@withgateway/sdk 0.6.0 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -1,25 +1,33 @@
1
- """Initialize a schema world from a connector template or the custom template.
1
+ """Initialize a schema world from a connector template's files, or from the blank ``custom`` scaffold.
2
2
 
3
- Templates are authored ``gateway-world/1`` contracts shipped with the SDK, one
4
- directory per connector under ``connectors/``. Initializing copies the authored
5
- files, compiles them, and writes an empty initial batch; the world starts with
6
- no records and is filled by ingestion or by hand-authored fixture batches.
3
+ Vendor templates are official worlds on the platform: each is a schema world built from its
4
+ template (:func:`init_bundle_from_files`), and a world made from one is that world copied under
5
+ its own name and compiled again (:func:`init_bundle_from_world`), never a vendor directory.
6
+ ``custom`` is the one template that ships in code. Initializing places the authored files,
7
+ compiles them and writes an empty initial batch; the world starts with no records.
7
8
  """
8
9
 
9
10
  from __future__ import annotations
10
11
 
11
12
  import base64
12
13
  import binascii
14
+ import hashlib
13
15
  import json
16
+ import re
14
17
  import shutil
15
18
  from pathlib import Path
19
+ from typing import Any, Callable, Mapping
16
20
 
17
- from .compiler import Contract, compile_bundle
21
+ from .._toml import tomllib
22
+ from .compiler import CompilePlan, Contract, compile_bundle, retarget_journals
18
23
  from .store_contract import describe_store
19
- from .validation import ContractError, encoded, fail, read_json
24
+ from .template_record import RECORD as TEMPLATE_RECORD, TemplateRecord
25
+ from .ui import UiDeclaration
26
+ from .validation import ContractError, encoded, fail, parse_json, tree_path
20
27
 
21
28
  TEMPLATES = Path(__file__).resolve().parent / "connectors"
22
29
  CUSTOM = "custom"
30
+ TEMPLATE_SLUG = re.compile(r"[a-z][a-z0-9-]*")
23
31
  MANIFEST = """[environment]
24
32
  name = "{name}"
25
33
  kind = "schema"
@@ -67,8 +75,6 @@ and body as the vendor's refusal; any other exception is answered 500 {error: "e
67
75
  """
68
76
  '''
69
77
 
70
-
71
- #: Where the template module's docstring ends and its example tools begin.
72
78
  _DOCSTRING_END = '\n"""\n'
73
79
 
74
80
 
@@ -94,10 +100,26 @@ def custom_handlers_source(template_handlers: bytes, with_example_tool: bool) ->
94
100
  return (doc + end).encode("utf-8")
95
101
 
96
102
 
103
+ SUPPORTING_SUFFIXES = {".json", ".md", ".toml"}
104
+ GENERATED_NAMES = {"base.json", "runtime.json", "lock.json", "README.md", "tool-schemas.json", "template.json"}
105
+ #: Template subdirectories copied verbatim to the world root: the connection's
106
+ #: Python (``api/handlers.py``), its served scenarios (``scenarios/…``), the
107
+ #: tests it ships for its tools (``tests/…``, run by ``gateway worlds test``) and its ``ui/``.
108
+ TEMPLATE_DIRECTORIES = {"api", "scenarios", "tests", "ui"}
109
+ #: Template files compile does not lay out, copied to the world root after it, so a world keeps every
110
+ #: file its template brought: the twin of ``splitCarriedTemplateFiles``
111
+ #: (gateway/packages/shared/src/domain/worldSchema.ts).
112
+ CARRIED_DIRECTORIES = {"verifiers", "openapi", "readers", "evidence", "reports"}
113
+ CARRIED_FILES = {"tasks.json"}
114
+ SCHEMA_CONTRACT = "schema/world.json"
115
+ WORLD_MANIFEST = "gateway-env.toml"
116
+ HANDLER_PATHS = ("handlers.py", "tools/handlers.py")
117
+ PLACED_ELSEWHERE = {"world.json", *HANDLER_PATHS}
118
+
119
+
97
120
  def list_templates() -> list[str]:
98
- """Connector slugs that ``init_bundle`` accepts, custom last."""
99
- slugs = sorted(p.name for p in TEMPLATES.iterdir() if (p / "world.json").is_file())
100
- return [s for s in slugs if s != CUSTOM] + [CUSTOM]
121
+ """The templates this runtime holds: the blank ``custom`` scaffold. Vendor templates live on the platform."""
122
+ return [CUSTOM]
101
123
 
