monosmith-plugin-sdk 0.1.0__py3-none-any.whl

monosmith_plugin_sdk/__init__.py

@@ -0,0 +1,204 @@
+"""The Python SDK for writing smith plugins.
+
+A plugin is an object with `describe` and one method for each thing it does. `serve` frames the
+JSON-RPC messages, answers `initialize`, derives the capabilities from the methods the object has and
+keeps standard output for the protocol:
+
+    from monosmith_plugin_sdk import contribute_to, serve, task
+
+    class WidgetLint:
+        def describe(self, params):
+            return {"plugin": {"name": "widget-lint", "version": "0.1.0"}, "kind": "convention",
+                    "roles": ["structure"], "languages": ["widget"]}
+
+        def contribute(self, params):
+            return contribute_to(params["projects"], lambda project: {
+                "tasks": {"layout-check": task(["python", "check.py"], cache=True)},
+                "dependsOn": {"lint": ["layout-check"]},
+            })
+
+    if __name__ == "__main__":
+        serve(WidgetLint())
+
+Test it in-process, with the real handshake and framing, and run the checks of `smith plugin check`:
+
+    from monosmith_plugin_sdk import HostOptions, check_plugin, connect_in_process
+
+    with connect_in_process(WidgetLint(), HostOptions(workspace_root=str(tmp_path))) as client:
+        report = check_plugin(client)
+        assert report.ok, report.failures()
+
+The messages of the protocol are `TypedDict`s generated from the protocol's JSON Schema; the wire
+form is the one the Go and TypeScript SDKs write, byte for byte. No runtime dependencies.
+"""
+
+from . import protocol as _protocol
+from .build_dir import BUILD_DIR, build_dir_from_project, in_build_dir, project_build_dir
+from .cancellation import CancelToken, RequestCancelledError
+from .ci import action_step, ci_step, credential
+from .codec import (
+    EncodeError,
+    MessageParseError,
+    ParamsError,
+    decode_params,
+    decode_result,
+    encode_params,
+    encode_result,
+)
+from .concurrency import (
+    CONCURRENCY_UNLIMITED,
+    UNLIMITED_IN_FLIGHT,
+    UNLIMITED_WORKERS,
+    in_flight_limit,
+    is_valid_concurrency,
+    worker_limit,
+)
+from .conformance import CONFORMANCE_STACK, CheckResult, ConformanceReport, check_plugin
+from .framing import FrameReader, FramingError, frame_message
+from .host import (
+    DEFAULT_CALL_TIMEOUT,
+    DEFAULT_CANCEL_GRACE,
+    CallInterruptedError,
+    HostOptions,
+    PluginClient,
+    PluginStreams,
+    StartOptions,
+    connect_in_process,
+    connect_plugin,
+    start_plugin,
+)
+from .jsondoc import JsonDocument, JsonDocumentError
+from .plugin_refs import conflicts_with, describe_ref, is_empty_ref, requires_language
+from .plugin_roles import (
+    ROLES,
+    default_roles,
+    effective_roles,
+    is_additive_role,
+    is_exclusive_role,
+    is_known_role,
+)
+from .projects import (
+    audit_blocks,
+    audit_enabled,
+    is_manifest,
+    project_kind_directory,
+    publishes,
+    resolve_project_kind,
+    set_toolchain,
+    stack_plugins,
+)
+from .protocol import *  # noqa: F403
+from .scaffold import scaffold_data, scaffold_project
+from .serve import (
+    CIContributor,
+    Contributor,
+    DeclarationEditor,
+    DependencyManager,
+    Discoverer,
+    DoctorContributor,
+    Generator,
+    LatestReader,
+    Plugin,
+    Publisher,
+    RegistryReader,
+    Remover,
+    ServeStreams,
+    Versioner,
+    capabilities_of,
+    serve,
+    serve_streams,
+)
+from .tasks import build_task, contribute_to, task
+from .templating import TemplateError, TemplateFileExistsError, render_template, write_templates
+
+__all__ = [
+    *_protocol.__all__,
+    # Writing a plugin.
+    "serve",
+    "Plugin",
+    "Discoverer",
+    "Generator",
+    "Versioner",
+    "Publisher",
+    "RegistryReader",
+    "CIContributor",
+    "DoctorContributor",
+    "Remover",
+    "DependencyManager",
+    "DeclarationEditor",
+    "LatestReader",
+    "Contributor",
+    "CancelToken",
+    "RequestCancelledError",
+    "CONCURRENCY_UNLIMITED",
+    "task",
+    "build_task",
+    "contribute_to",
+    "scaffold_project",
+    "scaffold_data",
+    "action_step",
+    "ci_step",
+    "credential",
+    "BUILD_DIR",
+    "project_build_dir",
+    "build_dir_from_project",
+    "in_build_dir",
+    "ROLES",
+    "default_roles",
+    "effective_roles",
+    "is_known_role",
+    "is_exclusive_role",
+    "is_additive_role",
+    "requires_language",
+    "conflicts_with",
+    "describe_ref",
+    "is_empty_ref",
+    "audit_enabled",
+    "audit_blocks",
+    "is_manifest",
+    "project_kind_directory",
+    "publishes",
+    "resolve_project_kind",
+    "set_toolchain",
+    "stack_plugins",
+    "render_template",
+    "write_templates",
+    "TemplateError",
+    "TemplateFileExistsError",
+    "JsonDocument",
+    "JsonDocumentError",
+    # Testing a plugin.
+    "HostOptions",
+    "StartOptions",
+    "PluginClient",
+    "PluginStreams",
+    "CallInterruptedError",
+    "DEFAULT_CALL_TIMEOUT",
+    "DEFAULT_CANCEL_GRACE",
+    "start_plugin",
+    "connect_plugin",
+    "connect_in_process",
+    "check_plugin",
+    "ConformanceReport",
+    "CheckResult",
+    "CONFORMANCE_STACK",
+    # Building blocks: the wire form of the messages, for tools that speak the protocol themselves.
+    "serve_streams",
+    "ServeStreams",
+    "capabilities_of",
+    "decode_params",
+    "decode_result",
+    "encode_params",
+    "encode_result",
+    "EncodeError",
+    "MessageParseError",
+    "ParamsError",
+    "FrameReader",
+    "FramingError",
+    "frame_message",
+    "UNLIMITED_IN_FLIGHT",
+    "UNLIMITED_WORKERS",
+    "in_flight_limit",
+    "is_valid_concurrency",
+    "worker_limit",
+]

