instruction.md 0.2.0__py3-none-any.whl

instruction_md/__init__.py

@@ -0,0 +1,56 @@
+"""instruction-md — the instruction.md specification's first edition (``instruction/1``) in Python: the reader and
+its checks, the inline syntax, resolution and the agent's text profile, the registry, the formatter, digests and
+signature verification, and a follower for instructions served over MCP.
+
+    from instruction_md import read, check, resolve, to_text
+    r = read(text)                           # the authored tree (r.document) and the reader's diagnostics
+    diagnostics = check(r)                   # those, with the inline checks, in source order
+    res = resolve(text, uri="agent.md", params={"timezone": "UTC"}, load=sources)
+    res.text                                 # what the agent receives (instruction-text/1)
+    res.resolved.resolved_digest             # the resolved artifact's RFC 8785 digest (instruction-resolved/1)
+
+The reference is the TypeScript package ``@instruction-md/spec`` (``packages/spec``); this port is byte-exact with
+its vectors and with the specification's conformance data, both vendored under ``conformance/``."""
+from __future__ import annotations
+
+from ._yaml import load_csv, load_json, load_yaml
+from .attributes import attributes_end, parse_attributes
+from .check import Target, check, inline_diagnostics, resolve_target
+from .consumer import META, AppliedInstruction, FollowerClient, FollowPolicy, InstructionFollower, McpSessionClient, Report, parse_meta
+from .digest import digest, digest_text, sha256_hex
+from .format import format
+from .inline import InlineToken, inline_tokens, split_wiki
+from .jcs import canonical_json, json_digest
+from .read import ReadResult, read, strip_comments, value_fits, value_from
+from .registry import (
+    BACKMATTER_KEYS, COMMON, FRONT_MATTER_KEYS, INLINE, INLINE_REQUIRED, KEYWORD_FLAGS, KEYWORDS, KINDS, PATTERNS, PRESENTATION_ATTRS, REGISTRY,
+    REGISTRY_VERSION, RULES, TYPED_REFERENCES, AttrSpec, KindSpec, attr_spec, canonical_kind, inline_attr_spec,
+)
+from .resolve import Resolution, Resolved, Source, references_of, resolve, resolve_tree, resolve_uri, resolve_with, slug
+from .text import TextOptions, TextSource, fence, normalize, to_text, value_text
+from .types import (
+    ABSENT, AuthoredDocument, Diagnostic, DirectiveNode, Identity, MarkdownNode, Metadata, Node, Parameter, Range, StructuredValue, document_from_json,
+    node_from_json,
+)
+from .verify import JWK, VerifyResult, public_jwk, sign_jws, verify_author, verify_delivery
+from .workflow import WORKFLOW_COMMON_FIELDS, WORKFLOW_DIALECT, WORKFLOW_KINDS, WORKFLOW_LIMITS, WORKFLOW_REGISTRY, WORKFLOW_SCOPES, WorkflowKind, workflow_diagnostics
+
+__version__ = "0.2.0"
+#: The edition this package reads: front matter's ``spec: "1"``, the tree's ``format: "instruction/1"``.
+SPEC_VERSION = "1"
+
+__all__ = [
+    "__version__", "SPEC_VERSION",
+    "read", "ReadResult", "strip_comments", "value_fits", "value_from", "check", "inline_diagnostics", "resolve_target", "Target",
+    "parse_attributes", "attributes_end", "inline_tokens", "InlineToken", "split_wiki", "load_yaml", "load_json", "load_csv",
+    "to_text", "TextOptions", "TextSource", "normalize", "fence", "value_text",
+    "resolve", "resolve_with", "resolve_tree", "references_of", "resolve_uri", "slug", "Source", "Resolution", "Resolved",
+    "format", "digest", "digest_text", "sha256_hex", "canonical_json", "json_digest",
+    "verify_author", "verify_delivery", "VerifyResult", "sign_jws", "public_jwk", "JWK",
+    "InstructionFollower", "FollowerClient", "FollowPolicy", "Report", "AppliedInstruction", "McpSessionClient", "parse_meta", "META",
+    "AuthoredDocument", "Metadata", "MarkdownNode", "DirectiveNode", "StructuredValue", "Node", "Diagnostic", "Parameter", "Identity", "Range", "ABSENT",
+    "node_from_json", "document_from_json",
+    "REGISTRY", "REGISTRY_VERSION", "KINDS", "COMMON", "INLINE", "KEYWORDS", "KEYWORD_FLAGS", "RULES", "TYPED_REFERENCES", "INLINE_REQUIRED",
+    "PRESENTATION_ATTRS", "PATTERNS", "FRONT_MATTER_KEYS", "BACKMATTER_KEYS", "KindSpec", "AttrSpec", "attr_spec", "inline_attr_spec", "canonical_kind",
+    "workflow_diagnostics", "WORKFLOW_DIALECT", "WORKFLOW_REGISTRY", "WORKFLOW_KINDS", "WORKFLOW_COMMON_FIELDS", "WORKFLOW_LIMITS", "WORKFLOW_SCOPES", "WorkflowKind",
+]