102
124
 
103
125
  def _slug(value: str, location: str) -> str:
@@ -106,44 +128,33 @@ def _slug(value: str, location: str) -> str:
106
128
  return value
107
129
 
108
130
 
131
+ def refuse_official(connector: str, door: str, location: str = "/init/connector") -> str:
132
+ """``connector`` when it names the ``custom`` scaffold; any other slug is an official
133
+ template this runtime does not hold, refused naming the ``door`` that takes its files."""
134
+ slug = _slug(connector, location)
135
+ if slug != CUSTOM:
136
+ fail("template", f"{slug} is an official template on the platform: send its files with {door}", location)
137
+ return slug
138
+
139
+
109
140
  def _resource(path: Path) -> Path:
110
141
  if path.is_symlink() or path.parent.is_symlink() or not path.is_file():
111
142
  fail("template", "Template resources must be regular files, not symlinks", str(path))
112
143
  return path
113
144
 
114
145
 
115
- SUPPORTING_SUFFIXES = {".json", ".md", ".toml"}
116
- GENERATED_NAMES = {"base.json", "runtime.json", "lock.json", "README.md", "tool-schemas.json"}
117
- #: Template files that are not schema artifacts but travel with a workspace connector.
118
- TEMPLATE_CODE = {"handlers.py", "api/handlers.py"}
119
- #: Template subdirectories copied verbatim to the world root: the connection's
120
- #: Python (``api/handlers.py``), its served scenarios (``scenarios/…``) and the
121
- #: tests it ships for its tools (``tests/…``, run by ``gateway worlds test``).
122
- TEMPLATE_DIRECTORIES = {"api", "scenarios", "tests", "ui"}
123
- #: Template subdirectories that stay with the connector package and never enter a
124
- #: world: authoring evidence, fidelity reports, and ``readers/`` — how the platform
125
- #: fills a world on this contract from a live connection (``readers/merge.toml``
126
- #: names the tools to pull, ``readers/merge.ingest.toml`` maps their payloads).
127
- CONNECTOR_ONLY_DIRECTORIES = {"evidence", "reports", "readers"}
128
-
129
-
130
146
  def _template_directory_files(directory: Path) -> list[Path]:
131
- files = []
132
- for path in sorted(directory.rglob("*")):
133
- if "__pycache__" in path.parts:
134
- continue
135
- if path.is_dir() and not path.is_symlink():
136
- continue
137
- files.append(_resource(path))
138
- return files
139
-
147
+ paths = sorted(directory.rglob("*"))
148
+ link = next((path for path in paths if path.is_symlink() or path.parent.is_symlink()), None)
149
+ if link is not None:
150
+ fail("template", "Template resources must be regular files, not symlinks", str(link))
151
+ return [path for path in paths if path.is_file() and "__pycache__" not in path.parts]
140
152
 
141
- def template_digest(files: dict[str, bytes]) -> str:
142
- """The same digest the platform computes over an installed template directory:
143
- sha256 over sorted ``path\0bytes\0``. A workspace connector's commit and an
144
- installed template with identical files therefore pin identically."""
145
- import hashlib
146
153
 
154
+ def template_digest(files: Mapping[str, bytes]) -> str:
155
+ """The same digest the platform computes over a template's files: sha256 over sorted
156
+ ``path\0bytes\0``. A workspace connector's commit and an official template with
157
+ identical files therefore pin identically."""
147
158
  digest = hashlib.sha256()
148
159
  for path in sorted(files):
149
160
  digest.update(path.encode("utf-8"))
@@ -153,65 +164,151 @@ def template_digest(files: dict[str, bytes]) -> str:
153
164
  return digest.hexdigest()
154
165
 
155
166
 