monosmith_plugin_sdk/build_dir/__init__.py

@@ -0,0 +1,5 @@
+"""The directory every build writes into."""
+
+from .build_dir_algorithm import BUILD_DIR, build_dir_from_project, in_build_dir, project_build_dir
+
+__all__ = ["BUILD_DIR", "build_dir_from_project", "in_build_dir", "project_build_dir"]

monosmith_plugin_sdk/build_dir/build_dir_algorithm.py

@@ -0,0 +1,30 @@
+"""Where every build writes its output."""
+
+from __future__ import annotations
+
+BUILD_DIR = "dist"
+"""The directory at the workspace root every build writes into.
+
+It is smith's opinion, so all output is in one place, outside every source tree, and cleaning is
+deleting one folder. A plugin builds a project into `project_build_dir`; `smith doctor` fails a task
+whose outputs fall outside it.
+"""
+
+
+def project_build_dir(root: str) -> str:
+    """Where a project's build goes, workspace-relative: `dist/<project dir>` (`dist/apps/web`)."""
+    return f"{BUILD_DIR}/{root.strip('/')}"
+
+
+def build_dir_from_project(root: str) -> str:
+    """The same directory relative to the project (`../../dist/apps/web`).
+
+    It is what a tool configured from inside the project, or a task's `outputs`, name.
+    """
+    trimmed = root.strip("/")
+    return "../" * len(trimmed.split("/")) + project_build_dir(trimmed)
+
+
+def in_build_dir(path: str) -> bool:
+    """Whether a workspace-relative path is inside the build directory."""
+    return path == BUILD_DIR or path.startswith(f"{BUILD_DIR}/")

