gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/runtime.py

@@ -0,0 +1,150 @@
+"""The ``gateway_env`` handler runtime — the module bundle handlers import.
+
+Generated (or hand-written) ``mock-tools`` handlers are written against this
+FIXED contract::
+
+    from gateway_env import tool, db
+
+    @tool(name="create_refund")
+    def handle(order_id, amount):
+        order = db.one("SELECT * FROM orders WHERE id = ?", order_id)
+        rid = db.insert("refunds", order_id=order_id, amount=amount)
+        return {"ok": True, "refund_id": rid}
+
+``gateway_env`` is importable ONLY while a bundle's handler modules are being
+loaded — the loader injects this module into ``sys.modules`` under that name
+for the duration of the load and restores it after (never globally installed).
+``db`` operations bind to the ACTIVE world's sqlite connection at call time via
+a contextvar, so the same handler object serves every world/branch.
+
+Handlers may also be plain ``def <tool_name>(...)`` functions — the loader
+falls back to discovery by function name == served tool name.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from contextvars import ContextVar
+from typing import Any, Callable, Dict, Optional
+
+__all__ = ["tool", "db", "store"]
+
+#: The active world's sqlite connection. Set by ``World.execute`` around each
+#: handler invocation; ``db`` reads it at call time.
+_active_connection: ContextVar[Optional[sqlite3.Connection]] = ContextVar(
+    "gateway_env_active_connection", default=None
+)
+
+#: The registry the loader is currently filling. ``@tool`` registers into it
+#: at module-exec time; outside a bundle load the decorator is a no-op tagger.
+_load_registry: ContextVar[Optional[Dict[str, Callable[..., Any]]]] = ContextVar(
+    "gateway_env_load_registry", default=None
+)
+
+_active_store: ContextVar[Any] = ContextVar("gateway_env_active_store", default=None)
+_strict_registration: ContextVar[bool] = ContextVar("gateway_env_strict_registration", default=False)
+
+
+class _Store:
+    """Entity operations bind to the currently executing schema-backed world."""
+
+    def __getattr__(self, name):
+        if name not in {"get", "list", "insert", "update", "delete", "apply_batch", "lineage"}:
+            raise AttributeError(name)
+        active = _active_store.get()
+        if active is None:
+            raise RuntimeError("gateway_env.store requires an active schema-backed world")
+        return getattr(active, name)
+
+
+store = _Store()
+
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _connection() -> sqlite3.Connection:
+    conn = _active_connection.get()
+    if conn is None:
+        raise RuntimeError(
+            "gateway_env.db has no active world — db.* is only usable while a "
+            "tool handler executes inside a world (world.execute / with env:)."
+        )
+    return conn
+
+
+def _identifier(name: str, what: str) -> str:
+    if not _IDENTIFIER_RE.match(name):
+        raise ValueError(f"invalid {what} name for db.insert: {name!r}")
+    return name
+
+
+class _Db:
+    """Tiny sqlite facade bound to the active world (rows are ``sqlite3.Row``,
+    dict-like: ``row["col"]`` and ``dict(row)`` both work)."""
+
+    def one(self, sql: str, *params: Any) -> Optional[sqlite3.Row]:
+        """First row of the query, or ``None``."""
+        return _connection().execute(sql, params).fetchone()
+
+    def all(self, sql: str, *params: Any) -> list[sqlite3.Row]:
+        """Every row of the query."""
+        return list(_connection().execute(sql, params).fetchall())
+
+    def insert(self, table: str, **cols: Any) -> int:
+        """INSERT one row, returning its rowid. Table/column names are
+        validated as identifiers (values are always bound parameters)."""
+        if _active_store.get() is not None:
+            from .schema import ContractError
+
+            raise ContractError("raw_write", "Use gateway_env.store.insert for schema-backed mutations")
+        if not cols:
+            raise ValueError("db.insert needs at least one column")
+        table_sql = _identifier(table, "table")
+        col_sql = ", ".join(_identifier(col, "column") for col in cols)
+        placeholders = ", ".join("?" for _ in cols)
+        cursor = _connection().execute(
+            f"INSERT INTO {table_sql} ({col_sql}) VALUES ({placeholders})",
+            tuple(cols.values()),
+        )
+        return int(cursor.lastrowid or 0)
+
+    def execute(self, sql: str, *params: Any) -> int:
+        """Run any statement (UPDATE/DELETE/DDL…), returning the affected
+        rowcount (-1 for non-DML per sqlite3 semantics)."""
+        if _active_store.get() is not None:
+            from .schema import ContractError
+
+            raise ContractError("raw_write", "Use gateway_env.store for schema-backed mutations")
+        return _connection().execute(sql, params).rowcount
+
+
+db = _Db()
+
+
+def tool(fn: Optional[Callable[..., Any]] = None, *, name: Optional[str] = None):
+    """Register a handler for a served tool.
+
+    Usable bare (``@tool`` — tool name is the function name) or with an
+    explicit name (``@tool(name="crm.lookup")`` — required when the tool name
+    is not a valid Python identifier). Returns the function unchanged.
+    """
+
+    def register(handler: Callable[..., Any], tool_name: str) -> Callable[..., Any]:
+        handler.__gateway_env_tool__ = tool_name  # type: ignore[attr-defined]
+        registry = _load_registry.get()
+        if registry is not None:
+            if _strict_registration.get() and tool_name in registry:
+                from .schema import ContractError
+
+                raise ContractError("tool", "Duplicate tool handler registration")
+            registry[tool_name] = handler
+        return handler
+
+    if fn is not None and callable(fn):
+        return register(fn, fn.__name__)
+
+    def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+        return register(handler, name or handler.__name__)
+
+    return decorator

gatewaysdk/environment/schema/__init__.py

@@ -0,0 +1,35 @@
+"""Offline executable world contracts: compile, validate, and store state."""
+
+from .compiler import (
+    Contract,
+    bundle_mode,
+    check_bundle,
+    compile_bundle,
+    describe_bundle,
+)
+from .connector import capture as capture_connection
+from .connector import ingest as ingest_captures
+from .connector import load_spec as load_connection
+from .scaffold import init_bundle, list_templates
+from .store import IngestConnection, SQLiteStore
+from .api import build_api_bundle
+from .api import serve as serve_api
+from .validation import ContractError
+
+__all__ = [
+    "Contract",
+    "ContractError",
+    "IngestConnection",
+    "SQLiteStore",
+    "build_api_bundle",
+    "bundle_mode",
+    "capture_connection",
+    "check_bundle",
+    "compile_bundle",
+    "describe_bundle",
+    "ingest_captures",
+    "init_bundle",
+    "list_templates",
+    "load_connection",
+    "serve_api",
+]

gatewaysdk/environment/schema/__main__.py

@@ -0,0 +1,225 @@
+"""Lean CLI, dependency-free: python -m gatewaysdk.environment.schema <command> PATH.
+
+init | templates | compile | check | describe   the world contract
+connector-validate | connector-capture | connector-ingest | conform   its vendor connection
+data-show | data-import                  the rows a local world seeds with
+serve | api-bundle                       the vendor's API served from the world
+skill                                    the packaged skills, printed or installed
+
+Every command is offline and local: it never reads GATEWAY_* keys or reaches a
+host. The platform's sandboxed `run_gateway_cli` runs exactly this module.
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+from . import (
+    ContractError,
+    build_api_bundle,
+    capture_connection,
+    check_bundle,
+    describe_bundle,
+    ingest_captures,
+    init_bundle,
+    list_templates,
+    load_connection,
+    serve_api,
+)
+from .conform import conform
+from .data import entity_counts, entity_rows, import_rows, parse_rows, world_kind
+from .skill import install_skill, next_step, packaged_skills, skill_text
+
+COMMANDS = (
+    "init",
+    "templates",
+    "compile",
+    "check",
+    "describe",
+    "connector-validate",
+    "connector-capture",
+    "connector-ingest",
+    "conform",
+    "data-show",
+    "data-import",
+    "serve",
+    "api-bundle",
+    "skill",
+)
+
+NO_BUNDLE = ("templates", "skill")
+
+
+def _pairs(values):
+    out = {}
+    for item in values or []:
+        if "=" not in item:
+            raise SystemExit(f"expected name=value, got {item!r}")
+        key, value = item.split("=", 1)
+        out[key.strip()] = value
+    return out
+
+
+def _installed_connector(value):
+    """This entry point is offline; a workspace connector needs the platform CLI."""
+    if value.startswith("workspace:"):
+        raise argparse.ArgumentTypeError(
+            "workspace connectors live on the platform; use "
+            "`gateway worlds schema init PATH --connector workspace:<slug>` with GATEWAY_* keys set"
+        )
+    return value
+
+
+def _skill(name, *, list_skills, install, force):
+    """Mirror of ``gateway worlds skill``: list, print, or ``--install DIR`` a packaged skill."""
+    if list_skills or name is None:
+        print(json.dumps({"status": "ok", "skills": packaged_skills()}, sort_keys=True))
+        return
+    if install is None:
+        print(skill_text(name), end="")
+        return
+    report = install_skill(install, name=name, force=force)
+    out = {
+        "status": "rejected" if report.conflicts else "ok",
+        "skill": name,
+        "written": report.written,
+        "unchanged": report.unchanged,
+        "conflicts": report.conflicts,
+        "next": next_step(name),
+    }
+    print(json.dumps(out, sort_keys=True))
+    if report.conflicts:
+        raise SystemExit(1)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Offline Gateway world schema contracts")
+    parser.add_argument("command", choices=COMMANDS)
+    parser.add_argument("bundle", nargs="?", help="world directory (every command but templates and skill); skill: the skill name")
+    parser.add_argument("rows", nargs="*", help="data-import: rows files ({entity: [rows]} JSON, {entity,row} JSONL, or bare rows)")
+    parser.add_argument(
+        "--connector",
+        default="custom",
+        type=_installed_connector,
+        choices=list_templates(),
+        help="init only: connector template to start from (default: custom)",
+    )
+    parser.add_argument("--name", default=None, help="init only: environment name and package id")
+    parser.add_argument("--op", default=None, help="connector-capture: operation name")
+    parser.add_argument("--arg", action="append", help="connector-capture: path argument name=value")
+    parser.add_argument("--param", action="append", help="connector-capture: query parameter name=value")
+    parser.add_argument("--max-pages", type=int, default=None, help="connector-capture: page limit")
+    parser.add_argument("--batch-id", default=None, help="connector-ingest | data-import: batch id")
+    parser.add_argument("--openapi", action="append", help="conform: the vendor's OpenAPI document; repeatable")
+    parser.add_argument("--limit", type=int, default=None, help="conform: check only the first N operations")
+    parser.add_argument("--entity", default=None, help="data-show: print this entity's rows; data-import: the entity bare-row files hold")
+    parser.add_argument("--mode", default="append", help="data-import: append (upsert by primary key) | replace (named entities)")
+    parser.add_argument("--port", type=int, default=8080, help="serve: port")
+    parser.add_argument("--api-key", default=None, help="serve: pin the accepted credential")
+    parser.add_argument("--scenario", default=None, help="serve: start in one of the world's scenarios/<name>")
+    parser.add_argument("--out", default=None, help="api-bundle: empty output directory; conform: write the full report as JSON here")
+    parser.add_argument("--list", action="store_true", help="skill: list the packaged skills and exit")
+    parser.add_argument("--install", default=None, help="skill: repository to install the skill into, under its .claude/")
+    parser.add_argument("--force", action="store_true", help="skill --install: overwrite files whose content differs")
+    args = parser.parse_args(argv)
+    if args.command == "skill":
+        if args.rows:
+            parser.error("skill takes at most one positional argument")
+    elif args.command in NO_BUNDLE:
+        if args.bundle or args.rows:
+            parser.error(f"{args.command} takes no positional argument")
+    elif not args.bundle:
+        parser.error(f"{args.command} needs a world directory")
+    elif args.rows and args.command != "data-import":
+        parser.error(f"{args.command} takes one positional argument")
+    try:
+        if args.command == "templates":
+            print(json.dumps({"status": "ok", "templates": list_templates()}, sort_keys=True))
+            return
+        if args.command == "skill":
+            _skill(args.bundle, list_skills=args.list, install=args.install, force=args.force)
+            return
+        if args.command == "describe":
+            print(describe_bundle(args.bundle), end="")
+            return
+        if args.command == "init":
+            contract = init_bundle(args.bundle, connector=args.connector, name=args.name)
+        elif args.command == "compile":
+            from .compiler import compile_world
+
+            contract, snapshots = compile_world(args.bundle)
+            print(json.dumps({"status": "ok", "domain": contract.target, "snapshots": snapshots}, sort_keys=True))
+            return
+        elif args.command == "check":
+            contract = check_bundle(args.bundle)
+        elif args.command == "connector-validate":
+            spec = load_connection(args.bundle)
+            print(
+                json.dumps({"status": "ok", "slug": spec.slug, "operations": sorted(spec.operations)}, sort_keys=True)
+            )
+            return
+        elif args.command == "connector-capture":
+            if not args.op:
+                raise SystemExit("connector-capture needs --op")
+            files = capture_connection(
+                args.bundle, args.op, _pairs(args.arg), _pairs(args.param), max_pages=args.max_pages
+            )
+            print(json.dumps({"status": "ok", "files": [str(f) for f in files]}, sort_keys=True))
+            return
+        elif args.command == "connector-ingest":
+            print(json.dumps({"status": "ok", **ingest_captures(args.bundle, batch_id=args.batch_id)}, sort_keys=True))
+            return
+        elif args.command == "conform":
+            if not args.openapi:
+                raise SystemExit("conform needs at least one --openapi document")
+            report = conform(args.bundle, args.openapi, max_operations=args.limit)
+            if args.out:
+                Path(args.out).write_text(json.dumps(report.to_json(), indent=2, sort_keys=True) + "\n")
+            print(json.dumps({"status": "ok", **report.to_json()}, sort_keys=True))
+            summary = report.summary
+            if summary["status_mismatch"] or summary["schema_violations"]:
+                raise SystemExit(1)
+            return
+        elif args.command == "data-show":
+            out = {"status": "ok", "kind": world_kind(args.bundle)}
+            if args.entity is None:
+                out["entity_counts"] = entity_counts(args.bundle)
+            else:
+                out["entity"] = args.entity
+                out["rows"] = entity_rows(args.bundle, args.entity)
+            print(json.dumps(out, sort_keys=True))
+            return
+        elif args.command == "data-import":
+            if not args.rows:
+                raise SystemExit("data-import needs at least one rows file")
+            parsed = parse_rows(args.rows, entity=args.entity)
+            result = import_rows(args.bundle, parsed, mode=args.mode, batch_id=args.batch_id)
+            print(json.dumps({"status": "ok", **result}, sort_keys=True))
+            return
+        elif args.command == "serve":
+            server = serve_api(args.bundle, port=args.port, api_key=args.api_key, scenario=args.scenario)
+            try:
+                server.serve_forever()
+            finally:
+                server.server_close()
+                server.world_state.close()
+            return
+        elif args.command == "api-bundle":
+            if not args.out:
+                raise SystemExit("api-bundle needs --out")
+            print(json.dumps({"status": "ok", "bundle": str(build_api_bundle(args.bundle, args.out))}, sort_keys=True))
+            return
+        print(json.dumps({"status": "ok", "domain": contract.target}, sort_keys=True))
+    except ContractError as error:
+        print(json.dumps({"status": "rejected", "error": error.detail}, sort_keys=True))
+        raise SystemExit(1)
+    except KeyError as error:
+        print(json.dumps({"status": "rejected", "error": {"message": str(error.args[0])}}, sort_keys=True))
+        raise SystemExit(1)
+    except (OSError, ValueError) as error:
+        print(json.dumps({"status": "rejected", "error": {"message": str(error)}}, sort_keys=True))
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

