runspec 0.1.0__py3-none-any.whl

runspec/__init__.py

@@ -0,0 +1,23 @@
+"""
+runspec — A language-agnostic, TOML-based interface specification
+for anything runnable.
+
+Public API:
+    parse()         → RunSpec   Parse arguments for the calling script
+    load_spec()     → RunSpec   Load spec without parsing argv
+    register_type() → None      Register a custom type coercer
+"""
+
+from runspec.models import Arg, Group, RunSpec
+from runspec.parser import load_spec, parse
+from runspec.types import register_type
+
+__version__ = "0.1.0"
+__all__ = [
+    "parse",
+    "load_spec",
+    "register_type",
+    "RunSpec",
+    "Arg",
+    "Group",
+]

runspec/cli.py

@@ -0,0 +1,349 @@
+"""
+cli.py — The runspec command-line interface.
+
+Commands:
+    runspec discover [--format mcp|openai|anthropic|json]
+    runspec check
+    runspec emit --script <name> [--format mcp|openai|anthropic]
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def main() -> None:
+    """Entry point for the runspec CLI binary."""
+    args = sys.argv[1:]
+
+    if not args or args[0] in ("-h", "--help"):
+        _print_help()
+        return
+
+    command = args[0]
+    rest = args[1:]
+
+    commands = {
+        "discover": cmd_discover,
+        "check": cmd_check,
+        "emit": cmd_emit,
+    }
+
+    if command not in commands:
+        print(f"✗  Unknown command: {command}")
+        print(f"   Available commands: {', '.join(commands)}")
+        sys.exit(1)
+
+    commands[command](rest)
+
+
+def cmd_discover(args: list[str]) -> None:
+    """
+    Discover all runspec-aware runnables in the current environment.
+    Checks installed packages and the current directory.
+    """
+    fmt = _get_flag(args, "--format", default="text")
+
+    discovered: list[dict[str, Any]] = []
+
+    # Check current directory
+    local = _discover_local()
+    if local:
+        discovered.extend(local)
+
+    # Check installed packages
+    installed = _discover_installed()
+    if installed:
+        discovered.extend(installed)
+
+    if not discovered:
+        print("No runspec-aware runnables found in this environment.")
+        print("Add a [tool.runspec.yourname] section to pyproject.toml or create runspec.toml")
+        return
+
+    if fmt == "text":
+        _print_discover_text(discovered)
+    elif fmt == "json":
+        print(json.dumps(discovered, indent=2, default=str))
+    elif fmt in ("mcp", "openai", "anthropic"):
+        schema = _emit_all(discovered, fmt)
+        print(json.dumps(schema, indent=2, default=str))
+    else:
+        print(f"✗  Unknown format: {fmt}")
+        print("   Available formats: text, json, mcp, openai, anthropic")
+        sys.exit(1)
+
+
+def cmd_check(args: list[str]) -> None:
+    """
+    Validate the current project's runspec setup.
+    """
+    from runspec.finder import find_config
+    from runspec.loader import load_raw
+
+    try:
+        config_path, fmt = find_config(Path.cwd())
+    except FileNotFoundError as e:
+        print(str(e))
+        sys.exit(1)
+
+    raw = load_raw(config_path, fmt)
+    errors: list[str] = []
+    warnings: list[str] = []
+    ok: list[str] = []
+
+    # Check config file found
+    ok.append(f"Config found: {config_path}")
+
+    # Check entry points if pyproject.toml
+    if fmt == "pyproject":
+        entry_points = raw.get("entry_points", {})
+        if entry_points:
+            ok.append(f"[project.scripts] found — {len(entry_points)} entry point(s)")
+        else:
+            warnings.append("No [project.scripts] found — agents may not discover runnables automatically\n  Add entry points to pyproject.toml or use runspec.toml")
+
+    # Check for reserved name
+    if "config" in raw["runnables"]:
+        errors.append("'config' is a reserved name — rename your runnable to something else")
+
+    # Check each runnable
+    for runnable_name, runnable in raw["runnables"].items():
+        if not runnable.get("description"):
+            warnings.append(f"'{runnable_name}' has no description — agents won't know what it does")
+        else:
+            ok.append(f"'{runnable_name}' — description present")
+
+        if not runnable.get("autonomy"):
+            warnings.append(f"'{runnable_name}' autonomy not declared — will default to '{raw['config']['autonomy_default']}'")
+        else:
+            ok.append(f"'{runnable_name}' — autonomy: {runnable['autonomy']}")
+
+        for arg_name, arg in runnable.get("args", {}).items():
+            if not arg.get("description") and arg.get("required"):
+                warnings.append(f"'{runnable_name}.{arg_name}' is required but has no description")
+
+    # Print results
+    for msg in ok:
+        print(f"  ✓  {msg}")
+    for msg in warnings:
+        print(f"  ℹ  {msg}")
+    for msg in errors:
+        print(f"  ✗  {msg}")
+
+    if errors:
+        sys.exit(1)
+    elif not warnings:
+        print("\n  All checks passed.")
+
+
+def cmd_emit(args: list[str]) -> None:
+    """
+    Emit a tool schema for one or all runnables.
+    """
+    script_name = _get_flag(args, "--script")
+    fmt = _get_flag(args, "--format", default="mcp")
+
+    from runspec.finder import find_config
+    from runspec.inference import infer_script
+    from runspec.loader import load_raw
+
+    try:
+        config_path, file_fmt = find_config(Path.cwd())
+    except FileNotFoundError as e:
+        print(str(e))
+        sys.exit(1)
+
+    raw = load_raw(config_path, file_fmt)
+    config = raw["config"]
+
+    if script_name:
+        if script_name not in raw["runnables"]:
+            print(f"✗  Runnable '{script_name}' not found")
+            sys.exit(1)
+        runnables = {script_name: raw["runnables"][script_name]}
+    else:
+        runnables = raw["runnables"]
+
+    schema = {}
+    for name, runnable in runnables.items():
+        inferred = infer_script(runnable, config["autonomy_default"])
+        schema[name] = _build_schema(name, inferred, fmt or "mcp")
+
+    output = {"tools": list(schema.values())} if fmt == "mcp" else schema
+
+    print(json.dumps(output, indent=2, default=str))
+
+
+# ── Schema builders ───────────────────────────────────────────────────────────
+
+
+def _build_schema(name: str, script: dict[str, Any], fmt: str) -> dict[str, Any]:
+    """Build a tool schema for a script in the requested format."""
+    properties: dict[str, Any] = {}
+    required_args: list[str] = []
+
+    for arg_name, arg in script.get("args", {}).items():
+        prop = _arg_to_json_schema(arg)
+        properties[arg_name] = prop
+        if arg.get("required"):
+            required_args.append(arg_name)
+
+    schema: dict[str, Any] = {
+        "name": name,
+        "description": script.get("description") or "",
+        "x-autonomy": script.get("autonomy", "confirm"),
+        "inputSchema": {
+            "type": "object",
+            "properties": properties,
+        },
+    }
+
+    if required_args:
+        schema["inputSchema"]["required"] = required_args
+
+    if script.get("autonomy_reason"):
+        schema["x-autonomy-reason"] = script["autonomy_reason"]
+
+    return schema
+
+
+def _arg_to_json_schema(arg: dict[str, Any]) -> dict[str, Any]:
+    """Convert a runspec arg spec to a JSON Schema property."""
+    type_map = {
+        "str": "string",
+        "int": "integer",
+        "float": "number",
+        "bool": "boolean",
+        "flag": "boolean",
+        "path": "string",
+        "choice": "string",
+    }
+
+    prop: dict[str, Any] = {
+        "type": type_map.get(arg.get("type", "str"), "string"),
+    }
+
+    if arg.get("description"):
+        prop["description"] = arg["description"]
+
+    if arg.get("default") is not None:
+        prop["default"] = arg["default"]
+
+    if arg.get("options"):
+        prop["enum"] = arg["options"]
+
+    if arg.get("range"):
+        min_val, max_val = arg["range"]
+        prop["minimum"] = min_val
+        prop["maximum"] = max_val
+
+    if arg.get("multiple"):
+        prop = {"type": "array", "items": prop}
+
+    return prop
+
+
+# ── Discovery helpers ─────────────────────────────────────────────────────────
+
+
+def _discover_local() -> list[dict[str, Any]]:
+    """Look for runspec config in the current directory."""
+    from runspec.finder import find_config
+    from runspec.loader import load_raw
+
+    try:
+        config_path, fmt = find_config(Path.cwd())
+        raw = load_raw(config_path, fmt)
+        return [{"source": str(config_path), "runnable": name, "spec": spec} for name, spec in raw["runnables"].items()]
+    except FileNotFoundError:
+        return []
+
+
+def _discover_installed() -> list[dict[str, Any]]:
+    """
+    Find runspec-aware packages in the current Python environment
+    using importlib.metadata.
+    """
+    import importlib.metadata as meta
+
+    discovered: list[dict[str, Any]] = []
+
+    for dist in meta.packages_distributions():
+        try:
+            meta.metadata(dist)
+            # Check if package has runspec.toml as package data
+            # This is a simplified check — full implementation uses
+            # importlib.resources to look for the file
+            pass
+        except Exception:
+            continue
+
+    return discovered
+
+
+def _emit_all(discovered: list[dict[str, Any]], fmt: str) -> dict[str, Any]:
+    """Emit all discovered runnables as a unified schema."""
+    tools = []
+    for item in discovered:
+        tool = _build_schema(item["script"], item["spec"], fmt)
+        tools.append(tool)
+    return {"tools": tools}
+
+
+def _print_discover_text(discovered: list[dict[str, Any]]) -> None:
+    """Pretty-print discovered runnables."""
+    by_source: dict[str, list[str]] = {}
+    for item in discovered:
+        src = item["source"]
+        by_source.setdefault(src, []).append(item["runnable"])
+
+    print(f"Found {len(discovered)} runspec-aware runnable(s):\n")
+    for source, runnables in by_source.items():
+        print(f"  {source}")
+        for r in runnables:
+            print(f"    • {r}")
+    print()
+    print("Run 'runspec discover --format mcp' to emit MCP tool schemas.")
+
+
+# ── Arg parsing helpers ───────────────────────────────────────────────────────
+
+
+def _get_flag(args: list[str], flag: str, default: str | None = None) -> str | None:
+    """Extract a --flag value from args list."""
+    try:
+        idx = args.index(flag)
+        return args[idx + 1]
+    except (ValueError, IndexError):
+        return default
+
+
+def _print_help() -> None:
+    print("""runspec — interface specification for anything runnable
+
+Usage:
+  runspec <command> [options]
+
+Commands:
+  discover    Find all runspec-aware runnables in this environment
+  check       Validate this project's runspec setup
+  emit        Emit tool schemas for agent frameworks
+
+Options for discover:
+  --format    Output format: text (default), json, mcp, openai, anthropic
+
+Options for emit:
+  --script    Runnable name to emit (all runnables if omitted)
+  --format    Output format: mcp (default), openai, anthropic
+
+Examples:
+  runspec discover
+  runspec discover --format mcp
+  runspec check
+  runspec emit --name compress --format mcp
+  runspec emit --format openai
+""")

runspec/errors.py

@@ -0,0 +1,168 @@
+"""
+errors.py — Human-first error formatting with fuzzy suggestions.
+
+Every error includes:
+  - what failed
+  - what was expected
+  - what was received
+  - a suggestion where possible (via difflib, stdlib, zero dependencies)
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+
+class RunSpecError(Exception):
+    """Base class for all runspec errors."""
+
+
+class MissingRequiredArg(RunSpecError):
+    """A required argument was not provided."""
+
+
+class InvalidChoice(RunSpecError):
+    """A value was not in the declared options list."""
+
+
+class OutOfRange(RunSpecError):
+    """A numeric value was outside the declared range."""
+
+
+class UnknownArg(RunSpecError):
+    """An argument was provided that is not in the spec."""
+
+
+class GroupViolation(RunSpecError):
+    """A group constraint was violated."""
+
+
+class AutonomyViolation(RunSpecError):
+    """An agent attempted to exceed its declared autonomy level."""
+
+
+def format_missing_required(name: str, arg_spec: dict[str, Any]) -> str:
+    lines = [
+        f"✗  Missing required argument: --{name}",
+        f"   Type: {arg_spec.get('type', 'str')}",
+    ]
+    if arg_spec.get("description"):
+        lines.append(f"   Description: {arg_spec['description']}")
+    if arg_spec.get("env"):
+        lines.append(f"   Tip: set environment variable {arg_spec['env']} as an alternative")
+    return "\n".join(lines)
+
+
+def format_invalid_choice(value: str, options: list[str], name: str) -> str:
+    lines = [
+        f"✗  Invalid value for --{name}: {value!r}",
+        f"   Expected one of: {', '.join(str(o) for o in options)}",
+        f"   Got: {value!r}",
+    ]
+    suggestion = _suggest(value, [str(o) for o in options])
+    if suggestion:
+        lines.append(f"\n   Did you mean: {suggestion}?")
+    return "\n".join(lines)
+
+
+def format_out_of_range(
+    value: int | float,
+    range_: tuple[Any, Any],
+    name: str,
+) -> str:
+    min_val, max_val = range_
+    return "\n".join(
+        [
+            f"✗  Value out of range for --{name}: {value}",
+            f"   Expected: between {min_val} and {max_val}",
+            f"   Got: {value}",
+        ]
+    )
+
+
+def format_unknown_arg(name: str, known_args: list[str]) -> str:
+    lines = [
+        f"✗  Unknown argument: --{name}",
+        f"   Known arguments: {', '.join(f'--{a}' for a in sorted(known_args))}",
+    ]
+    suggestion = _suggest(name, known_args)
+    if suggestion:
+        lines.append(f"\n   Did you mean: --{suggestion}?")
+    return "\n".join(lines)
+
+
+def format_group_exclusive(group_name: str, provided: list[str]) -> str:
+    return "\n".join(
+        [
+            f"✗  Conflicting arguments in group '{group_name}'",
+            f"   --{provided[0]} and --{provided[1]} cannot be used together",
+            "   Choose one or the other",
+        ]
+    )
+
+
+def format_group_inclusive(group_name: str, missing: list[str]) -> str:
+    missing_flags = " and ".join(f"--{m}" for m in missing)
+    return "\n".join(
+        [
+            f"✗  Incomplete argument group '{group_name}'",
+            "   Providing one of these args requires all of them",
+            f"   Also provide: {missing_flags}",
+        ]
+    )
+
+
+def format_group_at_least_one(group_name: str, args: list[str]) -> str:
+    return "\n".join(
+        [
+            f"✗  Group '{group_name}' requires at least one argument",
+            f"   Provide at least one of: {', '.join(f'--{a}' for a in args)}",
+        ]
+    )
+
+
+def format_group_exactly_one(group_name: str, args: list[str], provided: list[str]) -> str:
+    if not provided:
+        return "\n".join(
+            [
+                f"✗  Group '{group_name}' requires exactly one argument",
+                f"   Provide exactly one of: {', '.join(f'--{a}' for a in args)}",
+            ]
+        )
+    return "\n".join(
+        [
+            f"✗  Group '{group_name}' requires exactly one argument",
+            f"   Got {len(provided)}: {', '.join(f'--{a}' for a in provided)}",
+            f"   Provide exactly one of: {', '.join(f'--{a}' for a in args)}",
+        ]
+    )
+
+
+def format_autonomy_violation(
+    script_name: str,
+    required_level: str,
+    reason: str | None,
+) -> str:
+    lines = [
+        f"✗  Cannot run '{script_name}' autonomously",
+        f"   Autonomy level: {required_level}",
+    ]
+    if reason:
+        lines.append(f"   Reason: {reason}")
+    lines.append("\n   Awaiting human confirmation...")
+    return "\n".join(lines)
+
+
+def format_deprecated(name: str, message: str) -> str:
+    return f"⚠  --{name} is deprecated: {message}"
+
+
+def _suggest(value: str, candidates: list[str]) -> str | None:
+    """
+    Return the closest match from candidates using difflib.
+    Returns None if no close match found.
+    Uses stdlib only — zero extra dependencies.
+    """
+    matches = difflib.get_close_matches(value, candidates, n=1, cutoff=0.6)
+    return matches[0] if matches else None