monosmith_plugin_sdk/cancellation/__init__.py

@@ -0,0 +1,6 @@
+"""Cooperative cancellation: the token a method watches, and the error it raises when it stops."""
+
+from .cancel_token_model import CancelToken
+from .request_cancelled_error import RequestCancelledError
+
+__all__ = ["CancelToken", "RequestCancelledError"]

monosmith_plugin_sdk/cancellation/cancel_token_model.py

@@ -0,0 +1,75 @@
+"""The token that carries a cancel to the work it concerns."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+
+from .request_cancelled_error import RequestCancelledError
+
+
+class CancelToken:
+    """A flag one thread sets and another watches, to stop work cooperatively.
+
+    The serve loop gives a method one for the request it is answering, and sets it when the
+    host sends `cancel` for the request (or when the plugin shuts down). A host in a test
+    passes one to `PluginClient.call` and sets it to cancel the call.
+
+    The usual loop checks it between steps, and waits on it instead of sleeping:
+
+        for path in files:
+            cancel.raise_if_cancelled()
+            scan(path)
+        if cancel.wait(0.1):   # sleeps up to 0.1 s, and wakes at once on a cancel
+            return partial_result
+    """
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._callbacks: list[Callable[[], None]] = []
+
+    @property
+    def cancelled(self) -> bool:
+        """Whether the work was asked to stop."""
+        return self._event.is_set()
+
+    def cancel(self) -> None:
+        """Ask the work to stop. Calling it again does nothing."""
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._event.set()
+            callbacks, self._callbacks = self._callbacks, []
+        for callback in callbacks:
+            callback()
+
+    def wait(self, timeout: float | None = None) -> bool:
+        """Wait up to `timeout` seconds (forever for `None`); return whether it was cancelled.
+
+        A cancellable sleep: it returns early, with `True`, the moment the token is cancelled.
+        """
+        return self._event.wait(timeout)
+
+    def raise_if_cancelled(self, message: str = "the request was cancelled") -> None:
+        """Raise `RequestCancelledError` when the work was asked to stop."""
+        if self._event.is_set():
+            raise RequestCancelledError(message)
+
+    def on_cancel(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Call `callback` (in the cancelling thread) when the token is cancelled, at once if it already is.
+
+        Returns a function that removes the callback again.
+        """
+        with self._lock:
+            if not self._event.is_set():
+                self._callbacks.append(callback)
+
+                def remove() -> None:
+                    with self._lock:
+                        if callback in self._callbacks:
+                            self._callbacks.remove(callback)
+
+                return remove
+        callback()
+        return lambda: None

monosmith_plugin_sdk/cancellation/request_cancelled_error.py

@@ -0,0 +1,11 @@
+"""The error a method raises to say it stopped because the request was cancelled."""
+
+from __future__ import annotations
+
+
+class RequestCancelledError(Exception):
+    """Raised by a method that noticed its request was cancelled (`CancelToken.raise_if_cancelled`).
+
+    The serve loop answers a cancelled request that fails with any error with the code
+    `REQUEST_CANCELLED`, so raising this is a convenience, not a requirement.
+    """

monosmith_plugin_sdk/ci/__init__.py

@@ -0,0 +1,5 @@
+"""Building the answers of `ci`: steps, provider-native steps and credentials."""
+
+from .ci_contribution_algorithm import action_step, ci_step, credential
+
+__all__ = ["action_step", "ci_step", "credential"]

monosmith_plugin_sdk/ci/ci_contribution_algorithm.py