gatewaysdk/environment/schema/_slack_fidelity.py

@@ -0,0 +1,116 @@
+"""Slack capability authoring and version-bound coverage reports.
+
+Authoring has exactly two shallow defaults maps. Published entries are expanded,
+so consumers never implement inheritance or infer collection from vendor URLs.
+"""
+
+from copy import deepcopy
+import hashlib
+from pathlib import Path
+
+from .validation import encoded, fail, read_json
+
+TEMPLATE = Path(__file__).with_name("connectors") / "slack"
+
+
+def expand_capabilities(document: dict) -> dict:
+    """Expand v2 author metadata to self-contained v1 entries; overrides replace.
+
+    A list/dictionary override replaces the entire default value. There is no
+    recursive merge, multi-level inheritance, or mutation of the authored input.
+    Already expanded v1 documents remain usable.
+    """
+    result = deepcopy(document)
+    if result.get("format") == "gateway-slack-capabilities/1":
+        return result
+    if result.get("format") != "gateway-slack-capabilities/2":
+        fail("slack_capabilities", "Unsupported capability format", "/capabilities/format")
+    defaults = result.pop("defaults", {})
+    if not isinstance(defaults, dict) or set(defaults) - {"entities", "operations"}:
+        fail("slack_capabilities", "Expected entity and operation defaults", "/capabilities/defaults")
+    for kind in ("entities", "operations"):
+        common = defaults.get(kind, {})
+        entries = result.get(kind)
+        if not isinstance(common, dict) or not isinstance(entries, dict):
+            fail("slack_capabilities", "Expected named capability objects", f"/capabilities/{kind}")
+        for name, entry in entries.items():
+            if not isinstance(entry, dict):
+                fail("slack_capabilities", "Expected a capability object", f"/capabilities/{kind}/{name}")
+            entries[name] = {**deepcopy(common), **entry}
+    result["format"] = "gateway-slack-capabilities/1"
+    return result
+
+
+def load_capabilities() -> dict:
+    return expand_capabilities(read_json(TEMPLATE / "capabilities.json"))
+
+
+def slack_template_digest() -> str:
+    """Match the platform's path-NUL-bytes-NUL hash over shipped Slack files."""
+    root = TEMPLATE
+    digest = hashlib.sha256()
+    for path in sorted(root.rglob("*"), key=lambda p: p.relative_to(root).as_posix()):
+        if not path.is_file() or path.is_symlink() or "__pycache__" in path.parts:
+            continue
+        digest.update(path.relative_to(root).as_posix().encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(path.read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def fidelity_report(contract, evidence, batch, diagnostics=None, *, mapping):
+    synthetic = evidence.get("synthetic") is True
+    capabilities = load_capabilities()
+    counts = {entity: 0 for entity in contract.entities}
+    for mutation in batch["mutations"]:
+        counts[mutation["entity"]] += 1
+    return {
+        "format": "gateway-slack-fidelity/1",
+        "shape": "base",
+        "label": "synthetic" if synthetic else "subset",
+        "source_hash": hashlib.sha256(encoded(evidence)).hexdigest(),
+        "template_digest": slack_template_digest(),
+        "contract_target": contract.target,
+        "package": contract.lock["package"],
+        "lock_digest": hashlib.sha256(encoded(contract.lock)).hexdigest(),
+        "mapping": mapping,
+        "coverage": evidence.get("coverage", {"complete": False}),
+        "capture_policy": {
+            "methods": capabilities["capture_methods"],
+            "description": (
+                "platform_capture describes the hosted connector pipeline, independent of observed counts. "
+                "collected means a directly requested entity; derived means an association or embedded object "
+                "from projected responses. Both remain bounded by selected scope and available fields. "
+                "capture_source is a vendor source reference, not proof the connector calls that method. "
+                "observed_mutations counts this import batch; synthetic_fixture_mutations identifies its invented rows."
+            ),
+        },
+        "checks": {
+            "schema_artifacts": "passed",
+            "initial_state": "passed",
+            "reference_closure": "passed",
+            "live_comparison": "skipped",
+        },
+        "entities": {
+            entity: {
+                **capabilities["entities"][entity],
+                "observed_mutations": counts[entity],
+                "synthetic_fixture_mutations": counts[entity] if synthetic else 0,
+            }
+            for entity in sorted(contract.entities)
+        },
+        "live_replay": {
+            "status": "skipped",
+            "score": None,
+            "reason": "No live response comparison performed by this offline mapper.",
+        },
+        "drift": {
+            "status": "reported",
+            "unknown_fields": sorted(
+                {name for observation in evidence["observations"] for name in observation.get("unknownFields", [])}
+            ),
+            "unmapped_fields": sorted((diagnostics or {}).get("unmapped_fields", [])),
+        },
+        "limitations": capabilities["limitations"],
+    }