runspec/finder.py

@@ -0,0 +1,115 @@
+"""
+finder.py — Locates the runspec configuration file.
+
+Search order (per SPEC.md):
+  1. pyproject.toml with [tool.runspec] section
+  2. runspec.toml
+  Walk up from the starting directory repeating 1 and 2.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+def find_config(start: Path | None = None) -> tuple[Path, str]:
+    """
+    Find the runspec config file starting from `start` and walking up.
+
+    Returns:
+        (config_path, format) where format is "pyproject" or "runspec"
+
+    Raises:
+        FileNotFoundError: if no config file is found
+    """
+    search_dir = (start or _caller_directory()).resolve()
+
+    for directory in [search_dir, *search_dir.parents]:
+        # Check pyproject.toml first
+        pyproject = directory / "pyproject.toml"
+        if pyproject.exists() and _has_runspec_section(pyproject):
+            return pyproject, "pyproject"
+
+        # Then runspec.toml
+        runspec_toml = directory / "runspec.toml"
+        if runspec_toml.exists():
+            return runspec_toml, "runspec"
+
+    raise FileNotFoundError(
+        "No runspec configuration found.\nExpected one of:\n  - pyproject.toml with [tool.runspec] section\n  - runspec.toml\n\nRun 'runspec check' to validate your project setup."
+    )
+
+
+def find_script_name(config_path: Path, format: str) -> str | None:
+    """
+    Infer the calling script's name from [project.scripts] or
+    [tool.poetry.scripts] by matching the calling executable.
+
+    Returns the script name if found, None if it cannot be determined.
+    """
+    try:
+        with open(config_path, "rb") as f:
+            data = tomllib.load(f)
+    except Exception:
+        return None
+
+    # Get the name of the currently running script/executable
+    caller = Path(sys.argv[0]).stem if sys.argv else None
+    if not caller:
+        return None
+
+    # Check [project.scripts] first (PEP 517/518 standard)
+    project_scripts = data.get("project", {}).get("scripts", {})
+    if caller in project_scripts:
+        return caller
+
+    # Fall back to [tool.poetry.scripts] with a nudge logged
+    poetry_scripts = data.get("tool", {}).get("poetry", {}).get("scripts", {})
+    if caller in poetry_scripts:
+        _nudge_poetry()
+        return caller
+
+    return caller  # return caller name even if not in scripts — let loader handle it
+
+
+def _has_runspec_section(pyproject_path: Path) -> bool:
+    """Return True if pyproject.toml contains a [tool.runspec] section."""
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+        return "runspec" in data.get("tool", {})
+    except Exception:
+        return False
+
+
+def _caller_directory() -> Path:
+    """Return the directory of the script that called parse()."""
+    # Walk up the call stack to find the first frame outside runspec
+    import inspect
+
+    for frame_info in inspect.stack():
+        frame_path = Path(frame_info.filename).resolve()
+        # Skip frames that are inside the runspec package itself
+        if "runspec" not in frame_path.parts[-3:]:
+            return frame_path.parent
+
+    # Fallback to current working directory
+    return Path.cwd()
+
+
+def _nudge_poetry() -> None:
+    """Print a one-time informational nudge about [project.scripts]."""
+    import warnings
+
+    warnings.warn(
+        "\nrunspec: Using [tool.poetry.scripts] — consider migrating to [project.scripts]\n"
+        "for better compatibility with modern Python packaging tools.\n"
+        "See: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/\n",
+        stacklevel=4,
+    )