runspec 0.76.2__tar.gz → 0.77.0__tar.gz

{runspec-0.76.2 → runspec-0.77.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: runspec
-Version: 0.76.2
+Version: 0.77.0
 Summary: A language-agnostic, TOML-based interface specification for anything runnable
 Author-email: Jason Finestone <jason@finestone.dev>
 Project-URL: Homepage, https://runspec.app
 Project-URL: Documentation, https://runspec.app
-Project-URL: Repository, https://github.com/JasonFinestone/runspec
-Project-URL: Issues, https://github.com/JasonFinestone/runspec/issues
-Project-URL: Changelog, https://github.com/JasonFinestone/runspec/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/runspec-app/runspec
+Project-URL: Issues, https://github.com/runspec-app/runspec/issues
+Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md
 Keywords: cli,argparse,arguments,agents,mcp,tools
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers

{runspec-0.76.2 → runspec-0.77.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runspec"
-version = "0.76.2"
+version = "0.77.0"
 description = "A language-agnostic, TOML-based interface specification for anything runnable"
 readme = "README.md"
 license = { file = "../../LICENSE" }
@@ -41,9 +41,9 @@ runspec = "runspec.cli:main"
 [project.urls]
 Homepage      = "https://runspec.app"
 Documentation = "https://runspec.app"
-Repository    = "https://github.com/JasonFinestone/runspec"
-Issues        = "https://github.com/JasonFinestone/runspec/issues"
-Changelog     = "https://github.com/JasonFinestone/runspec/blob/main/CHANGELOG.md"
+Repository    = "https://github.com/runspec-app/runspec"
+Issues        = "https://github.com/runspec-app/runspec/issues"
+Changelog     = "https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md"
 
 [build-system]
 requires      = ["setuptools>=69.0.2", "wheel"]

{runspec-0.76.2 → runspec-0.77.0}/runspec/cli.py

@@ -288,8 +288,10 @@ def _emit_meta(source: str, runnable: str, key: str) -> tuple[dict[str, Any], di
     Runnable-level `meta` is a pass-through the loader drops from the normalised
     spec (loader `_normalise_script`), so the emitter reads it straight from the
     raw TOML — keeping every platform-specific setting out of the core spec."""
+    from runspec.loader import read_resolved
+
     try:
-        raw = _load_toml_file(Path(source))
+        raw = read_resolved(Path(source))
     except Exception:
         return {}, {}
     config_meta = (raw.get("config", {}) or {}).get("meta", {}) or {}
@@ -1878,7 +1880,7 @@ def _init_claude_md(project_root: Path, pkg_name: str) -> None:
     path.write_text(
         "# AI Context\n"
         "\n"
-        "This project uses [runspec](https://github.com/JasonFinestone/runspec) for CLI interfaces.\n"
+        "This project uses [runspec](https://github.com/runspec-app/runspec) for CLI interfaces.\n"
         "\n"
         "## Key files\n"
         f"- `{pkg_name}/runspec.toml` — defines runnables: args, types, autonomy levels\n"

runspec-0.77.0/runspec/compose.py

@@ -0,0 +1,245 @@
+"""
+compose.py — resolve ``include`` and ``shared-args`` in a parsed runspec.toml.
+
+Two authoring features that let a big ``runspec.toml`` be split up and stop
+repeating itself. Both are resolved here, on the raw TOML dict, *before* the
+loader normalises it, so every later stage (inference, validation, ``--help``,
+``serve``, stubs, emit, the console) sees an ordinary single-file spec.
+
+``include``
+    A runnable or command table may say ``include = "path/to/file.toml"``. The
+    file holds that table's body (``description``, ``args``, ``commands``, …,
+    with no ``[runnable.commands.x]`` prefix) and is merged into the table. The
+    path is relative to the file that names it and must stay inside the
+    directory holding ``runspec.toml``. Included files may include others; a
+    cycle is an error, and the chain is capped at ``MAX_INCLUDE_DEPTH`` files.
+    A key set both in the table and in the included file is an error.
+
+``shared-args`` / ``use``
+    ``[config.shared-args]``, ``[<runnable>.shared-args]`` and
+    ``[<…>.commands.<c>.shared-args]`` define args once. An arg written as
+    ``project = {use = "project"}`` takes that definition; any other keys next
+    to ``use`` override it. The nearest definition wins (the command's own,
+    then each parent up to the runnable, then ``[config]``). A definition can't
+    itself contain ``use``.
+
+The functions are pure: file access goes through a ``reader`` callback that
+takes a path relative to the ``runspec.toml`` directory (POSIX ``/``
+separators) and returns the file's text, or ``None`` when it doesn't exist —
+so the console can resolve a spec it fetched over SSH without a filesystem.
+"""
+
+from __future__ import annotations
+
+import copy
+import difflib
+import posixpath
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+Reader = Callable[[str], "str | None"]
+
+ROOT_FILE = "runspec.toml"
+MAX_INCLUDE_DEPTH = 8
+SHARED_ARGS_KEY = "shared-args"
+
+
+def resolve(data: dict[str, Any], reader: Reader | None = None, source: str = ROOT_FILE) -> dict[str, Any]:
+    """Return a copy of ``data`` with every ``include`` and ``use`` resolved and
+    every ``shared-args`` table removed.
+
+    A file that uses neither feature comes back equal to ``data``.
+
+    Args:
+        data:   the parsed ``runspec.toml``.
+        reader: reads an included file by its package-relative POSIX path;
+                returns ``None`` when the file doesn't exist. Without a reader
+                an ``include`` is an error.
+        source: the package-relative name of the file ``data`` came from.
+
+    Raises:
+        ValueError: a bad include path, a missing or malformed included file,
+            a cycle, a key defined twice, or an unknown ``use`` name.
+    """
+    out = copy.deepcopy(data)
+    for name, table in out.items():
+        if name == "config" or not isinstance(table, dict):
+            continue
+        _resolve_includes(table, f"[{name}]", source, reader, (source,))
+    _resolve_uses(out)
+    return out
+
+
+def has_include(text: str) -> bool:
+    """Cheap textual check: could this runspec.toml text use ``include``?
+
+    Used by the console to decide whether a scanned file needs its fragments.
+    False positives are harmless (a key named ``include`` inside ``args`` …).
+    """
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("include") and stripped[len("include") :].lstrip().startswith("="):
+            return True
+    return False
+
+
+def fs_reader(root: Path) -> Reader:
+    """A reader over the real filesystem, rooted at the ``runspec.toml`` directory.
+
+    Refuses a path that resolves outside ``root`` (a symlink pointing out of the
+    package), so a wheel can only include its own files.
+    """
+    base = root.resolve()
+
+    def read(rel: str) -> str | None:
+        target = (base / rel).resolve()
+        if target != base and base not in target.parents:
+            raise ValueError(f"✗  include '{rel}' resolves outside the package directory ({base}).")
+        if not target.is_file():
+            return None
+        return target.read_text(encoding="utf-8")
+
+    return read
+
+
+# ── include ────────────────────────────────────────────────────────────────────
+
+
+def _include_path(value: Any, cur_file: str, where: str) -> str:
+    """The package-relative POSIX path an ``include`` value points at."""
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f'✗  {where} include must be a path string, e.g. include = "commands/deploy.toml".')
+    raw = value.strip()
+    if "\\" in raw:
+        raise ValueError(f"✗  {where} include '{raw}': use '/' in include paths, not '\\'.")
+    if raw.startswith("/") or (len(raw) > 1 and raw[1] == ":"):
+        raise ValueError(f"✗  {where} include '{raw}' must be a relative path inside the package directory.")
+    if not raw.endswith(".toml"):
+        raise ValueError(f"✗  {where} include '{raw}' must name a .toml file.")
+    rel = posixpath.normpath(posixpath.join(posixpath.dirname(cur_file), raw))
+    if rel == ".." or rel.startswith("../"):
+        raise ValueError(f"✗  {where} include '{raw}' (in {cur_file}) points outside the package directory.")
+    return rel
+
+
+def _read_fragment(rel: str, reader: Reader | None, where: str, cur_file: str) -> dict[str, Any]:
+    if reader is None:
+        raise ValueError(f"✗  {where} include '{rel}' can't be read here (no file access).")
+    text = reader(rel)
+    if text is None:
+        raise ValueError(f"✗  {where} include '{rel}' (named in {cur_file}) was not found.\n   Is the file shipped in the package?")
+    try:
+        frag = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise ValueError(f"✗  {rel} is not valid TOML: {e}") from e
+    return frag
+
+
+def _resolve_includes(
+    table: dict[str, Any],
+    where: str,
+    cur_file: str,
+    reader: Reader | None,
+    stack: tuple[str, ...],
+) -> None:
+    """Merge every ``include`` into ``table`` (in place), then recurse into its commands.
+
+    ``cur_file`` is the file ``table`` was written in; ``stack`` is the chain of
+    files from ``runspec.toml`` down to here, for cycle detection.
+    """
+    origin = dict.fromkeys(table, cur_file)  # key → file it came from
+    file = cur_file
+    while "include" in table:
+        rel = _include_path(table.pop("include"), file, where)
+        if rel in stack:
+            chain = " → ".join((*stack[stack.index(rel) :], rel))
+            raise ValueError(f"✗  {where} include cycle: {chain}")
+        if len(stack) > MAX_INCLUDE_DEPTH:
+            raise ValueError(f"✗  {where} includes are nested more than {MAX_INCLUDE_DEPTH} files deep: {' → '.join((*stack, rel))}")
+        frag = _read_fragment(rel, reader, where, file)
+        dupes = sorted(k for k in frag if k in table)
+        if dupes:
+            keys = ", ".join(dupes)
+            raise ValueError(f"✗  {where} sets {keys} both in {origin[dupes[0]]} and in its include {rel}.\n   Set each key in one place.")
+        table.update(frag)
+        origin.update(dict.fromkeys(frag, rel))
+        stack = (*stack, rel)
+        file = rel
+
+    commands = table.get("commands")
+    if isinstance(commands, dict):
+        cmd_file = origin.get("commands", file)
+        for name, sub in commands.items():
+            if isinstance(sub, dict):
+                _resolve_includes(sub, f"{where[:-1]}.commands.{name}]", cmd_file, reader, stack)
+
+
+# ── shared-args / use ──────────────────────────────────────────────────────────
+
+
+def _shared_defs(raw: Any, where: str) -> dict[str, dict[str, Any]]:
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise ValueError(f"✗  {where} must be a table of arg definitions.")
+    defs: dict[str, dict[str, Any]] = {}
+    for name, value in raw.items():
+        definition = value if isinstance(value, dict) else {"default": value}
+        if "use" in definition:
+            raise ValueError(f"✗  {where} {name}: a shared arg can't itself use another one.")
+        defs[name] = definition
+    return defs
+
+
+def _resolve_uses(data: dict[str, Any]) -> None:
+    config = data.get("config")
+    scopes: list[dict[str, dict[str, Any]]] = []
+    if isinstance(config, dict):
+        scopes.append(_shared_defs(config.pop(SHARED_ARGS_KEY, None), f"[config.{SHARED_ARGS_KEY}]"))
+    for name, table in data.items():
+        if name == "config" or not isinstance(table, dict):
+            continue
+        _resolve_uses_table(table, f"[{name}]", scopes)
+
+
+def _resolve_uses_table(table: dict[str, Any], where: str, scopes: list[dict[str, dict[str, Any]]]) -> None:
+    if SHARED_ARGS_KEY in table:
+        scopes = [*scopes, _shared_defs(table.pop(SHARED_ARGS_KEY), f"{where[:-1]}.{SHARED_ARGS_KEY}]")]
+    args = table.get("args")
+    if isinstance(args, dict):
+        for arg_name, value in args.items():
+            if isinstance(value, dict) and "use" in value:
+                args[arg_name] = _use(value, arg_name, where, scopes)
+    commands = table.get("commands")
+    if isinstance(commands, dict):
+        for name, sub in commands.items():
+            if isinstance(sub, dict):
+                _resolve_uses_table(sub, f"{where[:-1]}.commands.{name}]", scopes)
+
+
+def _use(value: dict[str, Any], arg_name: str, where: str, scopes: list[dict[str, dict[str, Any]]]) -> dict[str, Any]:
+    ref = value["use"]
+    if not isinstance(ref, str) or not ref:
+        raise ValueError(f'✗  {where} arg {arg_name}: use must name a shared arg, e.g. {{use = "{arg_name}"}}.')
+    for defs in reversed(scopes):
+        if ref in defs:
+            merged: dict[str, Any] = copy.deepcopy(defs[ref])
+            merged.update({k: v for k, v in value.items() if k != "use"})
+            return merged
+    known = sorted({n for defs in scopes for n in defs})
+    hint = ""
+    close = difflib.get_close_matches(ref, known, n=1)
+    if close:
+        hint = f"\n   Did you mean '{close[0]}'?"
+    elif known:
+        hint = f"\n   Shared args in scope: {', '.join(known)}"
+    else:
+        hint = f"\n   No [{SHARED_ARGS_KEY}] table is in scope here."
+    raise ValueError(f"✗  {where} arg {arg_name}: unknown shared arg '{ref}'.{hint}")

{runspec-0.76.2 → runspec-0.77.0}/runspec/loader.py

@@ -20,11 +20,17 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib  # type: ignore[no-redef]
 
+from runspec.compose import Reader, fs_reader, resolve
+
 
 def load_raw(config_path: Path) -> dict[str, Any]:
     """
     Read runspec.toml and return the normalised spec dict.
 
+    ``include`` and ``shared-args`` / ``use`` are resolved first (see
+    :mod:`runspec.compose`), so the result looks the same as if the spec had
+    been written as one file.
+
     Args:
         config_path: Path to runspec.toml
 
@@ -32,12 +38,36 @@ def load_raw(config_path: Path) -> dict[str, Any]:
         Normalised dict with keys: config, runnables
 
     Raises:
-        ValueError: if the runspec section is malformed
+        ValueError: if the runspec section is malformed, or an include / use
+            can't be resolved
         FileNotFoundError: if config_path does not exist
     """
+    return normalise(read_resolved(config_path))
+
+
+def read_resolved(config_path: Path) -> dict[str, Any]:
+    """Read runspec.toml as a raw TOML dict with ``include`` and ``use`` resolved.
+
+    For callers that need keys the normaliser drops (e.g. ``meta`` tables).
+    """
+    config_path = Path(config_path)
     with open(config_path, "rb") as f:
         data = tomllib.load(f)
+    return resolve(data, fs_reader(config_path.parent), config_path.name)
+
+
+def load_text(text: str, reader: Reader | None = None) -> dict[str, Any]:
+    """:func:`load_raw` for runspec.toml *text*.
+
+    ``reader`` reads an included file by its path relative to the runspec.toml
+    directory (``None`` when missing); without one, a spec that uses
+    ``include`` raises ``ValueError``.
+    """
+    return normalise(resolve(tomllib.loads(text), reader))
+
 
+def normalise(data: dict[str, Any]) -> dict[str, Any]:
+    """Normalise a parsed (and resolved) runspec.toml dict."""
     runnables_raw = {key: value for key, value in data.items() if key != "config" and isinstance(value, dict)}
 
     return {

{runspec-0.76.2 → runspec-0.77.0}/runspec.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: runspec
-Version: 0.76.2
+Version: 0.77.0
 Summary: A language-agnostic, TOML-based interface specification for anything runnable
 Author-email: Jason Finestone <jason@finestone.dev>
 Project-URL: Homepage, https://runspec.app
 Project-URL: Documentation, https://runspec.app
-Project-URL: Repository, https://github.com/JasonFinestone/runspec
-Project-URL: Issues, https://github.com/JasonFinestone/runspec/issues
-Project-URL: Changelog, https://github.com/JasonFinestone/runspec/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/runspec-app/runspec
+Project-URL: Issues, https://github.com/runspec-app/runspec/issues
+Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md
 Keywords: cli,argparse,arguments,agents,mcp,tools
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers

{runspec-0.76.2 → runspec-0.77.0}/runspec.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ runspec/ansiblegen.py
 runspec/auditlog.py
 runspec/become.py
 runspec/cli.py
+runspec/compose.py
 runspec/denylist.py
 runspec/discovery.py
 runspec/emitutil.py
@@ -48,6 +49,7 @@ tests/test_cli_discover.py
 tests/test_cli_emit.py
 tests/test_cli_init.py
 tests/test_cli_test.py
+tests/test_compose.py
 tests/test_denylist.py
 tests/test_discovery.py
 tests/test_env.py

runspec-0.77.0/tests/test_compose.py

@@ -0,0 +1,418 @@
+"""
+Tests for compose.py — ``include`` and ``shared-args`` / ``use``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from runspec.compose import has_include, resolve
+from runspec.loader import load_raw, load_text, normalise, read_resolved
+from runspec.parser import parse
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+REPO = Path(__file__).parents[4]
+FIXTURES = REPO / "tests" / "integration" / "fixtures"
+COMPOSED = FIXTURES / "composed"
+
+
+def _write(root: Path, files: dict[str, str]) -> Path:
+    for rel, text in files.items():
+        p = root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+    return root / "runspec.toml"
+
+
+def _repo_specs() -> list[Path]:
+    skip = {"node_modules", ".venv", "dist", "build"}
+    return sorted(p for p in REPO.glob("**/runspec.toml") if not skip & set(p.parts) and COMPOSED not in p.parents)
+
+
+# ── Existing specs are untouched ──────────────────────────────────────────────
+
+
+class TestExistingSpecsUnchanged:
+    """Every runspec.toml in the repo uses neither feature, so resolving it must
+    be a no-op and loading it must give exactly what the old loader gave."""
+
+    def test_found_specs(self):
+        assert len(_repo_specs()) > 20
+
+    @pytest.mark.parametrize("path", _repo_specs(), ids=lambda p: str(p.relative_to(REPO)))
+    def test_resolve_is_identity(self, path):
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+        assert resolve(data) == data
+
+    @pytest.mark.parametrize("path", _repo_specs(), ids=lambda p: str(p.relative_to(REPO)))
+    def test_load_raw_matches_plain_normalise(self, path):
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+        try:
+            expected = normalise(data)
+        except ValueError:
+            pytest.skip("deliberately invalid fixture")
+        assert load_raw(path) == expected
+
+
+class TestComplianceFixture:
+    """Shared with the Node pack: the composed fixture equals its flat twin."""
+
+    def test_composed_equals_flat(self):
+        assert load_raw(COMPOSED / "runspec.toml") == load_raw(FIXTURES / "composed_flat.toml")
+
+
+# ── include ───────────────────────────────────────────────────────────────────
+
+BASH_SCRIPTS = {
+    "runspec.toml": """
+[bash-scripts]
+description = "Collection of bash scripts"
+require-command = true
+
+[bash-scripts.shared-args]
+cluster = {type = "str", default = "main", description = "Cluster to act on"}
+
+[bash-scripts.commands.europe]
+include = "scripts/europe/europe.toml"
+""",
+    "scripts/europe/europe.toml": """
+description = "Scripts for the European estate"
+require-command = true
+
+[commands.find-nodes]
+include = "find-nodes.toml"
+
+[commands.delete-nodes]
+include = "delete-nodes.toml"
+""",
+    "scripts/europe/find-nodes.toml": """
+description = "Find nodes matching a pattern"
+autonomy = "autonomous"
+
+[args]
+pattern = {description = "Node name glob"}
+cluster = {use = "cluster"}
+""",
+    "scripts/europe/delete-nodes.toml": """
+description = "Delete nodes"
+autonomy = "confirm"
+
+[args]
+pattern = {description = "Node name glob"}
+cluster = {use = "cluster", required = true}
+""",
+}
+
+
+class TestInclude:
+    def test_nested_includes_resolve(self, tmp_path):
+        spec = load_raw(_write(tmp_path, BASH_SCRIPTS))["runnables"]["bash-scripts"]
+        europe = spec["commands"]["europe"]
+        assert europe["description"] == "Scripts for the European estate"
+        assert europe["require_command"] is True
+        find = europe["commands"]["find-nodes"]
+        assert find["autonomy"] == "autonomous"
+        assert find["args"]["cluster"]["default"] == "main"
+        assert find["args"]["cluster"]["description"] == "Cluster to act on"
+        delete = europe["commands"]["delete-nodes"]
+        assert delete["args"]["cluster"]["required"] is True
+        assert delete["args"]["cluster"]["default"] == "main"
+
+    def test_same_as_single_file(self, tmp_path):
+        split = load_raw(_write(tmp_path / "split", BASH_SCRIPTS))
+        single = load_raw(
+            _write(
+                tmp_path / "single",
+                {
+                    "runspec.toml": """
+[bash-scripts]
+description = "Collection of bash scripts"
+require-command = true
+
+[bash-scripts.commands.europe]
+description = "Scripts for the European estate"
+require-command = true
+
+[bash-scripts.commands.europe.commands.find-nodes]
+description = "Find nodes matching a pattern"
+autonomy = "autonomous"
+
+[bash-scripts.commands.europe.commands.find-nodes.args]
+pattern = {description = "Node name glob"}
+cluster = {type = "str", default = "main", description = "Cluster to act on"}
+
+[bash-scripts.commands.europe.commands.delete-nodes]
+description = "Delete nodes"
+autonomy = "confirm"
+
+[bash-scripts.commands.europe.commands.delete-nodes.args]
+pattern = {description = "Node name glob"}
+cluster = {type = "str", default = "main", description = "Cluster to act on", required = true}
+"""
+                },
+            )
+        )
+        assert split == single
+
+    def test_parse_runs_through_includes(self, tmp_path):
+        cfg = _write(tmp_path, BASH_SCRIPTS)
+        args = parse(
+            script_name="bash-scripts",
+            argv=["europe", "delete-nodes", "--pattern", "web*", "--cluster", "eu-1"],
+            config_path=cfg,
+        )
+        assert args.runspec_command_path == ["europe", "delete-nodes"]
+        assert args.pattern.value == "web*"
+        assert args.cluster.value == "eu-1"
+
+    def test_runnable_level_include(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[disk-usage]\ninclude = "runnables/disk-usage.toml"\n',
+                "runnables/disk-usage.toml": 'description = "Show disk usage"\n[args]\npath = {default = "/"}\n',
+            },
+        )
+        spec = load_raw(cfg)["runnables"]["disk-usage"]
+        assert spec["description"] == "Show disk usage"
+        assert spec["args"]["path"]["default"] == "/"
+
+    def test_paths_relative_to_including_file(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[r]\n[r.commands.a]\ninclude = "a/a.toml"\n',
+                "a/a.toml": '[commands.b]\ninclude = "../b/b.toml"\n',
+                "b/b.toml": 'description = "from b"\n',
+            },
+        )
+        assert load_raw(cfg)["runnables"]["r"]["commands"]["a"]["commands"]["b"]["description"] == "from b"
+
+    def test_chained_include(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[r]\ninclude = "one.toml"\n',
+                "one.toml": 'description = "one"\ninclude = "two.toml"\n',
+                "two.toml": 'autonomy = "autonomous"\n',
+            },
+        )
+        spec = load_raw(cfg)["runnables"]["r"]
+        assert (spec["description"], spec["autonomy"]) == ("one", "autonomous")
+
+    def test_meta_survives_for_emit(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[r]\ninclude = "r.toml"\n',
+                "r.toml": '[meta.rundeck]\nschedule = "0 2 * * *"\n',
+            },
+        )
+        assert read_resolved(cfg)["r"]["meta"]["rundeck"]["schedule"] == "0 2 * * *"
+
+    def test_cycle_is_an_error(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[r]\n[r.commands.a]\ninclude = "a.toml"\n',
+                "a.toml": '[commands.b]\ninclude = "b.toml"\n',
+                "b.toml": '[commands.c]\ninclude = "a.toml"\n',
+            },
+        )
+        with pytest.raises(ValueError, match=r"cycle: a\.toml → b\.toml → a\.toml"):
+            load_raw(cfg)
+
+    def test_including_runspec_toml_is_a_cycle(self, tmp_path):
+        cfg = _write(tmp_path, {"runspec.toml": '[r]\ninclude = "runspec.toml"\n'})
+        with pytest.raises(ValueError, match="cycle"):
+            load_raw(cfg)
+
+    def test_depth_cap(self, tmp_path):
+        files = {"runspec.toml": '[r]\ninclude = "f1.toml"\n'}
+        for i in range(1, 11):
+            files[f"f{i}.toml"] = f'include = "f{i + 1}.toml"\n'
+        files["f11.toml"] = 'description = "deep"\n'
+        with pytest.raises(ValueError, match="more than 8 files deep"):
+            load_raw(_write(tmp_path, files))
+
+    def test_duplicate_key_is_an_error(self, tmp_path):
+        cfg = _write(
+            tmp_path,
+            {
+                "runspec.toml": '[r]\ndescription = "here"\ninclude = "r.toml"\n',
+                "r.toml": 'description = "there"\n',
+            },
+        )
+        with pytest.raises(ValueError, match="sets description both in runspec.toml and in its include r.toml"):
+            load_raw(cfg)
+
+    def test_missing_file(self, tmp_path):
+        cfg = _write(tmp_path, {"runspec.toml": '[r]\ninclude = "nope.toml"\n'})
+        with pytest.raises(ValueError, match="nope.toml.*not found"):
+            load_raw(cfg)
+
+    def test_invalid_toml_in_fragment(self, tmp_path):
+        cfg = _write(tmp_path, {"runspec.toml": '[r]\ninclude = "bad.toml"\n', "bad.toml": "x = = 1\n"})
+        with pytest.raises(ValueError, match="bad.toml is not valid TOML"):
+            load_raw(cfg)
+
+    @pytest.mark.parametrize(
+        "path, message",
+        [
+            ("../outside.toml", "outside the package"),
+            ("a/../../outside.toml", "outside the package"),
+            ("/etc/x.toml", "relative path"),
+            ("C:/x.toml", "relative path"),
+            ("a\\\\b.toml", "use '/'"),
+            ("notes.txt", "must name a .toml file"),
+        ],
+    )
+    def test_bad_paths(self, tmp_path, path, message):
+        cfg = _write(tmp_path, {"runspec.toml": f'[r]\ninclude = "{path}"\n'})
+        with pytest.raises(ValueError, match=message):
+            load_raw(cfg)
+
+    def test_non_string_include(self, tmp_path):
+        cfg = _write(tmp_path, {"runspec.toml": "[r]\ninclude = 3\n"})
+        with pytest.raises(ValueError, match="must be a path string"):
+            load_raw(cfg)
+
+    def test_symlink_out_of_package_refused(self, tmp_path):
+        outside = tmp_path / "outside.toml"
+        outside.write_text('description = "x"\n')
+        pkg = tmp_path / "pkg"
+        cfg = _write(pkg, {"runspec.toml": '[r]\ninclude = "link.toml"\n'})
+        try:
+            (pkg / "link.toml").symlink_to(outside)
+        except OSError:
+            pytest.skip("symlinks not available")
+        with pytest.raises(ValueError, match="outside the package directory"):
+            load_raw(cfg)
+
+    def test_load_text_with_reader(self):
+        files = {"cmd/x.toml": 'description = "x"\n'}
+        spec = load_text('[r]\n[r.commands.x]\ninclude = "cmd/x.toml"\n', files.get)
+        assert spec["runnables"]["r"]["commands"]["x"]["description"] == "x"
+
+    def test_load_text_without_reader(self):
+        with pytest.raises(ValueError, match="no file access"):
+            load_text('[r]\ninclude = "x.toml"\n')
+
+    def test_has_include(self):
+        assert has_include('[r]\ninclude = "x.toml"\n')
+        assert has_include('[r]\n  include="x.toml"\n')
+        assert not has_include('[r]\ndescription = "include = x"\n')
+        assert not has_include("[r]\nincluded = 1\n")
+
+
+# ── shared-args / use ─────────────────────────────────────────────────────────
+
+
+class TestSharedArgs:
+    def test_runnable_level(self):
+        spec = load_text(
+            """
+[gitlab.shared-args]
+project = {type = "str", required = false, env = "GITLAB_PROJECT", description = "Project id or path"}
+
+[gitlab.commands.get-issue.args]
+project = {use = "project"}
+
+[gitlab.commands.create-issue.args]
+project = {use = "project", required = true}
+source-project = {use = "project"}
+"""
+        )["runnables"]["gitlab"]
+        get_issue = spec["commands"]["get-issue"]["args"]["project"]
+        assert get_issue["required"] is False
+        assert get_issue["env"] == ["GITLAB_PROJECT"]
+        create = spec["commands"]["create-issue"]["args"]
+        assert create["project"]["required"] is True
+        assert create["project"]["description"] == "Project id or path"
+        assert create["source-project"]["name"] == "source-project"
+        assert create["source-project"]["env"] == ["GITLAB_PROJECT"]
+
+    def test_config_level_across_runnables(self):
+        spec = load_text(
+            """
+[config.shared-args]
+proxy = {required = false, description = "HTTP proxy"}
+
+[cert-check.args]
+proxy = {use = "proxy"}
+
+[http-check.args]
+proxy = {use = "proxy"}
+"""
+        )
+        for name in ("cert-check", "http-check"):
+            assert spec["runnables"][name]["args"]["proxy"]["description"] == "HTTP proxy"
+
+    def test_nearest_definition_wins(self):
+        spec = load_text(
+            """
+[config.shared-args]
+limit = 10
+
+[r.shared-args]
+limit = 20
+
+[r.commands.a.shared-args]
+limit = 30
+
+[r.commands.a.args]
+limit = {use = "limit"}
+
+[r.commands.b.args]
+limit = {use = "limit"}
+"""
+        )["runnables"]["r"]["commands"]
+        assert spec["a"]["args"]["limit"]["default"] == 30
+        assert spec["b"]["args"]["limit"]["default"] == 20
+
+    def test_runnable_args_can_use(self):
+        spec = load_text('[r.shared-args]\nverbose = false\n[r.args]\nverbose = {use = "verbose"}\n')
+        assert spec["runnables"]["r"]["args"]["verbose"]["default"] is False
+
+    def test_shared_args_table_removed(self):
+        data = tomllib.loads('[config.shared-args]\nx = 1\n[r.shared-args]\ny = 2\n[r.args]\nx = {use = "x"}\n')
+        out = resolve(data)
+        assert "shared-args" not in out["config"]
+        assert "shared-args" not in out["r"]
+        assert out["r"]["args"]["x"] == {"default": 1}
+
+    def test_unused_definitions_are_fine(self):
+        spec = load_text("[r.shared-args]\nx = 1\n[r.args]\ny = 2\n")
+        assert list(spec["runnables"]["r"]["args"]) == ["y"]
+
+    def test_unknown_name_suggests(self):
+        with pytest.raises(ValueError, match="(?s)unknown shared arg 'projet'.*Did you mean 'project'"):
+            load_text('[r.shared-args]\nproject = "x"\n[r.args]\np = {use = "projet"}\n')
+
+    def test_unknown_name_without_any_table(self):
+        with pytest.raises(ValueError, match=r"No \[shared-args\] table"):
+            load_text('[r.args]\np = {use = "project"}\n')
+
+    def test_sibling_scope_not_visible(self):
+        with pytest.raises(ValueError, match="unknown shared arg 'x'"):
+            load_text('[r.commands.a.shared-args]\nx = 1\n[r.commands.b.args]\nx = {use = "x"}\n')
+
+    def test_definition_cannot_use(self):
+        with pytest.raises(ValueError, match="can't itself use"):
+            load_text('[r.shared-args]\na = 1\nb = {use = "a"}\n')
+
+    def test_use_must_be_a_name(self):
+        with pytest.raises(ValueError, match="use must name a shared arg"):
+            load_text("[r.shared-args]\na = 1\n[r.args]\na = {use = 3}\n")
+
+    def test_definitions_not_shared_between_uses(self):
+        spec = load_text('[r.shared-args]\nm = {options = ["a", "b"]}\n[r.commands.x.args]\nm = {use = "m"}\n[r.commands.y.args]\nm = {use = "m"}\n')["runnables"]["r"]["commands"]
+        spec["x"]["args"]["m"]["options"].append("c")
+        assert spec["y"]["args"]["m"]["options"] == ["a", "b"]