instruction_md/__main__.py

@@ -0,0 +1,195 @@
+"""``python -m instruction_md check|tree|deliver|format FILE`` — the library's document operations, for a shell or a
+CI step — and ``watch URI``: follow an instruction on an instruction.md MCP server (the follower, with the ``mcp``
+extra). ``deliver`` resolves a document's bases and includes from the files beside it, under its directory, never
+above it and never from a URL."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import re
+import sys
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from . import __version__, check, format as format_text, read, resolve
+from .read import value_from
+from .resolve import Source
+from .types import Diagnostic
+
+_PARAM = re.compile(r"([A-Za-z_][A-Za-z0-9_.-]*)=(.*)\Z", re.S)
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+def _line(d: Diagnostic) -> str:
+    """A diagnostic as one line: ``line 3: … [code]``, with the file it came from when that is another one."""
+    return (f"{d.uri}: " if d.uri else "") + (f"line {d.range.start}: " if d.range else "") + f"{d.message}  [{d.code}]"
+
+
+def _params(items: list[str], text: str) -> dict[str, Any]:
+    """``name=value`` arguments, each read as the document declares the parameter (a number, a list, a boolean)."""
+    declared = read(text).parameters
+    out: dict[str, Any] = {}
+    for item in items:
+        m = _PARAM.match(item)
+        if not m:
+            print(f"not a name=value: {item}", file=sys.stderr)
+            raise SystemExit(2)
+        p = declared.get(m.group(1))
+        out[m.group(1)] = value_from(p, m.group(2)) if p else m.group(2)
+    return out
+
+
+def files_under(root: Path) -> Callable[[str], Optional[Source]]:
+    """Sources beside a file: what its ``extends`` and its includes name, read from the file system under the directory
+    it is in (never above it, through a symbolic link either; never a URL)."""
+    top = os.path.realpath(root)
+
+    def load(uri: str) -> Optional[Source]:
+        if _SCHEME.match(uri) and not uri.startswith("file:"):
+            return None
+        path = urllib.request.url2pathname(urllib.parse.urlsplit(uri).path) if uri.startswith("file:") else uri
+        path = os.path.realpath(path)
+        if path != top and not path.startswith(top + os.sep):
+            return None
+        try:
+            return Source(uri, Path(path).read_bytes().decode("utf-8"))
+        except (OSError, UnicodeDecodeError):
+            return None
+
+    return load
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="instruction_md", description="read, check, resolve and format instruction.md files (instruction/1)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name, help_ in (("check", "the reader's diagnostics and the inline checks; exit 1 on errors"), ("tree", "print the authored tree (instruction/1) as JSON"),
+                        ("deliver", "print the text a model receives (instruction-text/1), the bases and includes read from files beside the document"),
+                        ("format", "print the formatted text")):
+        p = sub.add_parser(name, help=help_)
+        p.add_argument("file", type=Path)
+        if name == "deliver":
+            p.add_argument("--param", action="append", default=[], metavar="NAME=VALUE", help="a parameter's value, read as the document declares it")
+            p.add_argument("--resolved", action="store_true", help="print the resolved artifact (instruction-resolved/1) instead")
+    w = sub.add_parser("watch", help="follow an instruction on an MCP server: print each version applied, or why one is held")
+    w.add_argument("uri", help="instruction://{id}[@ref|@vN|@ver_…]")
+    w.add_argument("--url", default=os.environ.get("INSTRUCTION_MD_URL", "https://instruction.md/mcp"))
+    w.add_argument("--token", default=os.environ.get("INSTRUCTION_MD_TOKEN"), help="a bearer token (default INSTRUCTION_MD_TOKEN); it isn't renewed")
+    w.add_argument("--client-id", default=os.environ.get("INSTRUCTION_MD_CLIENT_ID"),
+                   help="sign in as this agent (default INSTRUCTION_MD_CLIENT_ID), with its secret from INSTRUCTION_MD_CLIENT_SECRET, renewed as it expires")
+    w.add_argument("--token-url", default=os.environ.get("INSTRUCTION_MD_TOKEN_URL"), help="the agent's token endpoint (default INSTRUCTION_MD_TOKEN_URL)")
+    w.add_argument("--once", action="store_true", help="read once, apply or hold, report, and exit (6 when held)")
+    w.add_argument("--require-signature", action="store_true")
+    w.add_argument("--require-delivery-signature", action="store_true")
+    w.add_argument("--out", type=Path, help="write each applied version's text here")
+    w.add_argument("--label", default="instruction-md-python", help="the binding's consumer name")
+    w.add_argument("--no-report", action="store_true", help="declare no binding, report nothing")
+    w.add_argument("--freshness", type=float, default=60.0, help="seconds between re-reads (0: notifications only)")
+    a = ap.parse_args(argv)
+    if a.cmd == "watch":
+        return asyncio.run(_watch(a))
+    text = a.file.read_bytes().decode("utf-8")  # (the bytes as stored: a digest covers them, line endings and all)
+    if a.cmd == "check":
+        diagnostics = check(text)
+        for d in diagnostics:
+            print(f"{d.severity}: {_line(d)}", file=sys.stderr)
+        return 1 if any(d.severity == "error" for d in diagnostics) else 0
+    if a.cmd == "tree":
+        r = read(text)
+        print(json.dumps(r.document.to_json(), indent=2, ensure_ascii=False))
+        return 1 if any(d.severity == "error" for d in r.diagnostics) else 0
+    if a.cmd == "deliver":
+        path = a.file.resolve()
+        res = resolve(text, uri=path.as_uri(), params=_params(a.param, text), load=files_under(path.parent))
+        errors = [d for d in res.diagnostics if d.severity == "error"]
+        if errors:
+            for d in errors:
+                print(_line(d), file=sys.stderr)
+            return 1
+        for d in res.diagnostics:
+            print(f"{d.severity}: {_line(d)}", file=sys.stderr)
+        if a.resolved:
+            print(json.dumps(res.resolved.to_json(), indent=2, ensure_ascii=False))
+        else:
+            sys.stdout.write(res.text)
+        return 0
+    sys.stdout.write(format_text(text))
+    return 0
+
+
+PROTOCOL_VERSION = "2026-07-28"
+"""The MCP wire `watch` speaks: stateless, every request whole on its own (no initialize, no Mcp-Session-Id)."""
+
+
+async def _no_subscription(_uri: str) -> None:
+    return None
+
+
+async def _watch(a: argparse.Namespace) -> int:
+    """The follower over the official MCP SDK's streamable HTTP client, as the person or agent the token names."""
+    try:
+        from mcp import Client
+        from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
+        from mcp_types import Implementation
+    except ImportError:
+        print("watch needs the MCP SDK: pip install 'instruction.md[mcp]'", file=sys.stderr)
+        return 2
+    from .consumer import FollowPolicy, InstructionFollower, McpSessionClient, Report
+
+    auth = None
+    if a.client_id:
+        secret = os.environ.get("INSTRUCTION_MD_CLIENT_SECRET")
+        if not secret or not a.token_url:
+            print("--client-id needs INSTRUCTION_MD_CLIENT_SECRET and --token-url (or INSTRUCTION_MD_TOKEN_URL)", file=sys.stderr)
+            return 2
+        from .mcp_auth import ClientCredentials
+
+        auth = ClientCredentials(a.token_url, a.client_id, secret)
+    code = {"held": False}
+
+    def applied(x, _prev) -> None:  # type: ignore[no-untyped-def]
+        print(json.dumps({"event": "applied", "uri": x.uri, "versionId": x.version_id, "number": x.revision, "verified": x.verified, "digest": x.digest}), flush=True)
+        if a.out:
+            a.out.write_text(x.text, encoding="utf-8")
+
+    def held(reason: str, _c) -> None:  # type: ignore[no-untyped-def]
+        code["held"] = True
+        print(json.dumps({"event": "held", "reason": reason}), file=sys.stderr, flush=True)
+
+    headers = {"Authorization": f"Bearer {a.token}"} if a.token and not auth else {}
+    # (stderr carries the JSON lines: the SDK's own notices stay off it)
+    for name in ("mcp", "client"):  # (the SDK's session logs as "client")
+        logging.getLogger(name).setLevel(logging.ERROR)
+    async with create_mcp_http_client(headers=headers, auth=auth) as http:
+        # The 2026-07-28 wire, pinned: no initialize and no session, so any replica of a clustered server answers each
+        # request (the owner, 2026-10-24: "the latest protocol version that does not require session id"); a
+        # subscription is a listen stream. "auto" probes server/discover and picks it too against instruction.md, but
+        # a probe answered with an error (one replica's hiccup) falls back to the session handshake.
+        transport = streamable_http_client(a.url, http_client=http)
+        async with Client(transport, mode=PROTOCOL_VERSION, client_info=Implementation(name="instruction-md-python", version=__version__)) as mcp:
+            client = McpSessionClient(mcp.session)
+            f = InstructionFollower(
+                client=client, uri=a.uri, on_apply=applied, on_hold=held,
+                policy=FollowPolicy(require_signature=a.require_signature, require_delivery_signature=a.require_delivery_signature),
+                freshness_seconds=0 if a.once else a.freshness,
+                report=None if a.no_report else Report(consumer={"label": a.label, "kind": "agent"}, client={"name": "instruction-md-python", "version": __version__}),
+            )
+            client.on_updated = f.notify
+            if a.once:
+                # (read once: nothing to listen for)
+                f.freshness_seconds = 0
+                client.subscribe_resource = _no_subscription  # type: ignore[method-assign]
+            await f.start()
+            if a.once:
+                f.stop()
+                return 0 if f.current and not code["held"] else 6
+            await asyncio.Event().wait()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

