runspec 0.75.2__tar.gz → 0.76.0__tar.gz

{runspec-0.75.2 → runspec-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec
-Version: 0.75.2
+Version: 0.76.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

{runspec-0.75.2 → runspec-0.76.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runspec"
-version = "0.75.2"
+version = "0.76.0"
 description = "A language-agnostic, TOML-based interface specification for anything runnable"
 readme = "README.md"
 license = { file = "../../LICENSE" }

{runspec-0.75.2 → runspec-0.76.0}/runspec/ansiblegen.py

@@ -24,6 +24,8 @@ Design points
   `check_mode` short-circuits to `changed=false` (conservative).
 - **Non-interactive:** the module injects `RUNSPEC_AUTONOMY=autonomous` so a
   `confirm` runnable runs in a playbook without prompting.
+- **Label:** it sets `RUNSPEC_LABEL=ansible`, so the run is labelled `ansible`
+  in the runs index.
 """
 
 from __future__ import annotations
@@ -279,6 +281,7 @@ def build_command(params):
 def build_env(params):
     env = dict(os.environ)
     env["RUNSPEC_AUTONOMY"] = "autonomous"
+    env["RUNSPEC_LABEL"] = "ansible"
     for param, kind, _cli, _position, secret_env in ARGS:
         if kind == "secret" and params.get(param) is not None:
             env[secret_env] = str(params[param])

{runspec-0.75.2 → runspec-0.76.0}/runspec/inbox.py

@@ -482,10 +482,10 @@ def row_from_records(run_id: str, records: list[dict[str, Any]]) -> dict[str, An
     row["runnable"] = start.get("runnable") or src.get("runnable") or ""
     cmd = start.get("command_path") or src.get("command_path") or []
     row["command"] = " ".join(cmd) if isinstance(cmd, list) else str(cmd or "")
-    for k in ("user", "user_target", "agent", "trigger", "skill", "autonomy"):
+    for k in ("user", "user_target", "agent", "trigger", "skill", "autonomy", "label"):
         v = start.get(k)
         row[k] = v if not _empty(v) else src.get(k)
-    for k in ("pid", "host", "proc_start", "run_as", "label", "exec_uid", "venv"):
+    for k in ("pid", "host", "proc_start", "run_as", "exec_uid", "venv"):
         row[k] = start.get(k)
     args = start.get("invocation_args") or src.get("invocation_args") or {}
     row["args"] = args if isinstance(args, dict) else {}

{runspec-0.75.2 → runspec-0.76.0}/runspec/logging_setup.py

@@ -155,6 +155,7 @@ def configure_logging(
     agent: bool = False,
     trigger: str = "",
     skill: str = "",
+    label: str = "",
     command_path: list[str] | None = None,
     invocation_args: dict[str, Any] | None = None,
     history_cfg: dict[str, Any] | None = None,
@@ -366,6 +367,8 @@ def configure_logging(
             # The saved skill that drove this run (RUNSPEC_SKILL), "" otherwise — a
             # further provenance axis alongside trigger/agent.
             "skill": skill,
+            # Where the run was launched from (RUNSPEC_LABEL, "cli" when unset).
+            "label": label,
             "command_path": list(command_path or []),
             "exception": None,
             "emitted": False,
@@ -516,6 +519,7 @@ def _write_run_start(state: dict[str, Any], *, indexed: bool) -> None:
                 "agent": state["agent"],
                 "trigger": state["trigger"],
                 "skill": state.get("skill", ""),
+                "label": state.get("label") or None,
                 "autonomy": state["autonomy"],
                 "run_as": state.get("run_as") or "",
                 "invocation_args": {k: v["value"] for k, v in state.get("invocation_args", {}).items()},
@@ -1004,6 +1008,7 @@ def _begin_history_row(state: dict[str, Any], log_dir: Path, log_file: str) -> N
                 "agent": state["agent"],
                 "trigger": state["trigger"],
                 "skill": state.get("skill", ""),
+                "label": state.get("label") or None,
                 "autonomy": state["autonomy"],
                 "pid": os.getpid(),
                 "host": socket.gethostname(),
@@ -1053,6 +1058,7 @@ def _emit_run_summary() -> None:
                     "agent": state["agent"],
                     "trigger": state["trigger"],
                     "skill": state.get("skill", ""),
+                    "label": state.get("label") or None,
                     "autonomy": state["autonomy"],
                     "exception": state["exception"],
                     "events": dict(state["counter"].counts),

{runspec-0.75.2 → runspec-0.76.0}/runspec/models.py

@@ -222,7 +222,7 @@ class RunSpec:
         you don't have to guard every access:
 
             since = args.get("since").value        # None if not in this path
-            symbol = args.get("symbol", "VOD.L").value
+            symbol = args.get("symbol", "ABC123").value
 
         When the arg is in the active command path its real Arg is returned;
         otherwise a synthetic ``not_set`` Arg wrapping ``default`` is returned,

{runspec-0.75.2 → runspec-0.76.0}/runspec/parser.py

@@ -265,7 +265,14 @@ def _parse_impl(
     # The skill (saved runbook) that drove this run, when started from the console's
     # `$` skills menu. Recorded in run_summary as `extra.skill` — another provenance
     # axis alongside `trigger`/`agent`, so History/Analytics can attribute runs to it.
-    skill = os.environ.get("RUNSPEC_SKILL", "").strip()
+    # The console sends the runbook id as RUNSPEC_RUNBOOK (skills were renamed to
+    # runbooks); RUNSPEC_SKILL is the older spelling, still honoured.
+    skill = (os.environ.get("RUNSPEC_SKILL", "") or os.environ.get("RUNSPEC_RUNBOOK", "")).strip()
+    # Where the run was launched from (RUNSPEC_LABEL, set by each launcher: the
+    # console, `runspec serve`, a Rundeck job, ...); a run nobody labelled was
+    # started from a shell, cron or a script, so it records "cli". Stored in the
+    # runs index's `label` column, the one `runspec exec --label` fills.
+    label = os.environ.get("RUNSPEC_LABEL", "").strip() or "cli"
     # A `runspec exec` wrapper's run id (RUNSPEC_RUN_ID). Taken — and removed from
     # the environment — here, unconditionally, so it never leaks to runnables this
     # one shells out to, even when this runnable has no [config.logging].
@@ -341,6 +348,7 @@ def _parse_impl(
             agent=agent,
             trigger=trigger,
             skill=skill,
+            label=label,
             command_path=command_path,
             invocation_args=invocation_args,
             history_cfg=config.get("history"),

{runspec-0.75.2 → runspec-0.76.0}/runspec/rundeckgen.py

@@ -241,6 +241,11 @@ def rd_option_token(name: str) -> str:
     return f"@option.{name}@"
 
 
+# Recorded as the run's label in the runs index (SPEC "Run labels"), so History
+# shows the run came from Rundeck.
+_LABEL_ASSIGN = "RUNSPEC_LABEL=rundeck"
+
+
 def _env_prelude_argv(invocation: str, venv: str | None) -> list[str]:
     """The env-prelude wrapper for a run behind `sudo` (SPEC "Command
     building"): the venv's own `bin/python` when the venv is known, so a sudoers
@@ -273,13 +278,15 @@ def _exists_check(runnable: str, invocation: str, venv: str | None, run_as: str
 
 def _direct(env_vars: list[tuple[str, str]], cmd: str, indent: str = "") -> list[str]:
     """Export the non-empty values (an empty option stays unset so the
-    runnable's own default applies) and exec the binary as this account."""
+    runnable's own default applies) and the run's label, and exec the binary as
+    this account."""
     lines: list[str] = []
     if env_vars:
         names = " ".join(var for var, _ in env_vars)
         lines.append(f"{indent}for rs_var in {names}; do")
         lines.append(f'{indent}  if [ -n "${{!rs_var}}" ]; then export "$rs_var"; else unset "$rs_var"; fi')
         lines.append(f"{indent}done")
+    lines.append(f"{indent}export {_LABEL_ASSIGN}")
     lines.append(f"{indent}exec {cmd}")
     return lines
 
@@ -324,7 +331,6 @@ def render_script(
     path.
     """
     env_vars = [(secret_env_var(runnable, name), name) for name in args]
-    names = " ".join(var for var, _ in env_vars)
 
     lines = ["#!/bin/bash", _PRIVATE, _GUARD, "set -e"]
     for var, name in env_vars:
@@ -366,15 +372,20 @@ def render_script(
     lines.append("fi")
 
     become = 'sudo -n -u "$rs_user"'
-    if not env_vars:
+    if not env_vars and not venv:
+        # Nothing to send but the label, and the `sh` prelude would need a
+        # sudoers rule that allows a shell: run the binary directly (the run then
+        # records the "cli" label).
         lines.append(f"exec {become} {cmd}")
         return _finish(lines)
 
     prelude = PY_ENV_PRELUDE if venv else ENV_PRELUDE
     lines.append(f"RS_PRELUDE='{prelude}'")
     lines.append(_FRAME_FUNC)
+    lines.append(_LABEL_ASSIGN)
     wrapped = " ".join([*_env_prelude_argv(invocation, venv), cmd])
-    lines.append(f"rs_frame {names} | {become} {wrapped}")
+    frame_vars = " ".join([*(var for var, _ in env_vars), "RUNSPEC_LABEL"])
+    lines.append(f"rs_frame {frame_vars} | {become} {wrapped}")
     return _finish(lines)
 
 

{runspec-0.75.2 → runspec-0.76.0}/runspec/runexec.py

@@ -199,6 +199,11 @@ def exec_runnable(
     out_stream = stdout if stdout is not None else sys.stdout
     err_stream = stderr if stderr is not None else sys.stderr
     label = label or None
+    # The label recorded on the run and handed to the child: --label, else the
+    # launcher's RUNSPEC_LABEL, else "cli" (what the child's parse() would record).
+    # `label` alone stays the --skip-if-running key, so an unlabelled run never
+    # waits on every other unlabelled run.
+    run_label = label or os.environ.get("RUNSPEC_LABEL", "").strip() or "cli"
     trigger = trigger if trigger is not None else os.environ.get("RUNSPEC_TRIGGER", "").strip()
     run_id = str(uuid.uuid4())
     start = _now()
@@ -237,7 +242,7 @@ def exec_runnable(
         "pid": os.getpid(),
         "host": socket.gethostname(),
         "proc_start": runsdb.proc_start_token(),
-        "label": label,
+        "label": run_label,
         "run_as": (spec or {}).get("run_as") or None,
         "os_user": inbox.effective_user() or None,
         "source": "direct",
@@ -268,7 +273,7 @@ def exec_runnable(
                 _record(
                     message,
                     run_id,
-                    {"event": "exec_result", "status": status, "exit_code": exit_code, "duration_ms": 0, "label": label, "trigger": trigger, "reason": reason},
+                    {"event": "exec_result", "status": status, "exit_code": exit_code, "duration_ms": 0, "label": run_label, "trigger": trigger, "reason": reason},
                     level="INFO" if status == "skipped" else "ERROR",
                 )
             ],
@@ -322,6 +327,7 @@ def exec_runnable(
             child_env["RUNSPEC_RUN_LOG"] = str(box.path)
         if trigger:
             child_env["RUNSPEC_TRIGGER"] = trigger
+        child_env["RUNSPEC_LABEL"] = run_label
         cmd, extra_env, frame = build_command(spec, list(argv), child_env)
         capture = capture_bytes > 0
         t0 = time.monotonic()
@@ -337,7 +343,7 @@ def exec_runnable(
             if write_row:  # drop the running placeholder; record the launch failure
                 runsdb.finish_run(log_dir, run_id, exit_code=EXIT_NOT_EXECUTABLE, duration_ms=0, status="failed", cfg=history_cfg, runnable=name)
             log_path = box.path if box is not None else _log_file_for(log_dir, None, name, start, run_id)
-            result = {"event": "exec_result", "status": "failed", "exit_code": EXIT_NOT_EXECUTABLE, "duration_ms": 0, "label": label, "trigger": trigger, "reason": "launch_error"}
+            result = {"event": "exec_result", "status": "failed", "exit_code": EXIT_NOT_EXECUTABLE, "duration_ms": 0, "label": run_label, "trigger": trigger, "reason": "launch_error"}
             sink.write(log_path, [_record(f"could not start '{name}': {exc}", run_id, result, level="ERROR")])
             with contextlib.suppress(Exception):
                 err_stream.write(f"runspec exec: could not start '{name}': {exc}\n")
@@ -381,7 +387,7 @@ def exec_runnable(
         if write_row and row is not None and row.get("pid") == os.getpid() and row.get("status") == "running":
             # The child never touched our row — no logging, failed before logging,
             # or an older runspec that minted its own id. Adopt the latter.
-            adopted = runsdb.adopt_child_row(log_dir, run_id, runnable=name, since_ts=start_iso, label=label)
+            adopted = runsdb.adopt_child_row(log_dir, run_id, runnable=name, since_ts=start_iso, label=run_label)
             if adopted:
                 target_id = adopted
         if write_row:
@@ -405,7 +411,7 @@ def exec_runnable(
             _record(
                 result_msg,
                 target_id,
-                {"event": "exec_result", "status": status, "exit_code": rc, "duration_ms": duration_ms, "label": label, "trigger": trigger, "reason": "timeout" if timed_out else ""},
+                {"event": "exec_result", "status": status, "exit_code": rc, "duration_ms": duration_ms, "label": run_label, "trigger": trigger, "reason": "timeout" if timed_out else ""},
                 level="INFO" if rc == 0 else "ERROR",
             )
         )

{runspec-0.75.2 → runspec-0.76.0}/runspec/runsdb.py

@@ -657,13 +657,19 @@ def _normalise_row(row: dict[str, Any]) -> dict[str, Any]:
 _HAS_UPSERT = sqlite3.sqlite_version_info >= (3, 24, 0)
 
 
+# Kept columns where the value already on the row wins over a later upsert's.
+_FIRST_WINS = ("label",)
+
+
 def _upsert(con: sqlite3.Connection, row: dict[str, Any]) -> None:
     """INSERT or overwrite a row by ``run_id``. ``label``, ``events`` and
     ``exception`` (and v6 ``os_user`` / ``source`` / ``exec_uid``) are written on
     insert but only ever *kept* on conflict: under
     ``runspec exec`` the wrapper writes the labelled row first and the child's own
     begin/finish upserts (which don't know the label) must not clear it — and a
-    begin that races a finish must not clear the finish's events."""
+    begin that races a finish must not clear the finish's events. ``label`` goes
+    further: the first non-empty value stays, so a child's own label (``cli`` when
+    nothing set ``RUNSPEC_LABEL``) never replaces the wrapper's ``--label``."""
     kept = ("label", "events", "exception", "os_user", "source", "exec_uid")
     cols = ", ".join((*_COLUMNS, *kept))
     placeholders = ", ".join("?" for _ in range(len(_COLUMNS) + len(kept)))
@@ -674,7 +680,7 @@ def _upsert(con: sqlite3.Connection, row: dict[str, Any]) -> None:
         # left a row without user / args / agent. UPDATE then INSERT does the same in
         # one write transaction (the UPDATE takes the write lock).
         sets = ", ".join(f"{c}=?" for c in _COLUMNS if c != "run_id")
-        sets += "".join(f", {c}=COALESCE(?, {c})" for c in kept)
+        sets += "".join(f", {c}=COALESCE({c}, ?)" if c in _FIRST_WINS else f", {c}=COALESCE(?, {c})" for c in kept)
         cur = con.execute(
             f"UPDATE runs SET {sets} WHERE run_id=?",
             (*(row[c] for c in _COLUMNS if c != "run_id"), *kept_vals, row["run_id"]),
@@ -683,7 +689,7 @@ def _upsert(con: sqlite3.Connection, row: dict[str, Any]) -> None:
             con.execute(f"INSERT INTO runs ({cols}) VALUES ({placeholders})", (*(row[c] for c in _COLUMNS), *kept_vals))
         return
     updates = ", ".join(f"{c}=excluded.{c}" for c in _COLUMNS if c != "run_id")
-    updates += "".join(f", {c}=COALESCE(excluded.{c}, runs.{c})" for c in kept)
+    updates += "".join(f", {c}=COALESCE(runs.{c}, excluded.{c})" if c in _FIRST_WINS else f", {c}=COALESCE(excluded.{c}, runs.{c})" for c in kept)
     con.execute(
         f"INSERT INTO runs ({cols}) VALUES ({placeholders}) ON CONFLICT(run_id) DO UPDATE SET {updates}",
         (*(row[c] for c in _COLUMNS), *kept_vals),
@@ -1277,6 +1283,7 @@ def reindex(log_dir: Path, records: list[dict[str, Any]]) -> int:
                             "trigger": rec.get("trigger", ""),
                             "skill": rec.get("skill", ""),
                             "autonomy": rec.get("autonomy", ""),
+                            "label": rec.get("label"),
                             "args": rec.get("invocation_args") or {},
                             "events": rec.get("events"),
                             "exception": exc,

{runspec-0.75.2 → runspec-0.76.0}/runspec/serve.py

@@ -316,7 +316,7 @@ def _handle_tools_call(
     # RUNSPEC_* vars on the child's stdin (the SPEC env frame) because sudo and
     # friends strip the environment — never on the command line.
     spec = exec_specs.get(name, {})
-    final_cmd, extra_env, frame = _build_command(spec, argv, {"RUNSPEC_AGENT": "1", **runspec_env})
+    final_cmd, extra_env, frame = _build_command(spec, argv, {"RUNSPEC_AGENT": "1", "RUNSPEC_LABEL": "mcp", **runspec_env})
     env = {**os.environ, **extra_env}
     # The child must never inherit serve's stdin: that's the MCP JSON-RPC stream.
     feed: dict[str, Any] = {"input": frame.decode("ascii")} if frame else {"stdin": subprocess.DEVNULL}

{runspec-0.75.2 → runspec-0.76.0}/runspec.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec
-Version: 0.75.2
+Version: 0.76.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

{runspec-0.75.2 → runspec-0.76.0}/tests/test_ansiblegen.py

@@ -154,6 +154,7 @@ def test_render_module_is_valid_python():
     assert "from ansible.module_utils.basic import AnsibleModule" in src
     assert "supports_check_mode=True" in src
     assert "RUNSPEC_AUTONOMY" in src  # non-interactive
+    assert 'env["RUNSPEC_LABEL"] = "ansible"' in src  # the run is labelled ansible
 
 
 def test_render_module_secret_via_env_not_argv():

{runspec-0.75.2 → runspec-0.76.0}/tests/test_exec.py

@@ -26,6 +26,7 @@ def logs_dir(tmp_path, monkeypatch):
     d.mkdir()
     monkeypatch.setattr(runexec, "_resolve_log_dir", lambda: d)
     monkeypatch.delenv("RUNSPEC_TRIGGER", raising=False)
+    monkeypatch.delenv("RUNSPEC_LABEL", raising=False)
     return d
 
 
@@ -119,6 +120,44 @@ class TestPlainChild:
         assert list(logs_dir.glob("demo.*.log"))
 
 
+class TestLabel:
+    """The run's label: --label, else the launcher's RUNSPEC_LABEL, else "cli" —
+    recorded on the row and handed to the child as RUNSPEC_LABEL."""
+
+    _BODY = "import os\nprint(os.environ.get('RUNSPEC_LABEL', '<unset>'))\n"
+
+    def test_unlabelled_run_is_cli(self, logs_dir, tmp_path, monkeypatch):
+        _install(monkeypatch, tmp_path, self._BODY)
+        _, out, _ = _run()
+        [row] = _rows(logs_dir)
+        assert row["label"] == "cli" and out.strip() == "cli"
+
+    def test_launcher_label_from_env(self, logs_dir, tmp_path, monkeypatch):
+        _install(monkeypatch, tmp_path, self._BODY)
+        monkeypatch.setenv("RUNSPEC_LABEL", "console")
+        _, out, _ = _run()
+        [row] = _rows(logs_dir)
+        assert row["label"] == "console" and out.strip() == "console"
+
+    def test_explicit_label_wins(self, logs_dir, tmp_path, monkeypatch):
+        _install(monkeypatch, tmp_path, self._BODY)
+        monkeypatch.setenv("RUNSPEC_LABEL", "console")
+        _, out, _ = _run(label="tui")
+        [row] = _rows(logs_dir)
+        assert row["label"] == "tui" and out.strip() == "tui"
+
+    def test_unlabelled_runs_do_not_skip_each_other(self, logs_dir, tmp_path, monkeypatch):
+        # --skip-if-running keys on --label only, so the "cli" default never
+        # makes one unlabelled runnable wait on another.
+        _install(monkeypatch, tmp_path, "print('ran')\n")
+        runsdb.begin_run(
+            logs_dir,
+            {"run_id": "live1", "runnable": "other", "status": "running", "pid": os.getpid(), "host": runsdb._hostname(), "proc_start": runsdb.proc_start_token(), "label": "cli"},
+        )
+        _, out, _ = _run(skip_if_running=True)
+        assert "ran" in out
+
+
 class TestNotRunnable:
     def test_not_installed_is_recorded(self, logs_dir, monkeypatch):
         monkeypatch.setattr(runexec, "find_runnable", lambda name: None)
@@ -191,6 +230,26 @@ class TestHandoff:
         assert row["command"] == "sub"  # the child's own detail kept
         assert row["events"] == '{"INFO": 2}'  # the wrapper's finalize kept the child's events
 
+    def test_child_label_does_not_replace_the_wrappers(self, logs_dir, tmp_path, monkeypatch):
+        # A child that records its own label (an older wrapper never handed one
+        # down, so parse() fell back to "cli") must not overwrite --label.
+        body = f"""
+        import os, sys
+        sys.path.insert(0, {str(Path(runsdb.__file__).parent.parent)!r})
+        from pathlib import Path
+        from runspec import runsdb
+        from runspec.logging_setup import adopt_exec_run_id
+        rid = adopt_exec_run_id()
+        d = Path({str(logs_dir)!r})
+        runsdb.begin_run(d, {{"run_id": rid, "runnable": "demo", "status": "running", "label": "cli",
+                              "pid": os.getpid(), "host": runsdb._hostname()}})
+        runsdb.finish_run(d, rid, exit_code=0, duration_ms=1, status="completed")
+        """
+        _install(monkeypatch, tmp_path, body)
+        _run(label="sched:x")
+        [row] = _rows(logs_dir)
+        assert row["label"] == "sched:x"
+
     def test_older_child_row_is_adopted(self, logs_dir, tmp_path, monkeypatch):
         # What a <= 0.61 child does: ignore RUNSPEC_RUN_ID and mint its own id.
         body = f"""

{runspec-0.75.2 → runspec-0.76.0}/tests/test_inbox.py

@@ -101,6 +101,11 @@ class TestParser:
         assert row["label"] == "sched:x" and row["command"] == "sub" and row["args"] == {"a": "b"}
         assert row["exec"]["exit_code"] == 137
 
+    def test_label_comes_from_the_summary_when_the_start_has_none(self):
+        rid = _rid()
+        row = inbox.row_from_records(rid, [json.loads(_rec(rid, "run_start", runnable="demo")), json.loads(_rec(rid, "run_summary", exit_code=0, label="console"))])
+        assert row is not None and row["label"] == "console"
+
     def test_history_db_false_marker(self):
         rid = _rid()
         row = inbox.row_from_records(rid, [json.loads(_rec(rid, "run_start", history_db=False)), json.loads(_rec(rid, "run_summary", exit_code=0))])

{runspec-0.75.2 → runspec-0.76.0}/tests/test_models.py

@@ -256,7 +256,7 @@ class TestRunSpecArgAccess:
 
     def test_get_absent_with_default(self):
         rs = self._make_with_args(region=arg("eu", name="region"))
-        assert rs.get("symbol", "VOD.L").value == "VOD.L"
+        assert rs.get("symbol", "ABC123").value == "ABC123"
 
     def test_get_never_raises_supports_safe_value_access(self):
         # The boilerplate-killer: no up-front guard needed.

{runspec-0.75.2 → runspec-0.76.0}/tests/test_parser.py

@@ -747,11 +747,11 @@ class TestSubcommandGlobals:
         self._write(tmp_path, monkeypatch)
         result = runspec.parse(
             script_name="sample-tool",
-            argv=["-r", "europe", "-e", "qa", "show", "--symbol", "VOD.L"],
+            argv=["-r", "europe", "-e", "qa", "show", "--symbol", "ABC123"],
         )
         assert result.region.value == "europe"
         assert result.env.value == "qa"
-        assert result.symbol.value == "VOD.L"
+        assert result.symbol.value == "ABC123"
         assert result.runspec_command_path == ["show"]
         assert result.runspec_command == "show"
 

{runspec-0.75.2 → runspec-0.76.0}/tests/test_run_summary.py

@@ -159,6 +159,16 @@ class TestEmit:
         s = next(obj for obj in lines if obj["logger"] == "runspec.runsummary")
         assert s["extra"]["skill"] == ""
 
+    def test_start_and_summary_record_the_label(self, tmp_path):
+        # `label` is where the run was launched from (RUNSPEC_LABEL, "cli" when
+        # unset — parse() fills that default); the run records carry it.
+        configure_logging(_cfg(), runnable_name="myscript", label="console")
+        _emit_run_summary()
+        lines = [json.loads(line) for line in (tmp_path / "logs" / "myscript.log").read_text().strip().splitlines()]
+        recs = [obj["extra"] for obj in lines if obj["logger"] == "runspec.runsummary"]
+        assert "run_summary" in {r["event"] for r in recs}
+        assert all(r["label"] == "console" for r in recs)
+
     def test_summary_console_writes_line_to_stderr(self, capsys):
         configure_logging(_cfg(summary_console=True), runnable_name="myscript")
         logging.getLogger("test.stderr").info("ran")
@@ -362,6 +372,35 @@ class TestEarlyExcepthookCoverage:
         assert seen["hook"] is not sys.__excepthook__
 
 
+class TestParseProvenance:
+    """parse() reads the launcher's provenance env vars and hands them to
+    configure_logging."""
+
+    def _kwargs(self, tmp_path, monkeypatch):
+        import runspec.parser as parser
+
+        cfg = tmp_path / "runspec.toml"
+        cfg.write_text("[demo]\n")
+        seen: dict[str, object] = {}
+        monkeypatch.setattr(parser, "configure_logging", lambda *a, **kw: seen.update(kw))
+        parser.parse(script_name="demo", argv=[], config_path=cfg)
+        return seen
+
+    def test_unlabelled_run_is_cli(self, tmp_path, monkeypatch):
+        monkeypatch.delenv("RUNSPEC_LABEL", raising=False)
+        assert self._kwargs(tmp_path, monkeypatch)["label"] == "cli"
+
+    def test_launcher_label(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("RUNSPEC_LABEL", " console ")
+        assert self._kwargs(tmp_path, monkeypatch)["label"] == "console"
+
+    def test_runbook_env_is_the_skill(self, tmp_path, monkeypatch):
+        # The console sends RUNSPEC_RUNBOOK; RUNSPEC_SKILL is the older spelling.
+        monkeypatch.delenv("RUNSPEC_SKILL", raising=False)
+        monkeypatch.setenv("RUNSPEC_RUNBOOK", "restart-web")
+        assert self._kwargs(tmp_path, monkeypatch)["skill"] == "restart-web"
+
+
 class TestExcStructuredHelpers:
     def test_build_exc_structured_shape(self):
         try:
@@ -517,6 +556,13 @@ class TestRunsIndexHook:
         assert done["status"] == "completed" and done["exit_code"] == 0
         assert isinstance(done["duration_ms"], int)
 
+    def test_row_carries_the_label(self, tmp_path):
+        from runspec import runsdb
+
+        configure_logging(_cfg(summary=True), runnable_name="demo", history_cfg={"db": True}, label="console")
+        _emit_run_summary()
+        assert runsdb.list_runs(tmp_path / "logs", live=False)[0]["label"] == "console"
+
     def test_failure_finalizes_as_failed(self, tmp_path):
         from runspec import runsdb
 

{runspec-0.75.2 → runspec-0.76.0}/tests/test_rundeckgen.py

@@ -184,10 +184,13 @@ def test_script_no_args_just_execs():
 def test_script_run_as_sends_env_frame_on_stdin_to_venv_python():
     s = rundeckgen.render_script("deploy", ["start"], {"token": {"type": "password"}}, "/opt/app/.venv/bin/deploy", run_as="svc", venv="/opt/app/.venv")
     assert "rs_user=svc\n" in s
-    assert 'rs_frame RUNSPEC_DEPLOY_ARG_TOKEN | sudo -n -u "$rs_user" /opt/app/.venv/bin/python -c "$RS_PRELUDE" /opt/app/.venv/bin/deploy start' in s
-    # sudo resets the environment, so values ride stdin; the only export is the
-    # no-sudo branch taken when the Rundeck user already is the account.
-    assert s.count("export") == 1
+    assert "\nRUNSPEC_LABEL=rundeck\n" in s
+    assert 'rs_frame RUNSPEC_DEPLOY_ARG_TOKEN RUNSPEC_LABEL | sudo -n -u "$rs_user" /opt/app/.venv/bin/python -c "$RS_PRELUDE" /opt/app/.venv/bin/deploy start' in s
+    # sudo resets the environment, so values (and the label) ride stdin; the only
+    # exports are in the no-sudo branch taken when the Rundeck user already is
+    # the account.
+    assert s.count("export") == 2
+    assert "  export RUNSPEC_LABEL=rundeck\n" in s
     assert 'if [ "$rs_user" = "$(id -un)" ]; then' in s
 
 
@@ -197,9 +200,19 @@ def test_script_run_as_without_venv_uses_shell_prelude():
     assert "command -v" not in s  # sudo's PATH isn't the Rundeck user's
 
 
-def test_script_run_as_no_args_execs_sudo():
+def test_script_run_as_no_args_sends_only_the_label():
+    """With the venv known the venv-python prelude is covered by a venv `bin/`
+    sudoers rule, so even a job with no options sends its label in the frame."""
     s = rundeckgen.render_script("deploy", [], {}, "/opt/v/bin/deploy", run_as="svc", venv="/opt/v")
-    assert s.strip().endswith('exec sudo -n -u "$rs_user" /opt/v/bin/deploy')
+    assert s.strip().endswith('rs_frame RUNSPEC_LABEL | sudo -n -u "$rs_user" /opt/v/bin/python -c "$RS_PRELUDE" /opt/v/bin/deploy')
+
+
+def test_script_run_as_no_args_no_venv_execs_sudo():
+    """Without the venv the prelude would be `sh`, which a sudoers rule may
+    refuse, so a job with no options runs the binary directly (label "cli")."""
+    s = rundeckgen.render_script("deploy", [], {}, "deploy", run_as="svc")
+    assert s.strip().endswith('exec sudo -n -u "$rs_user" deploy')
+    assert "RS_PRELUDE" not in s
 
 
 def test_script_run_as_rejects_shell_metacharacters():
@@ -227,7 +240,7 @@ def _show_binary(tmp_path):
 
     show = tmp_path / "bin" / "show"
     show.parent.mkdir(exist_ok=True)
-    show.write_text(f"#!{sys.executable}\nimport json, os, sys\nprint(json.dumps([{{k: v for k, v in os.environ.items() if k.startswith('RUNSPEC_SHOW_')}}, sys.argv[1:]]))\n")
+    show.write_text(f"#!{sys.executable}\nimport json, os, sys\nprint(json.dumps([{{k: v for k, v in os.environ.items() if k.startswith('RUNSPEC_SHOW_') or k == 'RUNSPEC_LABEL'}}, sys.argv[1:]]))\n")
     show.chmod(0o755)
     return show
 
@@ -257,7 +270,7 @@ def test_script_values_round_trip_through_bash(tmp_path):
         out = _run_substituted(tmp_path, script, values)
         assert out.returncode == 0, out.stderr
         env, argv = json.loads(out.stdout)
-        assert env == {"RUNSPEC_SHOW_ARG_PLAIN": "3", "RUNSPEC_SHOW_ARG_TRICKY": values["tricky"], "RUNSPEC_SHOW_ARG_DELIM": "RUNSPEC_VALUE"}
+        assert env == {"RUNSPEC_SHOW_ARG_PLAIN": "3", "RUNSPEC_SHOW_ARG_TRICKY": values["tricky"], "RUNSPEC_SHOW_ARG_DELIM": "RUNSPEC_VALUE", "RUNSPEC_LABEL": "rundeck"}
         assert argv == ["sub"]
     assert not (tmp_path / "pwned").exists()
 
@@ -324,7 +337,7 @@ def test_script_guard_tolerates_blank_lines(tmp_path):
     script = rundeckgen.render_script("show", [], {"a": {"type": "str"}}, str(show)) + "\n\n"
     out = _run_substituted(tmp_path, script, {"a": "\n"})
     assert out.returncode == 0, out.stderr
-    assert json.loads(out.stdout)[0] == {}
+    assert json.loads(out.stdout)[0] == {"RUNSPEC_LABEL": "rundeck"}
 
 
 def test_script_guard_count_matches_rendered_script():
@@ -380,7 +393,7 @@ def test_script_owner_runs_directly_when_already_the_owner(tmp_path):
         env = {**os.environ, "PATH": f"{tmp_path}/bin:/usr/bin:/bin"}
         out = _run_substituted(tmp_path, script, {"a": "v"}, env=env)
         assert out.returncode == 0, out.stderr
-        assert json.loads(out.stdout) == [{"RUNSPEC_SHOW_ARG_A": "v"}, ["sub"]]
+        assert json.loads(out.stdout) == [{"RUNSPEC_SHOW_ARG_A": "v", "RUNSPEC_LABEL": "rundeck"}, ["sub"]]
 
 
 def test_script_owner_escalates_to_the_venv_owner(tmp_path):
@@ -404,7 +417,7 @@ def test_script_owner_escalates_to_the_venv_owner(tmp_path):
         script = rundeckgen.render_script("show", ["sub"], {"a": {"type": "str"}, "b": {"type": "password"}}, invocation, run_as="@owner", venv=venv)
         out = _run_substituted(tmp_path, script, {"a": "v", "b": "s3cret"}, env=env)
         assert out.returncode == 0, out.stderr
-        assert json.loads(out.stdout) == [{"RUNSPEC_SHOW_ARG_A": "v", "RUNSPEC_SHOW_ARG_B": "s3cret"}, ["sub"]]
+        assert json.loads(out.stdout) == [{"RUNSPEC_SHOW_ARG_A": "v", "RUNSPEC_SHOW_ARG_B": "s3cret", "RUNSPEC_LABEL": "rundeck"}, ["sub"]]
         sudo_argv = (tmp_path / "sudo.log").read_text()
         assert sudo_argv.startswith("-n -u svc-owner ")
         assert "s3cret" not in sudo_argv and str(show) in sudo_argv

{runspec-0.75.2 → runspec-0.76.0}/tests/test_runsdb.py

@@ -210,6 +210,7 @@ class TestReindex:
                     "trigger": "schedule",
                     "skill": "",
                     "autonomy": "autonomous",
+                    "label": "rundeck",
                     "exception": None,
                     "user": "svc",
                     "invocation_args": {},
@@ -230,7 +231,8 @@ class TestReindex:
         assert n == 2
         rows = {r["run_id"]: r for r in runsdb.list_runs(logs_dir, live=False)}
         assert rows["h1"]["status"] == "completed" and rows["h1"]["agent"] == 1
-        assert rows["h1"]["trigger"] == "schedule"
+        assert rows["h1"]["trigger"] == "schedule" and rows["h1"]["label"] == "rundeck"
+        assert rows["h2"]["label"] is None  # a summary from before labels
         assert rows["h2"]["status"] == "failed" and rows["h2"]["command"] == "push"
 
     def test_reindex_skips_records_without_run_id(self, logs_dir):

{runspec-0.75.2 → runspec-0.76.0}/tests/test_serve.py

@@ -316,6 +316,7 @@ def test_tools_call_no_run_as_does_not_escalate(monkeypatch, tmp_path):
     # The env rides the child's environment; the child never inherits serve's
     # stdin (the MCP JSON-RPC stream).
     assert captured["kw"]["env"]["RUNSPEC_AGENT"] == "1"
+    assert captured["kw"]["env"]["RUNSPEC_LABEL"] == "mcp"
     assert captured["kw"]["stdin"] is subprocess.DEVNULL
 
 

{runspec-0.75.2 → runspec-0.76.0}/tests/test_testing.py

@@ -2,15 +2,15 @@
 Tests for runspec.testing.ParseHarness — and a worked example of how a
 developer scaffolds tests for a real, subcommand-heavy runnable.
 
-The `static-data` fixture is the migrated trading-symbol runnable from
-docs/design/new_example_toml.md: ~11 subcommands, parent-level args
+The `catalog` fixture (tests/fixtures/catalog.toml) is a large catalogue
+runnable: ~11 subcommands, parent-level args
 (region/env/source/jira), patterns, multiple values, and require-command.
 It stands in for any large migrated runnable so the patterns below transfer
 directly.
 
 Two layers are demonstrated:
 
-  Layer 1 — wiring/parsing, no mocks (TestStaticDataWiring, TestSmoke).
+  Layer 1 — wiring/parsing, no mocks (TestCatalogWiring, TestSmoke).
   Layer 2 — the actual work, mocking only the I/O boundary (TestLayerTwoPattern).
 """
 
@@ -28,50 +28,50 @@ from runspec.testing import ParseHarness, harness, no_run_as_check
 posix_only = pytest.mark.skipif(not hasattr(os, "geteuid"), reason="POSIX uid model required")
 
 FIXTURES = Path(__file__).parent / "fixtures"
-STATIC_DATA = FIXTURES / "static_data.toml"
+CATALOG = FIXTURES / "catalog.toml"
 
 
 @pytest.fixture()
 def h() -> ParseHarness:
-    return ParseHarness(script_name="static-data", config_path=STATIC_DATA)
+    return ParseHarness(script_name="catalog", config_path=CATALOG)
 
 
 # ── Layer 1: wiring / parsing (no mocks) ──────────────────────────────────────
 
 
-class TestStaticDataWiring:
+class TestCatalogWiring:
     def test_subcommand_is_detected(self, h: ParseHarness) -> None:
-        spec = h.expect_ok(["create", "-s", "AAPL,MSFT", "--region", "americas", "--env", "prod"])
+        spec = h.expect_ok(["create", "-s", "WIDGET1,GADGET2", "--region", "americas", "--env", "prod"])
         assert spec.runspec_command == "create"
         assert spec.runspec_command_path == ["create"]
 
     def test_types_are_coerced(self, h: ParseHarness) -> None:
-        spec = h.expect_ok(["create", "-s", "AAPL", "--price", "12.5", "--region", "americas", "--env", "prod"])
-        assert spec.symbols.value == ["AAPL"]  # multiple + delimiter -> list
+        spec = h.expect_ok(["create", "-s", "WIDGET1", "--price", "12.5", "--region", "americas", "--env", "prod"])
+        assert spec.skus.value == ["WIDGET1"]  # multiple + delimiter -> list
         assert spec.price.value == 12.5  # float
         assert isinstance(spec.price.value, float)
 
     def test_flag_defaults_false(self, h: ParseHarness) -> None:
-        spec = h.expect_ok(["create", "-s", "AAPL", "--region", "americas", "--env", "prod"])
+        spec = h.expect_ok(["create", "-s", "WIDGET1", "--region", "americas", "--env", "prod"])
         assert spec.persist.value is False
 
-    def test_missing_required_symbols_exits(self, h: ParseHarness) -> None:
-        # `symbols` is required on `create`; omit it.
+    def test_missing_required_skus_exits(self, h: ParseHarness) -> None:
+        # `skus` is required on `create`; omit it.
         out = h.expect_exit(["create", "--region", "americas", "--env", "prod"])
-        assert "symbol" in out.lower() or "-s" in out
+        assert "sku" in out.lower() or "-s" in out
 
     def test_bad_choice_names_the_flag(self, h: ParseHarness) -> None:
         h.expect_exit(
-            ["create", "-s", "AAPL", "--region", "mars", "--env", "prod"],
+            ["create", "-s", "WIDGET1", "--region", "mars", "--env", "prod"],
             contains="--region",
         )
 
     def test_pattern_violation_is_rejected(self, h: ParseHarness) -> None:
-        # symbols pattern forbids whitespace / lowercase.
-        h.expect_exit(["show", "-s", "not a symbol", "--region", "americas", "--env", "prod"])
+        # skus pattern forbids whitespace / lowercase.
+        h.expect_exit(["show", "-s", "not a sku", "--region", "americas", "--env", "prod"])
 
     def test_require_command_enforced(self, h: ParseHarness) -> None:
-        # static-data sets require-command = true.
+        # catalog sets require-command = true.
         h.expect_exit([])
 
     def test_help_exits_zero(self, h: ParseHarness) -> None:
@@ -92,12 +92,12 @@ class TestSmoke:
             values={
                 "region": "americas",
                 "env": "prod",
-                "symbols": "AAPL",
+                "skus": "WIDGET1",
                 "price": "12.5",
-                "adv": "1000",
-                "trades": "50",
-                "ipo_date": "20240101",
-                "volume": "100",
+                "avg_sales": "1000",
+                "avg_orders": "50",
+                "launch_date": "20240101",
+                "quantity": "100",
                 "field": "SomeField",
                 "value": "x",
             }
@@ -111,7 +111,7 @@ class TestSmoke:
     def test_command_discovery(self, h: ParseHarness) -> None:
         names = {p[-1] for p in h.command_paths()}
         assert {"show", "create", "clone", "refresh"} <= names
-        assert h.required_args(["create"]) == ["symbols"]
+        assert h.required_args(["create"]) == ["skus"]
         assert h.requires_command() is True
 
 
@@ -301,22 +301,22 @@ class TestLayerTwoPattern:
         # Stand-in for your real module: a pure logic function + the one I/O call.
         calls: list[tuple] = []
 
-        def fake_store_call(region: str, action: str, symbols: list[str], **fields):
-            calls.append((region, action, tuple(symbols), fields))
-            return {"ok": True, "applied": list(symbols)}
+        def fake_store_call(region: str, action: str, skus: list[str], **fields):
+            calls.append((region, action, tuple(skus), fields))
+            return {"ok": True, "applied": list(skus)}
 
-        def create_symbols(region, symbols, *, price=None, _call=fake_store_call):
+        def create_items(region, skus, *, price=None, _call=fake_store_call):
             # the kind of plain function your main() should delegate to
-            return _call(region, "create", symbols, price=price)
+            return _call(region, "create", skus, price=price)
 
         # The harness gives you the parsed RunSpec to feed the logic function.
-        h = ParseHarness(script_name="static-data", config_path=STATIC_DATA)
-        spec = h.expect_ok(["create", "-s", "AAPL,MSFT", "--price", "12.5", "--region", "americas", "--env", "prod"])
+        h = ParseHarness(script_name="catalog", config_path=CATALOG)
+        spec = h.expect_ok(["create", "-s", "WIDGET1,GADGET2", "--price", "12.5", "--region", "americas", "--env", "prod"])
 
-        result = create_symbols(spec.region.value, spec.symbols.value, price=spec.price.value)
+        result = create_items(spec.region.value, spec.skus.value, price=spec.price.value)
 
-        assert result == {"ok": True, "applied": ["AAPL", "MSFT"]}
-        assert calls == [("americas", "create", ("AAPL", "MSFT"), {"price": 12.5})]
+        assert result == {"ok": True, "applied": ["WIDGET1", "GADGET2"]}
+        assert calls == [("americas", "create", ("WIDGET1", "GADGET2"), {"price": 12.5})]
 
 
 # ── Harness behaviour itself ──────────────────────────────────────────────────
@@ -352,7 +352,7 @@ class TestHarnessApi:
         with pytest.raises(ValueError):
             ParseHarness(script_name="greet")
         with pytest.raises(ValueError):
-            ParseHarness(script_name="greet", toml=GREET, config_path=STATIC_DATA)
+            ParseHarness(script_name="greet", toml=GREET, config_path=CATALOG)
 
     def test_unknown_runnable_raises(self) -> None:
         with pytest.raises(KeyError):