156
- def init_bundle_from_files(
157
- destination: str | Path, files: dict[str, bytes], *, connector: str, name: str | None = None
158
- ) -> Contract:
159
- """Create and compile a schema world from a template held in memory: a workspace
160
- connector's files (``world.json``, ``connector.toml``, ``provenance.json``,
161
- ``scope.toml``, ``handlers.py``, ``api/handlers.py``, ``scenarios/…``, ``tests/…``), exactly
162
- what :func:`init_bundle` reads from an installed template directory.
163
-
164
- ``connector`` names the template for the manifest; ``name`` the world."""
165
- destination = Path(destination)
166
- connector = _slug(connector, "/init/connector")
167
- name = _slug(name if name is not None else f"{connector}-world", "/init/name")
168
- if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
169
- fail("state_exists", "Destination must be a new or empty directory", "/init")
170
- if "world.json" not in files:
171
- fail("template", "A connector template needs world.json", "/init/files")
172
- if not all(isinstance(k, str) and k and not k.startswith("/") and ".." not in k.split("/") for k in files):
173
- fail("template", "Template paths must be relative and stay inside the template", "/init/files")
174
- try:
175
- world = json.loads(files["world.json"].decode("utf-8"))
176
- except (UnicodeDecodeError, ValueError):
177
- fail("template", "world.json is not valid JSON", "/init/files/world.json")
178
- if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
179
- fail("template", "world.json is not a gateway-world document", "/init/files/world.json")
180
- world["x-gateway"]["package"]["id"] = name
181
- tools = sorted(world["x-gateway"].get("tools", {}))
167
+ def template_json(files: Mapping[str, bytes], name: str, location: str = "/init/files") -> Any:
168
+ if name not in files:
169
+ fail("template", f"The template carries no {name}", f"{location}/{name}")
182
170
  try:
183
- (destination / "schema").mkdir(parents=True)
184
- (destination / "schema/world.json").write_bytes(_pretty(world))
185
- shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
171
+ return parse_json(files[name].decode("utf-8"), name)
172
+ except ContractError:
173
+ raise
174
+ except ValueError:
175
+ fail("template", f"{name} is not valid JSON", f"{location}/{name}")
176
+
177
+
178
+ def _pretty(value) -> bytes:
179
+ return (json.dumps(value, indent=2) + "\n").encode("utf-8")
180
+
181
+
182
+ def _published_slack_capabilities(files: Mapping[str, bytes]) -> bytes:
183
+ from ._slack_fidelity import load_capabilities
184
+
185
+ return _pretty(load_capabilities(files, "capabilities.json"))
186
+
187
+
188
+ #: Authored files a template publishes in another form: Slack's capabilities are
189
+ #: expanded, so no reader of a world resolves the authoring defaults.
190
+ RENDERED: dict[tuple[str, str], Callable[[Mapping[str, bytes]], bytes]] = {
191
+ ("slack", "capabilities.json"): _published_slack_capabilities,
192
+ }
193
+
194
+
195
+ class WorldTemplate:
196
+ """A connector template held in memory, ``{template-relative path: bytes}``: what a world
197
+ is initialized from (``world.json``, ``connector.toml``, ``handlers.py``, ``provenance.json``,
198
+ ``scope.toml``, ``api/…``, ``scenarios/…``, ``tests/…``, ``ui/…``). ``location`` names the
199
+ files in refusals."""
200
+
201
+ def __init__(self, files: Mapping[str, bytes], location: str = "/init/files") -> None:
202
+ self.files = dict(files)
203
+ self.location = location
204
+
205
+ @property
206
+ def digest(self) -> str:
207
+ return template_digest(self.files)
208
+
209
+ def world(self) -> dict:
210
+ if "world.json" not in self.files:
211
+ fail("template", "A connector template needs world.json", self.location)
212
+ world = template_json(self.files, "world.json", self.location)
213
+ if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
214
+ fail("template", "world.json is not a gateway-world document", f"{self.location}/world.json")
215
+ return world
216
+
217
+ def summary(self, slug: str) -> dict:
218
+ """What a template listing shows; never runs the template's Python."""
219
+ world = self.world()
220
+ gateway = world["x-gateway"]
221
+ return {
222
+ "slug": slug,
223
+ "name": world.get("title") if isinstance(world.get("title"), str) else None,
224
+ "description": world.get("description") if isinstance(world.get("description"), str) else None,
225
+ "entities": self._names(gateway, "entities"),
226
+ "tools": self._names(gateway, "tools"),
227
+ "hasConnection": "connector.toml" in self.files,
228
+ "ui": UiDeclaration.kind_of(self.files.get("connector.toml")),
229
+ }
230
+
231
+ def _names(self, gateway: dict, key: str) -> list[str]:
232
+ value = gateway.get(key) or {}
233
+ names = list(value) if isinstance(value, (dict, list)) else None
234
+ if names is None or not all(isinstance(name, str) for name in names):
235
+ fail(
236
+ "template",
237
+ f'"x-gateway".{key} must be an object or a list of names',
238
+ f"{self.location}/world.json",
239
+ )
240
+ return sorted(names)
241
+
242
+ def write(self, destination: str | Path, *, connector: str, name: str | None = None) -> Contract:
243
+ """Lay the template out as a world at ``destination`` (new or empty) and compile it.
244
+ ``connector`` names the template in the manifest; ``name`` the world and its package
245
+ id. The domain ``$id`` stays the template's, so worlds built from one template share
246
+ a domain identity."""
247
+ destination = _fresh(destination)
248
+ connector = _slug(connector, "/init/connector")
249
+ name = _slug(name if name is not None else f"{connector}-world", "/init/name")
250
+ world = self._named(self.world(), name)
251
+ placed = self._placed(connector)
252
+ if not world["x-gateway"].get("entities"):
253
+ fail("template", "world.json declares no entities", f"{self.location}/world.json")
254
+ try:
255
+ return self._lay_out(destination, world, placed, name=name, connector=connector)
256
+ except BaseException:
257
+ shutil.rmtree(destination, ignore_errors=True)
258
+ raise
259
+
260
+ def _named(self, world: dict, name: str) -> dict:
261
+ if not isinstance(world["x-gateway"].get("package"), dict):
262
+ fail("template", "world.json declares no x-gateway.package", f"{self.location}/world.json")
263
+ world["x-gateway"]["package"]["id"] = name
264
+ return world
265
+
266
+ def _handlers(self) -> bytes:
267
+ handlers = self.files.get("handlers.py") or self.files.get("tools/handlers.py")
268
+ return handlers if handlers is not None else b""
269
+
270
+ def _target(self, path: str) -> str | None:
271
+ """Where an authored file lands in the world; None when it stays with the template."""
272
+ parts = path.split("/")
273
+ if path in PLACED_ELSEWHERE or path in GENERATED_NAMES or "__pycache__" in parts:
274
+ return None
275
+ if path == "connector.toml" or _carried(path) or (parts[0] in TEMPLATE_DIRECTORIES and len(parts) > 1):
276
+ return path
277
+ if len(parts) == 1 and Path(path).suffix in SUPPORTING_SUFFIXES and path not in GENERATED_NAMES:
278
+ return f"schema/{path}"
279
+ fail("template", "Unsupported or generated template artifact", f"{self.location}/{path}")
280
+
281
+ def _placed(self, connector: str) -> dict[str, bytes]:
282
+ _confined(self.files, self.location)
283
+ placed = {}
284
+ for path in sorted(self.files):
285
+ target = self._target(path)
286
+ if target is not None:
287
+ placed[target] = self._content(connector, path)
288
+ return placed
289
+
290
+ def _content(self, connector: str, path: str) -> bytes:
291
+ render = RENDERED.get((connector, path))
292
+ return render(self.files) if render is not None else self.files[path]
293
+
294
+ def _lay_out(
295
+ self, destination: Path, world: dict, placed: dict[str, bytes], *, name: str, connector: str
296
+ ) -> Contract:
297
+ tools = sorted(world["x-gateway"].get("tools") or {})
298
+ entity = min(world["x-gateway"]["entities"])
299
+ self._lay_out_schema(destination, world, placed)
186
300
  (destination / "tools").mkdir()
187
- handlers = files.get("handlers.py") or files.get("tools/handlers.py")
188
- (destination / "tools/handlers.py").write_bytes(handlers if handlers is not None else b"")
189
- for path, content in sorted(files.items()):
190
- if path in {"world.json", "handlers.py", "tools/handlers.py"} or path.startswith("__pycache__"):
191
- continue
192
- if path == "connector.toml":
193
- target = destination / "connector.toml"
194
- elif path.startswith(("api/", "scenarios/", "tests/", "ui/")):
195
- target = destination / path
196
- elif path.split("/", 1)[0] in CONNECTOR_ONLY_DIRECTORIES:
197
- continue # evidence, reports and reader plans stay with the connector, not the world
198
- elif (
199
- Path(path).suffix in SUPPORTING_SUFFIXES and Path(path).name not in GENERATED_NAMES and "/" not in path
200
- ):
201
- target = destination / "schema" / path
202
- else:
203
- fail("template", "Unsupported or generated template artifact", f"/init/files/{path}")
204
- target.parent.mkdir(parents=True, exist_ok=True)
205
- target.write_bytes(content)
301
+ (destination / "tools/handlers.py").write_bytes(self._handlers())
302
+ _write(
303
+ destination,
304
+ {target: content for target, content in placed.items() if not _carried(target) and not _schema(target)},
305
+ )
206
306
  (destination / "gateway-env.toml").write_text(
207
307
  MANIFEST.format(name=name, connector=connector, serve=", ".join(f'"{t}"' for t in tools)),
208
308
  encoding="utf-8",
209
309
  )