@@ -0,0 +1,57 @@
+"""Building the answers of `ci`."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from ..protocol import ActionStep, Credential, Step
+
+
+def action_step(uses: str, inputs: Mapping[str, str] | Sequence[tuple[str, str]] | None = None) -> ActionStep:
+    """A provider-native step: a GitHub action (`"actions/setup-node@v6"`) or an Azure task (`"NodeTool@0"`).
+
+    The inputs are written in the order given. The values of a pipeline are written as quoted YAML
+    strings, except `true` and `false`, so pass strings.
+    """
+    pairs = list(inputs.items()) if isinstance(inputs, Mapping) else list(inputs or [])
+    if not pairs:
+        return {"uses": uses}
+    return {"uses": uses, "inputs": [{"name": name, "value": value} for name, value in pairs]}
+
+
+def ci_step(
+    name: str,
+    command: Sequence[str],
+    *,
+    dir: str | None = None,  # noqa: A002 - the protocol's member name
+    blocking: bool = True,
+    cache_files: Sequence[str] | None = None,
+) -> Step:
+    """One command a CI phase (`setup`, `audit`, `postRelease`) runs. It blocks unless `blocking=False`.
+
+    `dir` is the workspace-relative directory to run in (default: the workspace root). `cache_files`
+    are workspace-relative files whose content decides what an audit step finds (a lockfile): smith
+    skips a passing step while they are unchanged.
+    """
+    step: Step = {"name": name, "command": list(command), "blocking": blocking}
+    if dir is not None:
+        step["dir"] = dir
+    if cache_files is not None:
+        step["cacheFiles"] = list(cache_files)
+    return step
+
+
+def credential(
+    env: str, description: str, *, required: bool = True, setup: bool = False, tasks: bool = False
+) -> Credential:
+    """A secret the release phase needs, read from the environment variable `env`.
+
+    `required=False` says release works without it. `setup` also gives it to `smith ci setup` (installs
+    from a private registry need it); `tasks` also gives it to every step that runs tasks.
+    """
+    result: Credential = {"env": env, "description": description, "required": required}
+    if setup:
+        result["setup"] = True
+    if tasks:
+        result["tasks"] = True
+    return result

monosmith_plugin_sdk/codec/__init__.py

@@ -0,0 +1,34 @@
+"""The wire form of the messages: the bytes the Go SDK writes, and params shaped as the types promise."""
+
+from .encode_error import EncodeError
+from .message_parse_error import MessageParseError
+from .method_codec_algorithm import decode_params, decode_result, encode_params, encode_result
+from .params_error import ParamsError
+from .received_message_contract import ReceivedError, ReceivedRequest, ReceivedResponse
+from .wire_message_mapper import (
+    parse_request,
+    parse_response,
+    write_failure,
+    write_notification,
+    write_request,
+    write_result,
+)
+
+__all__ = [
+    "EncodeError",
+    "MessageParseError",
+    "ParamsError",
+    "ReceivedError",
+    "ReceivedRequest",
+    "ReceivedResponse",
+    "decode_params",
+    "decode_result",
+    "encode_params",
+    "encode_result",
+    "parse_request",
+    "parse_response",
+    "write_failure",
+    "write_notification",
+    "write_request",
+    "write_result",
+]

monosmith_plugin_sdk/codec/encode_by_schema_algorithm.py

@@ -0,0 +1,126 @@
+"""Writing a value as the JSON the Go SDK writes for the same message."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from .encode_error import EncodeError
+from .encode_json_value_algorithm import encode_json_string, encode_json_value, format_number
+from .schema_lookup_algorithm import SchemaNode, base_node, is_nullable, kind_of
+
+
+def encode_by_schema(schema: SchemaNode, node: SchemaNode, value: Any, path: str) -> str:
+    """Write a value as the JSON the Go SDK would write for the same message.
+
+    The members of a message come in the order the schema lists them (the order of the Go
+    fields); an optional member is left out when it is absent or holds the zero value Go's
+    `omitempty` drops (`""`, `0`, `false`, an empty list or dict); the keys of a map are sorted;
+    HTML characters are escaped. So the bytes a Python plugin writes equal the bytes a Go
+    plugin writes for the same answer.
+
+    Raises `EncodeError` for a required member that is missing or a value of the wrong type.
+    """
+    kind = kind_of(schema, node)
+    if value is None:
+        if is_nullable(node) or kind == "any":
+            return "null"
+        raise EncodeError(f"{path} is required and cannot be null")
+    base = base_node(schema, node)
+    if kind == "string":
+        if not isinstance(value, str):
+            raise _wrong_type(path, "a string", value)
+        return encode_json_string(value)
+    if kind == "integer":
+        if not _is_integer(value):
+            raise _wrong_type(path, "an integer", value)
+        return str(value)
+    if kind == "number":
+        if isinstance(value, bool) or not isinstance(value, int | float) or not math.isfinite(value):
+            raise _wrong_type(path, "a number", value)
+        return format_number(value, path)
+    if kind == "boolean":
+        if not isinstance(value, bool):
+            raise _wrong_type(path, "a boolean", value)
+        return "true" if value else "false"
+    if kind == "array":
+        if not isinstance(value, list | tuple):
+            raise _wrong_type(path, "an array", value)
+        items = base.get("items") or {}
+        return (
+            "[" + ",".join(encode_by_schema(schema, items, item, f"{path}[{i}]") for i, item in enumerate(value)) + "]"
+        )
+    if kind == "map":
+        if not isinstance(value, Mapping):
+            raise _wrong_type(path, "an object", value)
+        values = base.get("additionalProperties")
+        member_schema: SchemaNode = values if isinstance(values, dict) else {}
+        members = [
+            f"{encode_json_string(str(name))}:{encode_by_schema(schema, member_schema, member, f'{path}.{name}')}"
+            for name, member in sorted(value.items(), key=lambda item: str(item[0]))
+        ]
+        return "{" + ",".join(members) + "}"
+    if kind == "struct":
+        if not isinstance(value, Mapping):
+            raise _wrong_type(path, "an object", value)
+        return _encode_struct(schema, base, value, path)
+    return encode_json_value(value, path)
+
+
+def _encode_struct(schema: SchemaNode, base: SchemaNode, value: Mapping[str, Any], path: str) -> str:
+    properties: dict[str, SchemaNode] = base.get("properties") or {}
+    required = set(base.get("required") or [])
+    members: list[str] = []
+    for name, property_schema in properties.items():
+        member = value.get(name)
+        if name not in required and _is_omitted(schema, property_schema, member):
+            continue
+        if name in required and name not in value:
+            raise EncodeError(f"{path}.{name} is required")
+        members.append(
+            f"{encode_json_string(name)}:{encode_by_schema(schema, property_schema, member, f'{path}.{name}')}"
+        )
+    # Members the schema does not know (a protocol that grew past this SDK) are kept, after the known ones.
+    for name in sorted(str(n) for n in value if n not in properties and value[n] is not None):
+        members.append(f"{encode_json_string(name)}:{encode_json_value(value[name], f'{path}.{name}')}")
+    return "{" + ",".join(members) + "}"
+
+
+def _is_omitted(schema: SchemaNode, property_schema: SchemaNode, member: Any) -> bool:
+    """Go's `omitempty`: absent, null, or the zero value of a scalar, array or map. A struct is never empty."""
+    if member is None:
+        return True
+    kind = kind_of(schema, property_schema)
+    if kind == "string":
+        return bool(member == "")
+    if kind in ("integer", "number"):
+        return not isinstance(member, bool) and member == 0
+    if kind == "boolean":
+        return member is False
+    if kind == "array":
+        return isinstance(member, list | tuple) and len(member) == 0
+    return bool(kind == "map" and isinstance(member, Mapping) and len(member) == 0)
+
+
+def _is_integer(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _wrong_type(path: str, expected: str, value: Any) -> EncodeError:
+    return EncodeError(f"{path} must be {expected}, not {describe_type(value)}")
+
+
+def describe_type(value: Any) -> str:
+    """How an error names the type of a JSON value."""
+    if isinstance(value, bool):
+        return "a boolean"
+    if isinstance(value, str):
+        return "a string"
+    if isinstance(value, int | float):
+        return "a number"
+    if isinstance(value, list | tuple):
+        return "an array"
+    if isinstance(value, Mapping):
+        return "an object"
+    return f"a {type(value).__name__}"

monosmith_plugin_sdk/codec/encode_error.py

@@ -0,0 +1,11 @@
+"""The error of a value that cannot be written as the message the schema describes."""
+
+from __future__ import annotations
+
+
+class EncodeError(Exception):
+    """A value that cannot be written as the message the schema describes.
+
+    A required member is missing, or a member has the wrong type. The serve loop answers it
+    with the code `INTERNAL_ERROR`.
+    """

monosmith_plugin_sdk/codec/encode_json_value_algorithm.py

@@ -0,0 +1,81 @@
+"""Writing JSON the way Go's `encoding/json` writes it."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from decimal import Decimal
+from typing import Any
+
+from .encode_error import EncodeError
+
+_LONE_SURROGATE = re.compile("[\ud800-\udfff]")
+_GO_ESCAPES = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    "&": "\\u0026",
+    "
": "\\u2028",
+    "
": "\\u2029",
+}
+_GO_ESCAPED = re.compile("[<>&

]")
+
+
+def encode_json_string(text: str) -> str:
+    """A string as the Go SDK writes it.
+
+    JSON escaping with the characters left as they are (never `\\uXXXX` for a non-ASCII
+    letter), and `<`, `>`, `&`, U+2028 and U+2029 as `\\u` escapes, because Go's `json.Marshal`
+    escapes HTML by default. Both forms decode to the same text; writing Go's makes the bytes
+    of the two SDKs equal. A lone surrogate, which has no UTF-8 form, becomes U+FFFD as Go
+    writes invalid UTF-8.
+    """
+    cleaned = _LONE_SURROGATE.sub("�", text)
+    return _GO_ESCAPED.sub(lambda match: _GO_ESCAPES[match.group()], json.dumps(cleaned, ensure_ascii=False))
+
+
+def format_number(value: int | float, path: str) -> str:
+    """A number as Go writes it: an integer as digits, a float in its shortest form."""
+    if isinstance(value, int):
+        return str(value)
+    if not math.isfinite(value):
+        raise EncodeError(f"{path}: {value} cannot be written as JSON")
+    if value == 0:
+        return "-0" if math.copysign(1.0, value) < 0 else "0"
+    magnitude = abs(value)
+    shortest = Decimal(repr(value))
+    if magnitude < 1e-6 or magnitude >= 1e21:
+        digits = shortest.as_tuple().digits
+        exponent = shortest.adjusted()
+        mantissa = f"{digits[0]}" + (f".{''.join(map(str, digits[1:])).rstrip('0')}" if len(digits) > 1 else "")
+        mantissa = mantissa.removesuffix(".")
+        sign = "-" if value < 0 else ""
+        # Go writes the exponent with at least two digits, except e-0N, which it cleans up to e-N.
+        exponent_text = f"{abs(exponent):02d}"
+        if exponent < 0 and exponent_text.startswith("0"):
+            exponent_text = exponent_text[1:]
+        return f"{sign}{mantissa}e{'-' if exponent < 0 else '+'}{exponent_text}"
+    text = format(shortest, "f")
+    return text.rstrip("0").rstrip(".") if "." in text else text
+
+
+def encode_json_value(value: Any, path: str) -> str:
+    """Any JSON value as the Go SDK writes a `map[string]any`: object keys sorted by their UTF-8 bytes."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return encode_json_string(value)
+    if isinstance(value, int | float):
+        return format_number(value, path)
+    if isinstance(value, Mapping):
+        members = [
+            f"{encode_json_string(str(name))}:{encode_json_value(member, f'{path}.{name}')}"
+            for name, member in sorted(value.items(), key=lambda item: str(item[0]))
+        ]
+        return "{" + ",".join(members) + "}"
+    if isinstance(value, list | tuple):
+        return "[" + ",".join(encode_json_value(item, f"{path}[{i}]") for i, item in enumerate(value)) + "]"
+    raise EncodeError(f"{path}: a {type(value).__name__} cannot be written as JSON")

monosmith_plugin_sdk/codec/message_parse_error.py

@@ -0,0 +1,10 @@
+"""The error of a frame body that is not a JSON-RPC 2.0 message."""
+
+from __future__ import annotations
+
+
+class MessageParseError(Exception):
+    """A frame whose body is not a JSON-RPC 2.0 message of the shape the protocol uses.
+
+    The serve loop answers it with the code `PARSE_ERROR`.
+    """