instruction_md/_js.py

@@ -0,0 +1,170 @@
+"""What the TypeScript reference gets from JavaScript and a port must spell out: its whitespace (``\\s``, ``trim``), a
+regex ``$`` that is the end of the string, its one number type and how it prints, ``String(value)`` and
+``JSON.stringify``. The text profile and the resolved artifact's digest are byte-exact with the reference, so these
+are too."""
+from __future__ import annotations
+
+import math
+import re
+from functools import lru_cache
+from typing import Any
+
+#: JavaScript's whitespace and line terminators: what ``\\s`` matches and ``trim()`` removes.
+WHITESPACE = "\t\n\v\f\r \u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+S = "[" + WHITESPACE + "]"
+NOT_S = "[^" + WHITESPACE + "]"
+#: ``.``: anything but a line terminator.
+DOT = "[^\n\r\u2028\u2029]"
+
+_SAFE = 2 ** 53
+
+
+def trim(s: str) -> str:
+    return s.strip(WHITESPACE)
+
+
+@lru_cache(maxsize=None)
+def regex(pattern: str) -> re.Pattern[str]:
+    """A registry pattern, whose ``$`` ends the string (Python's would also match before a final newline)."""
+    return re.compile(pattern[:-1] + r"\Z" if pattern.endswith("$") and not pattern.endswith("\\$") else pattern)
+
+
+def truthy(value: Any) -> bool:
+    """JavaScript's truthiness: an empty list or object is true; 0, NaN, "", null and false are not."""
+    if value is None or value is False or value == "":
+        return False
+    if is_number(value):
+        return value == value and value != 0
+    return True
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def number(value: Any) -> Any:
+    """A number as JavaScript holds it: an integer stays one while it is exact (to 2**53), anything else is a double."""
+    if isinstance(value, int) and not isinstance(value, bool):
+        if -_SAFE <= value <= _SAFE:
+            return value
+        # (past a double's range JavaScript reads Infinity; Python's float() would raise)
+        try:
+            return float(value)
+        except OverflowError:
+            return math.inf if value > 0 else -math.inf
+    if isinstance(value, float) and math.isfinite(value) and value.is_integer() and -_SAFE <= value <= _SAFE:
+        return int(value)
+    return value
+
+
+_NUMERIC = re.compile(r"[+-]?(?:Infinity|(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?)\Z")
+_RADIX = re.compile(r"0([xXoObB])([0-9A-Za-z]+)\Z")
+
+
+def to_number(text: str) -> float:
+    """``Number(text)``: decimal (or a 0x, 0o, 0b literal), surrounding whitespace ignored, "" is 0, else NaN."""
+    s = trim(text)
+    if s == "":
+        return 0
+    radix = _RADIX.match(s)
+    if radix:
+        try:
+            return number(int(radix.group(2), {"x": 16, "o": 8, "b": 2}[radix.group(1).lower()]))
+        except ValueError:
+            return math.nan
+    if not _NUMERIC.match(s):
+        return math.nan
+    return number(float(s.replace("Infinity", "inf")))
+
+
+def number_text(value: Any) -> str:
+    """ECMAScript's Number::toString: the shortest digits that round-trip, plainly up to 1e21, else exponential."""
+    if isinstance(value, int):
+        if -_SAFE <= value <= _SAFE:
+            return str(value)
+        value = float(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    mantissa, _, exp = repr(abs(value)).partition("e")
+    whole, _, fraction = mantissa.partition(".")
+    if fraction == "0":
+        fraction = ""
+    digits = (whole + fraction).lstrip("0")
+    # the value is int(digits) * 10**(exp - len(fraction)); ECMAScript's n puts the decimal point n digits in
+    n = len(digits) - len(fraction) + (int(exp) if exp else 0)
+    digits = digits.rstrip("0")
+    k = len(digits)
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * -n + digits
+    e = n - 1
+    return sign + digits[0] + ("." + digits[1:] if k > 1 else "") + "e" + ("+" if e >= 0 else "-") + str(abs(e))
+
+
+def string(value: Any) -> str:
+    """``String(value)``."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if is_number(value):
+        return number_text(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        return ",".join("" if v is None else string(v) for v in value)
+    return "[object Object]"
+
+
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+_NEEDS_ESCAPE = re.compile('["\\\\\x00-\x1f\ud800-\udfff]')
+
+
+def quote(s: str) -> str:
+    """A string as ``JSON.stringify`` writes it (a lone surrogate escaped, every other character as it is)."""
+    return '"' + _NEEDS_ESCAPE.sub(lambda m: _ESCAPES.get(m.group(), "\\u%04x" % ord(m.group())), s) + '"'
+
+
+def stringify(value: Any, sort_keys: Any = None, strict: bool = False) -> str:
+    """``JSON.stringify(value)`` without spaces (a non-finite number as null, or with ``strict`` an error); with
+    ``sort_keys``, an object's keys in that order (a key function)."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return quote(value)
+    if is_number(value):
+        if isinstance(value, float) and not math.isfinite(value):
+            if strict:
+                raise ValueError("JSON has no non-finite numbers")
+            return "null"
+        return number_text(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(stringify(v, sort_keys, strict) for v in value) + "]"
+    if isinstance(value, dict):
+        keys = sorted(value, key=sort_keys) if sort_keys else list(value)
+        return "{" + ",".join(quote(k) + ":" + stringify(value[k], sort_keys, strict) for k in keys) + "}"
+    raise TypeError(f"JSON cannot carry a {type(value).__name__}")
+
+
+def object_order(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """An object's keys in JavaScript's order: the array indices first, ascending, then the rest as they came."""
+    index = [p for p in pairs if _ARRAY_INDEX.match(p[0]) and int(p[0]) < 4294967295]
+    if not index:
+        return dict(pairs)
+    rest = [p for p in pairs if not (_ARRAY_INDEX.match(p[0]) and int(p[0]) < 4294967295)]
+    return dict(sorted(index, key=lambda p: int(p[0])) + rest)
+
+
+_ARRAY_INDEX = re.compile(r"(?:0|[1-9][0-9]*)\Z")