210
- entities = sorted(world["x-gateway"].get("entities", {}))
211
- if not entities:
212
- fail("template", "world.json declares no entities", "/init/files/world.json")
213
- (destination / "verifiers").mkdir()
214
- (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=entities[0]), encoding="utf-8")
310
+ (destination / "verifiers").mkdir(exist_ok=True)
311
+ (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=entity), encoding="utf-8")
215
312
  contract = compile_bundle(destination)
216
313
  (destination / "data").mkdir()
217
314
  (destination / "data/initial.json").write_bytes(
@@ -225,144 +322,192 @@ def init_bundle_from_files(
225
322
  }
226
323
  )
227
324
  )
228
- except BaseException:
229
- shutil.rmtree(destination, ignore_errors=True)
230
- raise
231
- return contract
325
+ _write(destination, {target: content for target, content in placed.items() if _carried(target)})
326
+ TemplateRecord.of_world(destination, connector=connector, digest=self.digest).write(destination)
327
+ return contract
232
328
 
329
+ def lay_out_schema(self, destination: Path) -> None:
330
+ """The schema documents :meth:`write` resolves (``world.json``, the packaged ``base.json`` and the
331
+ template's own), uncompiled; the package is not renamed and no rendered file is rendered."""
332
+ self._lay_out_schema(destination, self.world(), self._placed(CUSTOM))
233
333
 
234
- def init_bundle(
235
- destination: str | Path,
236
- *,
237
- connector: str = CUSTOM,
238
- name: str | None = None,
239
- with_example_tool: bool = False,
240
- ) -> Contract:
241
- """Create and compile a schema world at ``destination`` from a template.
242
-
243
- The destination must not exist or must be an empty directory. ``name``
244
- becomes the environment name and package id; the domain ``$id`` stays the
245
- connector's so worlds built from one connector share a domain identity.
246
-
247
- The ``custom`` scaffold is the exception: it is a blank page, not a shared
248
- vendor model, so its ``$id`` is derived from the name
249
- (``urn:gateway:connector:<name>``) and its example tools are left out unless
250
- ``with_example_tool`` asks for them. Authors used to rewrite the ``$id`` and
251
- delete the placeholder tools by hand on every world (Brex retrospective).
252
- """
334
+ @staticmethod
335
+ def _lay_out_schema(destination: Path, world: dict, placed: dict[str, bytes]) -> None:
336
+ (destination / "schema").mkdir(parents=True)
337
+ (destination / "schema/world.json").write_bytes(_pretty(world))
338
+ shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
339
+ _write(destination, {target: content for target, content in placed.items() if _schema(target)})
340
+
341
+
342
+ def _schema(target: str) -> bool:
343
+ return target.startswith("schema/")
344
+
345
+
346
+ class TemplateWorld(WorldTemplate):
347
+ """An official world's head as stored: a schema world built from a connector template, whose
348
+ ``schema/template.json`` (``TemplateRecord``) names the template's digest and the sha256 of every
349
+ file the world holds besides the compiler's outputs. A world made from it is a copy of every file
350
+ it holds under the new world's name, compiled again, so nothing is rebuilt from the template and
351
+ the digest its worlds pin is the one recorded when it was built."""
352
+
353
+ def world(self) -> dict:
354
+ world = template_json(self.files, SCHEMA_CONTRACT, self.location)
355
+ if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
356
+ fail("template", f"{SCHEMA_CONTRACT} is not a gateway-world document", f"{self.location}/{SCHEMA_CONTRACT}")
357
+ return world
358
+
359
+ @property
360
+ def record(self) -> TemplateRecord:
361
+ return TemplateRecord.parse(self.files, self.location)
362
+
363
+ @property
364
+ def digest(self) -> str:
365
+ return self.record.digest
366
+
367
+ def write(self, destination: str | Path, *, connector: str | None = None, name: str | None = None) -> Contract:
368
+ """Copy the world to ``destination`` (new or empty) as ``name`` and compile it there; its data follows
369
+ the renamed contract. Built snapshots are outputs of the official world, not part of the copy."""
370
+ from .snapshot import is_snapshot_output
371
+
372
+ _confined(self.files, self.location)
373
+ record = self.record
374
+ record.verify(self.files, self.location)
375
+ destination = _fresh(destination)
376
+ connector = _slug(connector if connector is not None else record.connector, "/init/connector")
377
+ name = _slug(name if name is not None else f"{connector}-world", "/init/name")
378
+ files = {
379
+ **{path: data for path, data in self.files.items() if not is_snapshot_output(path)},
380
+ SCHEMA_CONTRACT: _pretty(self._named(self.world(), name)),
381
+ WORLD_MANIFEST: self._renamed_manifest(name),
382
+ }
383
+ try:
384
+ _write(destination, files)
385
+ plan = CompilePlan.of(destination)
386
+ retarget_journals(destination, plan.contract)
387
+ contract = plan.write()
388
+ TemplateRecord.of_world(destination, connector=record.connector, digest=record.digest).write(destination)
389
+ return contract
390
+ except BaseException:
391
+ shutil.rmtree(destination, ignore_errors=True)
392
+ raise
393
+
394
+ def _renamed_manifest(self, name: str) -> bytes:
395
+ location = f"{self.location}/{WORLD_MANIFEST}"
396
+ if WORLD_MANIFEST not in self.files:
397
+ fail("template", f"The world carries no {WORLD_MANIFEST}", location)
398
+ text = self.files[WORLD_MANIFEST].decode("utf-8")
399
+ current = tomllib.loads(text).get("environment", {}).get("name")
400
+ line = f'name = "{current}"\n'
401
+ if not isinstance(current, str) or text.count(line) != 1:
402
+ fail("template", "The manifest must name its world once, as [environment] name", location)
403
+ return text.replace(line, f'name = "{name}"\n').encode("utf-8")
404
+
405
+
406
+ def _fresh(destination: str | Path) -> Path:
253
407
  destination = Path(destination)
