runspec 0.76.2__tar.gz → 0.77.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. runspec-0.77.1/PKG-INFO +130 -0
  2. runspec-0.77.1/README.md +100 -0
  3. {runspec-0.76.2 → runspec-0.77.1}/pyproject.toml +6 -7
  4. {runspec-0.76.2 → runspec-0.77.1}/runspec/cli.py +4 -2
  5. runspec-0.77.1/runspec/compose.py +245 -0
  6. {runspec-0.76.2 → runspec-0.77.1}/runspec/loader.py +31 -1
  7. runspec-0.77.1/runspec.egg-info/PKG-INFO +130 -0
  8. {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/SOURCES.txt +3 -0
  9. runspec-0.77.1/tests/test_compose.py +418 -0
  10. runspec-0.76.2/PKG-INFO +0 -29
  11. runspec-0.76.2/runspec.egg-info/PKG-INFO +0 -29
  12. {runspec-0.76.2 → runspec-0.77.1}/runspec/__init__.py +0 -0
  13. {runspec-0.76.2 → runspec-0.77.1}/runspec/ansiblegen.py +0 -0
  14. {runspec-0.76.2 → runspec-0.77.1}/runspec/auditlog.py +0 -0
  15. {runspec-0.76.2 → runspec-0.77.1}/runspec/become.py +0 -0
  16. {runspec-0.76.2 → runspec-0.77.1}/runspec/denylist.py +0 -0
  17. {runspec-0.76.2 → runspec-0.77.1}/runspec/discovery.py +0 -0
  18. {runspec-0.76.2 → runspec-0.77.1}/runspec/emitutil.py +0 -0
  19. {runspec-0.76.2 → runspec-0.77.1}/runspec/env.py +0 -0
  20. {runspec-0.76.2 → runspec-0.77.1}/runspec/errors.py +0 -0
  21. {runspec-0.76.2 → runspec-0.77.1}/runspec/execute.py +0 -0
  22. {runspec-0.76.2 → runspec-0.77.1}/runspec/finder.py +0 -0
  23. {runspec-0.76.2 → runspec-0.77.1}/runspec/inbox.py +0 -0
  24. {runspec-0.76.2 → runspec-0.77.1}/runspec/inference.py +0 -0
  25. {runspec-0.76.2 → runspec-0.77.1}/runspec/jump.py +0 -0
  26. {runspec-0.76.2 → runspec-0.77.1}/runspec/logging_setup.py +0 -0
  27. {runspec-0.76.2 → runspec-0.77.1}/runspec/logs.py +0 -0
  28. {runspec-0.76.2 → runspec-0.77.1}/runspec/mock.py +0 -0
  29. {runspec-0.76.2 → runspec-0.77.1}/runspec/models.py +0 -0
  30. {runspec-0.76.2 → runspec-0.77.1}/runspec/parser.py +0 -0
  31. {runspec-0.76.2 → runspec-0.77.1}/runspec/py.typed +0 -0
  32. {runspec-0.76.2 → runspec-0.77.1}/runspec/rebrand.py +0 -0
  33. {runspec-0.76.2 → runspec-0.77.1}/runspec/rundeckgen.py +0 -0
  34. {runspec-0.76.2 → runspec-0.77.1}/runspec/runexec.py +0 -0
  35. {runspec-0.76.2 → runspec-0.77.1}/runspec/runsdb.py +0 -0
  36. {runspec-0.76.2 → runspec-0.77.1}/runspec/runspec.toml +0 -0
  37. {runspec-0.76.2 → runspec-0.77.1}/runspec/schemacheck.py +0 -0
  38. {runspec-0.76.2 → runspec-0.77.1}/runspec/serve.py +0 -0
  39. {runspec-0.76.2 → runspec-0.77.1}/runspec/stubgen.py +0 -0
  40. {runspec-0.76.2 → runspec-0.77.1}/runspec/testing.py +0 -0
  41. {runspec-0.76.2 → runspec-0.77.1}/runspec/types.py +0 -0
  42. {runspec-0.76.2 → runspec-0.77.1}/runspec/validator.py +0 -0
  43. {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/dependency_links.txt +0 -0
  44. {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/entry_points.txt +0 -0
  45. {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/requires.txt +0 -0
  46. {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/top_level.txt +0 -0
  47. {runspec-0.76.2 → runspec-0.77.1}/setup.cfg +0 -0
  48. {runspec-0.76.2 → runspec-0.77.1}/tests/__init__.py +0 -0
  49. {runspec-0.76.2 → runspec-0.77.1}/tests/conftest.py +0 -0
  50. {runspec-0.76.2 → runspec-0.77.1}/tests/test_agent.py +0 -0
  51. {runspec-0.76.2 → runspec-0.77.1}/tests/test_ansiblegen.py +0 -0
  52. {runspec-0.76.2 → runspec-0.77.1}/tests/test_audit.py +0 -0
  53. {runspec-0.76.2 → runspec-0.77.1}/tests/test_become.py +0 -0
  54. {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_discover.py +0 -0
  55. {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_emit.py +0 -0
  56. {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_init.py +0 -0
  57. {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_test.py +0 -0
  58. {runspec-0.76.2 → runspec-0.77.1}/tests/test_denylist.py +0 -0
  59. {runspec-0.76.2 → runspec-0.77.1}/tests/test_discovery.py +0 -0
  60. {runspec-0.76.2 → runspec-0.77.1}/tests/test_env.py +0 -0
  61. {runspec-0.76.2 → runspec-0.77.1}/tests/test_exec.py +0 -0
  62. {runspec-0.76.2 → runspec-0.77.1}/tests/test_finder.py +0 -0
  63. {runspec-0.76.2 → runspec-0.77.1}/tests/test_inbox.py +0 -0
  64. {runspec-0.76.2 → runspec-0.77.1}/tests/test_inference.py +0 -0
  65. {runspec-0.76.2 → runspec-0.77.1}/tests/test_jump.py +0 -0
  66. {runspec-0.76.2 → runspec-0.77.1}/tests/test_loader.py +0 -0
  67. {runspec-0.76.2 → runspec-0.77.1}/tests/test_log_resilience.py +0 -0
  68. {runspec-0.76.2 → runspec-0.77.1}/tests/test_logging_setup.py +0 -0
  69. {runspec-0.76.2 → runspec-0.77.1}/tests/test_logs.py +0 -0
  70. {runspec-0.76.2 → runspec-0.77.1}/tests/test_mock.py +0 -0
  71. {runspec-0.76.2 → runspec-0.77.1}/tests/test_models.py +0 -0
  72. {runspec-0.76.2 → runspec-0.77.1}/tests/test_parser.py +0 -0
  73. {runspec-0.76.2 → runspec-0.77.1}/tests/test_password.py +0 -0
  74. {runspec-0.76.2 → runspec-0.77.1}/tests/test_rebrand.py +0 -0
  75. {runspec-0.76.2 → runspec-0.77.1}/tests/test_run_as_enforce.py +0 -0
  76. {runspec-0.76.2 → runspec-0.77.1}/tests/test_run_summary.py +0 -0
  77. {runspec-0.76.2 → runspec-0.77.1}/tests/test_rundeckgen.py +0 -0
  78. {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb.py +0 -0
  79. {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb_events.py +0 -0
  80. {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb_sync.py +0 -0
  81. {runspec-0.76.2 → runspec-0.77.1}/tests/test_schemacheck.py +0 -0
  82. {runspec-0.76.2 → runspec-0.77.1}/tests/test_secret_argv.py +0 -0
  83. {runspec-0.76.2 → runspec-0.77.1}/tests/test_serve.py +0 -0
  84. {runspec-0.76.2 → runspec-0.77.1}/tests/test_serve_e2e.py +0 -0
  85. {runspec-0.76.2 → runspec-0.77.1}/tests/test_stubgen.py +0 -0
  86. {runspec-0.76.2 → runspec-0.77.1}/tests/test_testing.py +0 -0
  87. {runspec-0.76.2 → runspec-0.77.1}/tests/test_types.py +0 -0
  88. {runspec-0.76.2 → runspec-0.77.1}/tests/test_typing.py +0 -0
  89. {runspec-0.76.2 → runspec-0.77.1}/tests/test_validator.py +0 -0
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.4
2
+ Name: runspec
3
+ Version: 0.77.1
4
+ Summary: A language-agnostic, TOML-based interface specification for anything runnable
5
+ Author-email: Jason Finestone <jason@finestone.dev>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://runspec.app
8
+ Project-URL: Documentation, https://runspec.app
9
+ Project-URL: Repository, https://github.com/runspec-app/runspec
10
+ Project-URL: Issues, https://github.com/runspec-app/runspec/issues
11
+ Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md
12
+ Keywords: cli,argparse,arguments,agents,mcp,tools
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ Requires-Dist: tomli>=2.0; python_version < "3.11"
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=8.0; extra == "dev"
27
+ Requires-Dist: pytest-cov>=5.0; extra == "dev"
28
+ Requires-Dist: ruff==0.15.20; extra == "dev"
29
+ Requires-Dist: mypy>=1.10; extra == "dev"
30
+
31
+ # runspec
32
+
33
+ A language-agnostic, TOML-based interface specification for anything runnable:
34
+ scripts, applications and MCP tools, readable by people and AI agents without
35
+ conversion.
36
+
37
+ This is the Python package (the reference implementation). The Node pack is
38
+ [`runspec-node`](https://www.npmjs.com/package/runspec-node).
39
+ Full documentation is at **[runspec.app](https://runspec.app)**.
40
+
41
+ ## Why
42
+
43
+ Argument definitions are usually buried in code. When an AI agent needs to call a
44
+ script as a tool, the interface gets described a second time in a separate tool
45
+ or skills file.
46
+
47
+ An interface definition already *is* a tool description. runspec puts it in one
48
+ `runspec.toml` next to your code, and that one file drives argument parsing and
49
+ validation, `--help`, agent tool schemas, forms, and how much an agent may do
50
+ without asking (autonomy).
51
+
52
+ ## Install
53
+
54
+ ```bash
55
+ pip install runspec
56
+ ```
57
+
58
+ Python 3.10+. No runtime dependencies on Python 3.11+ (`tomli` on 3.10).
59
+
60
+ ## Quick start
61
+
62
+ Describe the runnable in `mypkg/runspec.toml`, inside your package directory:
63
+
64
+ ```toml
65
+ [greet]
66
+ description = "Greet someone from the command line"
67
+ autonomy = "autonomous"
68
+
69
+ [greet.args]
70
+ name = {type = "str"}
71
+ loud = {default = false}
72
+ times = {default = 1}
73
+ ```
74
+
75
+ Read the arguments in your code:
76
+
77
+ ```python
78
+ from runspec import parse
79
+
80
+ def main():
81
+ args = parse()
82
+ message = f"Hello, {args.name.value}!"
83
+ if args.loud.value:
84
+ message = message.upper()
85
+ for _ in range(args.times.value):
86
+ print(message)
87
+ ```
88
+
89
+ Register `greet = "mypkg.greet:main"` as a console script (the entry point name
90
+ matches the runnable name), install the package, and it runs as a normal CLI:
91
+
92
+ ```bash
93
+ greet --name Ada --loud --times 2
94
+ ```
95
+
96
+ List every runspec runnable in the environment, or serve them to an agent over
97
+ MCP:
98
+
99
+ ```bash
100
+ runspec local
101
+ runspec serve
102
+ ```
103
+
104
+ ## Features
105
+
106
+ - **Spec first**: write the interface before the implementation.
107
+ - **One call**: `parse()` finds the spec, validates the arguments and returns
108
+ them typed.
109
+ - **Self-describing values**: each argument carries its value plus its type,
110
+ default, options and where the value came from (CLI, environment or default).
111
+ - **Inference**: type, required and choice are inferred from defaults and
112
+ options.
113
+ - **Autonomy control**: declare whether an agent may run a tool freely, must ask
114
+ first, or must leave it to a person.
115
+ - **Agent discovery**: `runspec local` and `runspec serve` expose installed
116
+ runnables as tools.
117
+ - **Run logging and audit** on by default.
118
+ - **Language agnostic**: the same format for Python, Node, shell or anything else.
119
+
120
+ ## Links
121
+
122
+ - [Documentation](https://runspec.app)
123
+ - [Format specification](https://github.com/runspec-app/runspec/blob/main/spec/SPEC.md)
124
+ - [Changelog](https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md)
125
+ - [Source](https://github.com/runspec-app/runspec)
126
+ - [runspec-console](https://pypi.org/project/runspec-console/), the desktop console for runspec runnables
127
+
128
+ ## License
129
+
130
+ MIT
@@ -0,0 +1,100 @@
1
+ # runspec
2
+
3
+ A language-agnostic, TOML-based interface specification for anything runnable:
4
+ scripts, applications and MCP tools, readable by people and AI agents without
5
+ conversion.
6
+
7
+ This is the Python package (the reference implementation). The Node pack is
8
+ [`runspec-node`](https://www.npmjs.com/package/runspec-node).
9
+ Full documentation is at **[runspec.app](https://runspec.app)**.
10
+
11
+ ## Why
12
+
13
+ Argument definitions are usually buried in code. When an AI agent needs to call a
14
+ script as a tool, the interface gets described a second time in a separate tool
15
+ or skills file.
16
+
17
+ An interface definition already *is* a tool description. runspec puts it in one
18
+ `runspec.toml` next to your code, and that one file drives argument parsing and
19
+ validation, `--help`, agent tool schemas, forms, and how much an agent may do
20
+ without asking (autonomy).
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ pip install runspec
26
+ ```
27
+
28
+ Python 3.10+. No runtime dependencies on Python 3.11+ (`tomli` on 3.10).
29
+
30
+ ## Quick start
31
+
32
+ Describe the runnable in `mypkg/runspec.toml`, inside your package directory:
33
+
34
+ ```toml
35
+ [greet]
36
+ description = "Greet someone from the command line"
37
+ autonomy = "autonomous"
38
+
39
+ [greet.args]
40
+ name = {type = "str"}
41
+ loud = {default = false}
42
+ times = {default = 1}
43
+ ```
44
+
45
+ Read the arguments in your code:
46
+
47
+ ```python
48
+ from runspec import parse
49
+
50
+ def main():
51
+ args = parse()
52
+ message = f"Hello, {args.name.value}!"
53
+ if args.loud.value:
54
+ message = message.upper()
55
+ for _ in range(args.times.value):
56
+ print(message)
57
+ ```
58
+
59
+ Register `greet = "mypkg.greet:main"` as a console script (the entry point name
60
+ matches the runnable name), install the package, and it runs as a normal CLI:
61
+
62
+ ```bash
63
+ greet --name Ada --loud --times 2
64
+ ```
65
+
66
+ List every runspec runnable in the environment, or serve them to an agent over
67
+ MCP:
68
+
69
+ ```bash
70
+ runspec local
71
+ runspec serve
72
+ ```
73
+
74
+ ## Features
75
+
76
+ - **Spec first**: write the interface before the implementation.
77
+ - **One call**: `parse()` finds the spec, validates the arguments and returns
78
+ them typed.
79
+ - **Self-describing values**: each argument carries its value plus its type,
80
+ default, options and where the value came from (CLI, environment or default).
81
+ - **Inference**: type, required and choice are inferred from defaults and
82
+ options.
83
+ - **Autonomy control**: declare whether an agent may run a tool freely, must ask
84
+ first, or must leave it to a person.
85
+ - **Agent discovery**: `runspec local` and `runspec serve` expose installed
86
+ runnables as tools.
87
+ - **Run logging and audit** on by default.
88
+ - **Language agnostic**: the same format for Python, Node, shell or anything else.
89
+
90
+ ## Links
91
+
92
+ - [Documentation](https://runspec.app)
93
+ - [Format specification](https://github.com/runspec-app/runspec/blob/main/spec/SPEC.md)
94
+ - [Changelog](https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md)
95
+ - [Source](https://github.com/runspec-app/runspec)
96
+ - [runspec-console](https://pypi.org/project/runspec-console/), the desktop console for runspec runnables
97
+
98
+ ## License
99
+
100
+ MIT
@@ -1,9 +1,9 @@
1
1
  [project]
2
2
  name = "runspec"
3
- version = "0.76.2"
3
+ version = "0.77.1"
4
4
  description = "A language-agnostic, TOML-based interface specification for anything runnable"
5
5
  readme = "README.md"
6
- license = { file = "../../LICENSE" }
6
+ license = "MIT"
7
7
  authors = [
8
8
  { name = "Jason Finestone", email = "jason@finestone.dev" }
9
9
  ]
@@ -12,7 +12,6 @@ keywords = ["cli", "argparse", "arguments", "agents", "mcp", "tools"]
12
12
  classifiers = [
13
13
  "Development Status :: 3 - Alpha",
14
14
  "Intended Audience :: Developers",
15
- "License :: OSI Approved :: MIT License",
16
15
  "Programming Language :: Python :: 3",
17
16
  "Programming Language :: Python :: 3.10",
18
17
  "Programming Language :: Python :: 3.11",
@@ -41,12 +40,12 @@ runspec = "runspec.cli:main"
41
40
  [project.urls]
42
41
  Homepage = "https://runspec.app"
43
42
  Documentation = "https://runspec.app"
44
- Repository = "https://github.com/JasonFinestone/runspec"
45
- Issues = "https://github.com/JasonFinestone/runspec/issues"
46
- Changelog = "https://github.com/JasonFinestone/runspec/blob/main/CHANGELOG.md"
43
+ Repository = "https://github.com/runspec-app/runspec"
44
+ Issues = "https://github.com/runspec-app/runspec/issues"
45
+ Changelog = "https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md"
47
46
 
48
47
  [build-system]
49
- requires = ["setuptools>=69.0.2", "wheel"]
48
+ requires = ["setuptools>=77.0", "wheel"]
50
49
  build-backend = "setuptools.build_meta"
51
50
 
52
51
 
@@ -288,8 +288,10 @@ def _emit_meta(source: str, runnable: str, key: str) -> tuple[dict[str, Any], di
288
288
  Runnable-level `meta` is a pass-through the loader drops from the normalised
289
289
  spec (loader `_normalise_script`), so the emitter reads it straight from the
290
290
  raw TOML — keeping every platform-specific setting out of the core spec."""
291
+ from runspec.loader import read_resolved
292
+
291
293
  try:
292
- raw = _load_toml_file(Path(source))
294
+ raw = read_resolved(Path(source))
293
295
  except Exception:
294
296
  return {}, {}
295
297
  config_meta = (raw.get("config", {}) or {}).get("meta", {}) or {}
@@ -1878,7 +1880,7 @@ def _init_claude_md(project_root: Path, pkg_name: str) -> None:
1878
1880
  path.write_text(
1879
1881
  "# AI Context\n"
1880
1882
  "\n"
1881
- "This project uses [runspec](https://github.com/JasonFinestone/runspec) for CLI interfaces.\n"
1883
+ "This project uses [runspec](https://github.com/runspec-app/runspec) for CLI interfaces.\n"
1882
1884
  "\n"
1883
1885
  "## Key files\n"
1884
1886
  f"- `{pkg_name}/runspec.toml` — defines runnables: args, types, autonomy levels\n"
@@ -0,0 +1,245 @@
1
+ """
2
+ compose.py — resolve ``include`` and ``shared-args`` in a parsed runspec.toml.
3
+
4
+ Two authoring features that let a big ``runspec.toml`` be split up and stop
5
+ repeating itself. Both are resolved here, on the raw TOML dict, *before* the
6
+ loader normalises it, so every later stage (inference, validation, ``--help``,
7
+ ``serve``, stubs, emit, the console) sees an ordinary single-file spec.
8
+
9
+ ``include``
10
+ A runnable or command table may say ``include = "path/to/file.toml"``. The
11
+ file holds that table's body (``description``, ``args``, ``commands``, …,
12
+ with no ``[runnable.commands.x]`` prefix) and is merged into the table. The
13
+ path is relative to the file that names it and must stay inside the
14
+ directory holding ``runspec.toml``. Included files may include others; a
15
+ cycle is an error, and the chain is capped at ``MAX_INCLUDE_DEPTH`` files.
16
+ A key set both in the table and in the included file is an error.
17
+
18
+ ``shared-args`` / ``use``
19
+ ``[config.shared-args]``, ``[<runnable>.shared-args]`` and
20
+ ``[<…>.commands.<c>.shared-args]`` define args once. An arg written as
21
+ ``project = {use = "project"}`` takes that definition; any other keys next
22
+ to ``use`` override it. The nearest definition wins (the command's own,
23
+ then each parent up to the runnable, then ``[config]``). A definition can't
24
+ itself contain ``use``.
25
+
26
+ The functions are pure: file access goes through a ``reader`` callback that
27
+ takes a path relative to the ``runspec.toml`` directory (POSIX ``/``
28
+ separators) and returns the file's text, or ``None`` when it doesn't exist —
29
+ so the console can resolve a spec it fetched over SSH without a filesystem.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import copy
35
+ import difflib
36
+ import posixpath
37
+ import sys
38
+ from collections.abc import Callable
39
+ from pathlib import Path
40
+ from typing import Any
41
+
42
+ if sys.version_info >= (3, 11):
43
+ import tomllib
44
+ else:
45
+ import tomli as tomllib # type: ignore[no-redef]
46
+
47
+ Reader = Callable[[str], "str | None"]
48
+
49
+ ROOT_FILE = "runspec.toml"
50
+ MAX_INCLUDE_DEPTH = 8
51
+ SHARED_ARGS_KEY = "shared-args"
52
+
53
+
54
+ def resolve(data: dict[str, Any], reader: Reader | None = None, source: str = ROOT_FILE) -> dict[str, Any]:
55
+ """Return a copy of ``data`` with every ``include`` and ``use`` resolved and
56
+ every ``shared-args`` table removed.
57
+
58
+ A file that uses neither feature comes back equal to ``data``.
59
+
60
+ Args:
61
+ data: the parsed ``runspec.toml``.
62
+ reader: reads an included file by its package-relative POSIX path;
63
+ returns ``None`` when the file doesn't exist. Without a reader
64
+ an ``include`` is an error.
65
+ source: the package-relative name of the file ``data`` came from.
66
+
67
+ Raises:
68
+ ValueError: a bad include path, a missing or malformed included file,
69
+ a cycle, a key defined twice, or an unknown ``use`` name.
70
+ """
71
+ out = copy.deepcopy(data)
72
+ for name, table in out.items():
73
+ if name == "config" or not isinstance(table, dict):
74
+ continue
75
+ _resolve_includes(table, f"[{name}]", source, reader, (source,))
76
+ _resolve_uses(out)
77
+ return out
78
+
79
+
80
+ def has_include(text: str) -> bool:
81
+ """Cheap textual check: could this runspec.toml text use ``include``?
82
+
83
+ Used by the console to decide whether a scanned file needs its fragments.
84
+ False positives are harmless (a key named ``include`` inside ``args`` …).
85
+ """
86
+ for line in text.splitlines():
87
+ stripped = line.lstrip()
88
+ if stripped.startswith("include") and stripped[len("include") :].lstrip().startswith("="):
89
+ return True
90
+ return False
91
+
92
+
93
+ def fs_reader(root: Path) -> Reader:
94
+ """A reader over the real filesystem, rooted at the ``runspec.toml`` directory.
95
+
96
+ Refuses a path that resolves outside ``root`` (a symlink pointing out of the
97
+ package), so a wheel can only include its own files.
98
+ """
99
+ base = root.resolve()
100
+
101
+ def read(rel: str) -> str | None:
102
+ target = (base / rel).resolve()
103
+ if target != base and base not in target.parents:
104
+ raise ValueError(f"✗ include '{rel}' resolves outside the package directory ({base}).")
105
+ if not target.is_file():
106
+ return None
107
+ return target.read_text(encoding="utf-8")
108
+
109
+ return read
110
+
111
+
112
+ # ── include ────────────────────────────────────────────────────────────────────
113
+
114
+
115
+ def _include_path(value: Any, cur_file: str, where: str) -> str:
116
+ """The package-relative POSIX path an ``include`` value points at."""
117
+ if not isinstance(value, str) or not value.strip():
118
+ raise ValueError(f'✗ {where} include must be a path string, e.g. include = "commands/deploy.toml".')
119
+ raw = value.strip()
120
+ if "\\" in raw:
121
+ raise ValueError(f"✗ {where} include '{raw}': use '/' in include paths, not '\\'.")
122
+ if raw.startswith("/") or (len(raw) > 1 and raw[1] == ":"):
123
+ raise ValueError(f"✗ {where} include '{raw}' must be a relative path inside the package directory.")
124
+ if not raw.endswith(".toml"):
125
+ raise ValueError(f"✗ {where} include '{raw}' must name a .toml file.")
126
+ rel = posixpath.normpath(posixpath.join(posixpath.dirname(cur_file), raw))
127
+ if rel == ".." or rel.startswith("../"):
128
+ raise ValueError(f"✗ {where} include '{raw}' (in {cur_file}) points outside the package directory.")
129
+ return rel
130
+
131
+
132
+ def _read_fragment(rel: str, reader: Reader | None, where: str, cur_file: str) -> dict[str, Any]:
133
+ if reader is None:
134
+ raise ValueError(f"✗ {where} include '{rel}' can't be read here (no file access).")
135
+ text = reader(rel)
136
+ if text is None:
137
+ raise ValueError(f"✗ {where} include '{rel}' (named in {cur_file}) was not found.\n Is the file shipped in the package?")
138
+ try:
139
+ frag = tomllib.loads(text)
140
+ except tomllib.TOMLDecodeError as e:
141
+ raise ValueError(f"✗ {rel} is not valid TOML: {e}") from e
142
+ return frag
143
+
144
+
145
+ def _resolve_includes(
146
+ table: dict[str, Any],
147
+ where: str,
148
+ cur_file: str,
149
+ reader: Reader | None,
150
+ stack: tuple[str, ...],
151
+ ) -> None:
152
+ """Merge every ``include`` into ``table`` (in place), then recurse into its commands.
153
+
154
+ ``cur_file`` is the file ``table`` was written in; ``stack`` is the chain of
155
+ files from ``runspec.toml`` down to here, for cycle detection.
156
+ """
157
+ origin = dict.fromkeys(table, cur_file) # key → file it came from
158
+ file = cur_file
159
+ while "include" in table:
160
+ rel = _include_path(table.pop("include"), file, where)
161
+ if rel in stack:
162
+ chain = " → ".join((*stack[stack.index(rel) :], rel))
163
+ raise ValueError(f"✗ {where} include cycle: {chain}")
164
+ if len(stack) > MAX_INCLUDE_DEPTH:
165
+ raise ValueError(f"✗ {where} includes are nested more than {MAX_INCLUDE_DEPTH} files deep: {' → '.join((*stack, rel))}")
166
+ frag = _read_fragment(rel, reader, where, file)
167
+ dupes = sorted(k for k in frag if k in table)
168
+ if dupes:
169
+ keys = ", ".join(dupes)
170
+ raise ValueError(f"✗ {where} sets {keys} both in {origin[dupes[0]]} and in its include {rel}.\n Set each key in one place.")
171
+ table.update(frag)
172
+ origin.update(dict.fromkeys(frag, rel))
173
+ stack = (*stack, rel)
174
+ file = rel
175
+
176
+ commands = table.get("commands")
177
+ if isinstance(commands, dict):
178
+ cmd_file = origin.get("commands", file)
179
+ for name, sub in commands.items():
180
+ if isinstance(sub, dict):
181
+ _resolve_includes(sub, f"{where[:-1]}.commands.{name}]", cmd_file, reader, stack)
182
+
183
+
184
+ # ── shared-args / use ──────────────────────────────────────────────────────────
185
+
186
+
187
+ def _shared_defs(raw: Any, where: str) -> dict[str, dict[str, Any]]:
188
+ if raw is None:
189
+ return {}
190
+ if not isinstance(raw, dict):
191
+ raise ValueError(f"✗ {where} must be a table of arg definitions.")
192
+ defs: dict[str, dict[str, Any]] = {}
193
+ for name, value in raw.items():
194
+ definition = value if isinstance(value, dict) else {"default": value}
195
+ if "use" in definition:
196
+ raise ValueError(f"✗ {where} {name}: a shared arg can't itself use another one.")
197
+ defs[name] = definition
198
+ return defs
199
+
200
+
201
+ def _resolve_uses(data: dict[str, Any]) -> None:
202
+ config = data.get("config")
203
+ scopes: list[dict[str, dict[str, Any]]] = []
204
+ if isinstance(config, dict):
205
+ scopes.append(_shared_defs(config.pop(SHARED_ARGS_KEY, None), f"[config.{SHARED_ARGS_KEY}]"))
206
+ for name, table in data.items():
207
+ if name == "config" or not isinstance(table, dict):
208
+ continue
209
+ _resolve_uses_table(table, f"[{name}]", scopes)
210
+
211
+
212
+ def _resolve_uses_table(table: dict[str, Any], where: str, scopes: list[dict[str, dict[str, Any]]]) -> None:
213
+ if SHARED_ARGS_KEY in table:
214
+ scopes = [*scopes, _shared_defs(table.pop(SHARED_ARGS_KEY), f"{where[:-1]}.{SHARED_ARGS_KEY}]")]
215
+ args = table.get("args")
216
+ if isinstance(args, dict):
217
+ for arg_name, value in args.items():
218
+ if isinstance(value, dict) and "use" in value:
219
+ args[arg_name] = _use(value, arg_name, where, scopes)
220
+ commands = table.get("commands")
221
+ if isinstance(commands, dict):
222
+ for name, sub in commands.items():
223
+ if isinstance(sub, dict):
224
+ _resolve_uses_table(sub, f"{where[:-1]}.commands.{name}]", scopes)
225
+
226
+
227
+ def _use(value: dict[str, Any], arg_name: str, where: str, scopes: list[dict[str, dict[str, Any]]]) -> dict[str, Any]:
228
+ ref = value["use"]
229
+ if not isinstance(ref, str) or not ref:
230
+ raise ValueError(f'✗ {where} arg {arg_name}: use must name a shared arg, e.g. {{use = "{arg_name}"}}.')
231
+ for defs in reversed(scopes):
232
+ if ref in defs:
233
+ merged: dict[str, Any] = copy.deepcopy(defs[ref])
234
+ merged.update({k: v for k, v in value.items() if k != "use"})
235
+ return merged
236
+ known = sorted({n for defs in scopes for n in defs})
237
+ hint = ""
238
+ close = difflib.get_close_matches(ref, known, n=1)
239
+ if close:
240
+ hint = f"\n Did you mean '{close[0]}'?"
241
+ elif known:
242
+ hint = f"\n Shared args in scope: {', '.join(known)}"
243
+ else:
244
+ hint = f"\n No [{SHARED_ARGS_KEY}] table is in scope here."
245
+ raise ValueError(f"✗ {where} arg {arg_name}: unknown shared arg '{ref}'.{hint}")
@@ -20,11 +20,17 @@ if sys.version_info >= (3, 11):
20
20
  else:
21
21
  import tomli as tomllib # type: ignore[no-redef]
22
22
 
23
+ from runspec.compose import Reader, fs_reader, resolve
24
+
23
25
 
24
26
  def load_raw(config_path: Path) -> dict[str, Any]:
25
27
  """
26
28
  Read runspec.toml and return the normalised spec dict.
27
29
 
30
+ ``include`` and ``shared-args`` / ``use`` are resolved first (see
31
+ :mod:`runspec.compose`), so the result looks the same as if the spec had
32
+ been written as one file.
33
+
28
34
  Args:
29
35
  config_path: Path to runspec.toml
30
36
 
@@ -32,12 +38,36 @@ def load_raw(config_path: Path) -> dict[str, Any]:
32
38
  Normalised dict with keys: config, runnables
33
39
 
34
40
  Raises:
35
- ValueError: if the runspec section is malformed
41
+ ValueError: if the runspec section is malformed, or an include / use
42
+ can't be resolved
36
43
  FileNotFoundError: if config_path does not exist
37
44
  """
45
+ return normalise(read_resolved(config_path))
46
+
47
+
48
+ def read_resolved(config_path: Path) -> dict[str, Any]:
49
+ """Read runspec.toml as a raw TOML dict with ``include`` and ``use`` resolved.
50
+
51
+ For callers that need keys the normaliser drops (e.g. ``meta`` tables).
52
+ """
53
+ config_path = Path(config_path)
38
54
  with open(config_path, "rb") as f:
39
55
  data = tomllib.load(f)
56
+ return resolve(data, fs_reader(config_path.parent), config_path.name)
57
+
58
+
59
+ def load_text(text: str, reader: Reader | None = None) -> dict[str, Any]:
60
+ """:func:`load_raw` for runspec.toml *text*.
61
+
62
+ ``reader`` reads an included file by its path relative to the runspec.toml
63
+ directory (``None`` when missing); without one, a spec that uses
64
+ ``include`` raises ``ValueError``.
65
+ """
66
+ return normalise(resolve(tomllib.loads(text), reader))
67
+
40
68
 
69
+ def normalise(data: dict[str, Any]) -> dict[str, Any]:
70
+ """Normalise a parsed (and resolved) runspec.toml dict."""
41
71
  runnables_raw = {key: value for key, value in data.items() if key != "config" and isinstance(value, dict)}
42
72
 
43
73
  return {