254
- connector = _slug(connector, "/init/connector")
255
- if connector not in list_templates():
256
- fail(
257
- "template",
258
- f"Unknown connector template; choose one of {', '.join(list_templates())}",
259
- "/init/connector",
260
- )
261
- name = _slug(name if name is not None else f"{connector}-world", "/init/name")
262
408
  if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
263
409
  fail("state_exists", "Destination must be a new or empty directory", "/init")
264
- template = TEMPLATES / connector
265
- # Templates may carry sibling schema dependencies and model evidence. Keep
266
- # every authored artifact in initialized worlds; never silently drop files.
267
- supporting_files = []
268
- code_files = []
269
- for path in sorted(template.iterdir()):
270
- # pip compiles the shipped handler module during installation.
271
- if path.name == "__pycache__" and path.is_dir() and not path.is_symlink():
272
- continue
273
- if path.name in TEMPLATE_DIRECTORIES and path.is_dir() and not path.is_symlink():
274
- # The blank custom world has no tools for the shipped tests to call.
275
- if not (path.name == "tests" and connector == CUSTOM and not with_example_tool):
276
- code_files.extend(_template_directory_files(path))
277
- continue
278
- if path.name in CONNECTOR_ONLY_DIRECTORIES and path.is_dir() and not path.is_symlink():
279
- continue
280
- _resource(path)
281
- if path.name in {"world.json", "handlers.py"}:
282
- continue
283
- if path.suffix not in {".json", ".md", ".toml"} or path.name in {
284
- "base.json",
285
- "runtime.json",
286
- "lock.json",
287
- "README.md",
288
- "tool-schemas.json",
289
- }:
290
- fail("template", "Unsupported or generated template artifact", str(path))
291
- supporting_files.append(path)
292
- world = read_json(_resource(template / "world.json"))
293
- world["x-gateway"]["package"]["id"] = name
294
- handlers = _resource(template / "handlers.py").read_bytes()
295
- if connector == CUSTOM:
410
+ return destination
411
+
412
+
413
+ def _carried(path: str) -> bool:
414
+ parts = path.split("/")
415
+ return path in CARRIED_FILES or (parts[0] in CARRIED_DIRECTORIES and len(parts) > 1)
416
+
417
+
418
+ def _confined(files: Mapping[str, bytes], location: str) -> None:
419
+ for path in files:
420
+ tree_path(path, location)
421
+
422
+
423
+ def _write(destination: Path, files: Mapping[str, bytes]) -> None:
424
+ for target, content in files.items():
425
+ written = destination.joinpath(*tree_path(target).parts)
426
+ written.parent.mkdir(parents=True, exist_ok=True)
427
+ written.write_bytes(content)
428
+
429
+
430
+ class CustomScaffold(WorldTemplate):
431
+ """The blank page, read from code: not a shared vendor model, so its ``$id`` is the
432
+ world's own name (``urn:gateway:connector:<name>``), and its example tools, with the
433
+ tests that call them, enter the world only when ``with_example_tool`` asks."""
434
+
435
+ def __init__(self, with_example_tool: bool = False) -> None:
436
+ directory = TEMPLATES / CUSTOM
437
+ files = {
438
+ path.relative_to(directory).as_posix(): path.read_bytes() for path in _template_directory_files(directory)
439
+ }
440
+ super().__init__(files)
441
+ self.with_example_tool = with_example_tool
442
+
443
+ def _named(self, world: dict, name: str) -> dict:
444
+ world = super()._named(world, name)
296
445
  world["$id"] = f"urn:gateway:connector:{name}"
297
- if not with_example_tool:
446
+ if not self.with_example_tool:
298
447
  world["x-gateway"]["tools"] = {}
299
- handlers = custom_handlers_source(handlers, with_example_tool)
300
- tools = sorted(world["x-gateway"]["tools"])
301
- try:
302
- (destination / "schema").mkdir(parents=True)
303
- (destination / "schema/world.json").write_bytes(_pretty(world))
304
- shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
305
- for path in supporting_files:
306
- # The connection spec sits at the world root, where `worlds connector` and
307
- # `worlds serve` look for it; everything else describes the schema.
308
- target = destination / path.name if path.name == "connector.toml" else destination / "schema" / path.name
309
- if connector == "slack" and path.name == "capabilities.json":
310
- from ._slack_fidelity import expand_capabilities
311
-
312
- target.write_bytes(_pretty(expand_capabilities(read_json(_resource(path)))))
313
- else:
314
- shutil.copyfile(_resource(path), target)
315
- for path in code_files:
316
- target = destination / path.relative_to(template)
317
- target.parent.mkdir(parents=True, exist_ok=True)
318
- shutil.copyfile(path, target)
319
- (destination / "tools").mkdir()
320
- (destination / "tools/handlers.py").write_bytes(handlers)
321
- (destination / "gateway-env.toml").write_text(
322
- MANIFEST.format(
323
- name=name,
324
- connector=connector,
325
- serve=", ".join(f'"{t}"' for t in tools),
326
- ),
327
- encoding="utf-8",
328
- )
329
- first_entity = sorted(world["x-gateway"]["entities"])[0]
330
- (destination / "verifiers").mkdir()
331
- (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=first_entity), encoding="utf-8")
332
- contract = compile_bundle(destination)
333
- # Only the journal: nothing reads a `data/records.json`, and an empty one
334
- # read as a leftover to clean up (Brex retrospective).
335
- (destination / "data").mkdir()
336
- (destination / "data/initial.json").write_bytes(
337
- encoded(
338
- {
339
- "id": f"{name}.initial.v1",
340
- "target": contract.target,
341
- "mapping": {"id": "empty", "version": "1"},
342
- "coverage": "partial",
343
- "mutations": [],
344
- }
345
- )
346
- )
347
- except BaseException:
348
- shutil.rmtree(destination, ignore_errors=True)
349
- raise
350
- return contract
448
+ return world
351
449
 
450
+ def _handlers(self) -> bytes:
451
+ return custom_handlers_source(super()._handlers(), self.with_example_tool)
352
452
 
353
- def _pretty(value) -> bytes:
354
- return (json.dumps(value, indent=2) + "\n").encode("utf-8")
453
+ def _target(self, path: str) -> str | None:
454
+ if path in GENERATED_NAMES:
455
+ fail("template", "Unsupported or generated template artifact", f"{self.location}/{path}")
456
+ if path.startswith("tests/") and not self.with_example_tool:
457
+ return None
458
+ return super()._target(path)
459
+
460
+
461
+ def init_bundle_from_files(
462
+ destination: str | Path, files: Mapping[str, bytes], *, connector: str, name: str | None = None
463
+ ) -> Contract:
464
+ """Create and compile a schema world from a template's files: an official template the
465
+ platform serves, a workspace connector, or a document an importer rendered.
466
+
467
+ ``connector`` names the template for the manifest; ``name`` the world."""
468
+ return WorldTemplate(files).write(destination, connector=connector, name=name)
469
+
470
+
471
+ def init_official_world(destination: str | Path, template_directory: str | Path) -> Contract:
472
+ """The schema world the official organization stores for a template directory: the template built under its
473
+ own slug. A push leaves its checkout record under ``.gateway/``; no dot entry, at any depth, is a template file."""
474
+ directory = Path(template_directory)
475
+ files = {
476
+ path.relative_to(directory).as_posix(): path.read_bytes()
477
+ for path in _template_directory_files(directory)
478
+ if not any(part.startswith(".") for part in path.relative_to(directory).parts)
479
+ }
480
+ return init_bundle_from_files(destination, files, connector=directory.name, name=directory.name)
355
481
 
356
482
 
357
- __all__ = ["CUSTOM", "TEMPLATES", "ContractError", "init_bundle", "list_templates"]
483
+ def init_bundle_from_world(destination: str | Path, files: Mapping[str, bytes], *, name: str | None = None) -> Contract:
484
+ """Create and compile a world from an official world's files: a copy under ``name``."""
485
+ return TemplateWorld(files).write(destination, name=name)
358
486
 
359
487
 
360
- def request_files(request: dict) -> dict[str, bytes]:
361
- """The ``files: [{path, content}]`` of a bridge request as ``{path: bytes}``:
488
+ def init_bundle(
489
+ destination: str | Path,
490
+ *,
491
+ connector: str = CUSTOM,
492
+ name: str | None = None,
493
+ with_example_tool: bool = False,
494
+ ) -> Contract:
495
+ """Create and compile the blank ``custom`` world at ``destination`` (new or empty).
496
+
497
+ ``name`` becomes the environment name and package id. Any other ``connector`` is an
498
+ official template on the platform: fetch its files and build with
499
+ :func:`init_bundle_from_files`."""
500
+ refuse_official(connector, "init_bundle_from_files")
501
+ return CustomScaffold(with_example_tool).write(destination, connector=CUSTOM, name=name)
502
+
503
+
504
+ def request_files(request: dict, key: str = "files", location: str | None = None) -> dict[str, bytes]:
505
+ """The ``[{path, content}]`` under ``key`` of a bridge request as ``{path: bytes}``:
362
506
  what ``init_bundle_from_files`` and the template readers consume."""
363
- listed = request.get("files")
507
+ where = location if location is not None else f"/{key}"
508
+ listed = request.get(key)
364
509
  if not isinstance(listed, list) or not listed:
365
- fail("input", "Expected the template's files as [{path, content}]")
510
+ fail("input", "Expected the template's files as [{path, content}]", where)
366
511
  files: dict[str, bytes] = {}
367
512
  for entry in listed:
368
513
  if (
@@ -370,9 +515,31 @@ def request_files(request: dict) -> dict[str, bytes]:
370
515
  or not isinstance(entry.get("path"), str)
371
516
  or not isinstance(entry.get("content"), str)
372
517
  ):
373
- fail("input", "Each template file is {path, content} with base64 content")
518
+ fail("input", "Each template file is {path, content} with base64 content", where)
519
+ tree_path(entry["path"], where)
520
+ if entry["path"] in files:
521
+ fail("path", f"{entry['path']} is sent twice", where)
374
522
  try:
375
523
  files[entry["path"]] = base64.b64decode(entry["content"], validate=True)
376
524
  except (ValueError, binascii.Error):
377
- fail("input", "Template file content must be base64")
525
+ fail("input", "Template file content must be base64", where)
378
526
  return files
527
+
528
+
529
+ __all__ = [
530
+ "CUSTOM",
531
+ "TEMPLATES",
532
+ "TEMPLATE_SLUG",
533
+ "ContractError",
534
+ "CustomScaffold",
535
+ "TemplateWorld",
536
+ "WorldTemplate",
537
+ "init_bundle",
538
+ "init_bundle_from_files",
539
+ "init_bundle_from_world",
540
+ "init_official_world",
541
+ "list_templates",
542
+ "refuse_official",
543
+ "request_files",
544
+ "template_digest",
545
+ ]