@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.
- package/dist/agents/index.d.mts +581 -0
- package/dist/agents/index.d.ts +581 -0
- package/dist/agents/index.js +1473 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1424 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +11611 -6845
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +10090 -5325
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +371 -102
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +371 -102
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
- package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +3177 -748
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2987 -590
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- package/dist/traces/index.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +371 -102
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +371 -102
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +1986 -1746
- package/dist/worlds/index.d.ts +1986 -1746
- package/dist/worlds/index.js +1470 -290
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1465 -286
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
- package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
- package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
- package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
- package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
- package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
- package/runtime/gatewaysdk/environment/schema/api.py +3 -4
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
- package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
- package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
- package/runtime/gatewaysdk/environment/schema/host.py +94 -12
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
- package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
- package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
- package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
- package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
- package/runtime/gatewaysdk/environment/schema/local.py +32 -7
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
- package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
- package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
- package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
- package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
- package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
- package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
- package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
- package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/SKILL.md +2 -2
- package/skills/connector-schema-authoring/connector-worlds.md +3 -2
- package/skills/connector-schema-authoring/world-schema.md +36 -23
- package/skills/factory-orchestrator/SKILL.md +147 -0
- package/skills/world-data-ingestion/ROWS.md +5 -1
- package/skills/world-data-ingestion/SKILL.md +8 -6
- package/skills/worlds-getting-started/SKILL.md +9 -9
- package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- package/dist/media-BIApiPzS.d.ts +0 -102
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@withgateway/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.3",
|
|
4
4
|
"description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -81,6 +81,11 @@
|
|
|
81
81
|
"import": "./dist/hooks/index.mjs",
|
|
82
82
|
"require": "./dist/hooks/index.js"
|
|
83
83
|
},
|
|
84
|
+
"./agents": {
|
|
85
|
+
"types": "./dist/agents/index.d.ts",
|
|
86
|
+
"import": "./dist/agents/index.mjs",
|
|
87
|
+
"require": "./dist/agents/index.js"
|
|
88
|
+
},
|
|
84
89
|
"./cli": {
|
|
85
90
|
"types": "./dist/cli.d.ts",
|
|
86
91
|
"import": "./dist/cli.mjs",
|
|
@@ -0,0 +1,531 @@
|
|
|
1
|
+
"""Stdlib only: the runner vendors this package."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import re
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from ._toml import tomllib
|
|
11
|
+
|
|
12
|
+
BUNDLE_MANIFEST = "gateway-bundle.toml"
|
|
13
|
+
MIN_BUNDLE_MEMBERS = 1
|
|
14
|
+
MAX_BUNDLE_MEMBERS = 48
|
|
15
|
+
BUNDLE_NOT_A_WORLD = (
|
|
16
|
+
"A world bundle is not itself a world, its members are: drop gateway-env.toml from the bundle, or push it "
|
|
17
|
+
"as its own world."
|
|
18
|
+
)
|
|
19
|
+
BUNDLE_PUSH_ACTIONS = ("tests",)
|
|
20
|
+
BUNDLE_RESERVED_TABLES = ("integrations",)
|
|
21
|
+
LINK_TRANSFORMS = (
|
|
22
|
+
"lower",
|
|
23
|
+
"upper",
|
|
24
|
+
"trim",
|
|
25
|
+
"collapse_ws",
|
|
26
|
+
"nfkc",
|
|
27
|
+
"digits",
|
|
28
|
+
"email_local_part",
|
|
29
|
+
"email_domain",
|
|
30
|
+
"sha1",
|
|
31
|
+
"sha256",
|
|
32
|
+
)
|
|
33
|
+
STRIP_PREFIX = "strip_prefix:"
|
|
34
|
+
|
|
35
|
+
_TABLES = ("bundle", "members", "actions", "identities", "references", *BUNDLE_RESERVED_TABLES)
|
|
36
|
+
_BUNDLE_KEYS = ("name", "test_state")
|
|
37
|
+
_MEMBER_ALIAS = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
|
|
38
|
+
_RESERVED_ALIASES = ("constructor", "prototype")
|
|
39
|
+
_MEMBER_PIN = re.compile(r"^(?:([^/@]+)/)?([^/@]+)@([^/@]+)$")
|
|
40
|
+
_MEMBER_REF = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$")
|
|
41
|
+
_WORLD_SLUG = re.compile(r"^(?!(?:migrate|runtime|templates)$)[a-z0-9][a-z0-9\-_]*$")
|
|
42
|
+
_MAX_SLUG_LENGTH = 128
|
|
43
|
+
_MAX_TEST_STATE_LENGTH = 120
|
|
44
|
+
_ENTITY = re.compile(r"[A-Za-z][A-Za-z0-9_]{0,63}")
|
|
45
|
+
_FIELD_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_-]*")
|
|
46
|
+
_FIELD_POINTER = re.compile(r"(?:/(?:[^/~]|~[01])+)+")
|
|
47
|
+
_IDENTITY_KEYS = ("created_in", "in", "key", "name")
|
|
48
|
+
_IDENTITY_MEMBER_KEYS = ("carry", "entity", "field", "transform")
|
|
49
|
+
_REFERENCE_KEYS = ("from", "to")
|
|
50
|
+
_REFERENCE_END_KEYS = ("entity", "field", "world")
|
|
51
|
+
_TRANSFORM_RULE = f"{', '.join(LINK_TRANSFORMS)} or strip_prefix:<prefix>"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _utf16_length(value: str) -> int:
|
|
55
|
+
return len(value.encode("utf-16-le", "surrogatepass")) // 2
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _world_slug(value: str) -> bool:
|
|
59
|
+
return len(value) <= _MAX_SLUG_LENGTH and _WORLD_SLUG.fullmatch(value) is not None
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def is_link_transform(name: str) -> bool:
|
|
63
|
+
return name in LINK_TRANSFORMS or (name.startswith(STRIP_PREFIX) and len(name) > len(STRIP_PREFIX))
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _transform_names(value: Any) -> list[Any] | None:
|
|
67
|
+
if value is None:
|
|
68
|
+
return []
|
|
69
|
+
if isinstance(value, str):
|
|
70
|
+
return [value]
|
|
71
|
+
return value if isinstance(value, list) else None
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _is_field(value: Any) -> bool:
|
|
75
|
+
return isinstance(value, str) and bool(_FIELD_NAME.fullmatch(value) or _FIELD_POINTER.fullmatch(value))
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@dataclass(frozen=True)
|
|
79
|
+
class BundleMember:
|
|
80
|
+
alias: str
|
|
81
|
+
slug: str
|
|
82
|
+
ref: str
|
|
83
|
+
|
|
84
|
+
def to_json(self) -> dict[str, str]:
|
|
85
|
+
return {"alias": self.alias, "slug": self.slug, "ref": self.ref}
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@dataclass(frozen=True)
|
|
89
|
+
class BundleIdentityMember:
|
|
90
|
+
alias: str
|
|
91
|
+
entity: str
|
|
92
|
+
field: str
|
|
93
|
+
transform: tuple[str, ...] = ()
|
|
94
|
+
carry: tuple[tuple[str, str], ...] = ()
|
|
95
|
+
|
|
96
|
+
def to_json(self) -> dict[str, Any]:
|
|
97
|
+
return {
|
|
98
|
+
"alias": self.alias,
|
|
99
|
+
"entity": self.entity,
|
|
100
|
+
"field": self.field,
|
|
101
|
+
"transform": list(self.transform),
|
|
102
|
+
"carry": dict(self.carry),
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
@dataclass(frozen=True)
|
|
107
|
+
class BundleIdentity:
|
|
108
|
+
name: str
|
|
109
|
+
key: str
|
|
110
|
+
created_in: str | None
|
|
111
|
+
members: tuple[BundleIdentityMember, ...]
|
|
112
|
+
|
|
113
|
+
def to_json(self) -> dict[str, Any]:
|
|
114
|
+
return {
|
|
115
|
+
"name": self.name,
|
|
116
|
+
"key": self.key,
|
|
117
|
+
"createdIn": self.created_in,
|
|
118
|
+
"in": [member.to_json() for member in self.members],
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@dataclass(frozen=True)
|
|
123
|
+
class BundleReferenceEnd:
|
|
124
|
+
world: str
|
|
125
|
+
entity: str
|
|
126
|
+
field: str
|
|
127
|
+
|
|
128
|
+
def to_json(self) -> dict[str, str]:
|
|
129
|
+
return {"world": self.world, "entity": self.entity, "field": self.field}
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
@dataclass(frozen=True)
|
|
133
|
+
class BundleReference:
|
|
134
|
+
source: BundleReferenceEnd
|
|
135
|
+
target: BundleReferenceEnd
|
|
136
|
+
|
|
137
|
+
def to_json(self) -> dict[str, Any]:
|
|
138
|
+
return {"from": self.source.to_json(), "to": self.target.to_json()}
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
@dataclass(frozen=True)
|
|
142
|
+
class BundleManifest:
|
|
143
|
+
name: str
|
|
144
|
+
test_state: str | None
|
|
145
|
+
members: tuple[BundleMember, ...]
|
|
146
|
+
on_push: tuple[str, ...] = ()
|
|
147
|
+
reserved: tuple[str, ...] = field(default_factory=tuple)
|
|
148
|
+
identities: tuple[BundleIdentity, ...] = ()
|
|
149
|
+
references: tuple[BundleReference, ...] = ()
|
|
150
|
+
|
|
151
|
+
@classmethod
|
|
152
|
+
def read(cls, text: str) -> BundleManifest | list[str]:
|
|
153
|
+
"""The manifest, or the list of issues that refuse it."""
|
|
154
|
+
try:
|
|
155
|
+
root = tomllib.loads(text.replace("\r\n", "\n"))
|
|
156
|
+
except tomllib.TOMLDecodeError as error:
|
|
157
|
+
return [f"gateway-bundle.toml is not valid TOML: {error}"]
|
|
158
|
+
return _Reader(root).read()
|
|
159
|
+
|
|
160
|
+
@staticmethod
|
|
161
|
+
def compose(
|
|
162
|
+
name: str,
|
|
163
|
+
members: list[BundleMember],
|
|
164
|
+
test_state: str | None = None,
|
|
165
|
+
on_push: tuple[str, ...] = (),
|
|
166
|
+
) -> str:
|
|
167
|
+
def quoted(value: object) -> str:
|
|
168
|
+
return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
|
|
169
|
+
|
|
170
|
+
lines = ["[bundle]", f"name = {quoted(name)}"]
|
|
171
|
+
if test_state:
|
|
172
|
+
lines.append(f"test_state = {quoted(test_state)}")
|
|
173
|
+
if on_push:
|
|
174
|
+
lines += ["", "[actions]", f"on_push = {quoted(list(on_push))}"]
|
|
175
|
+
for member in sorted(members, key=lambda m: m.alias):
|
|
176
|
+
lines += ["", f"[members.{member.alias}]", f"pin = {quoted(f'{member.slug}@{member.ref}')}"]
|
|
177
|
+
return "\n".join(lines) + "\n"
|
|
178
|
+
|
|
179
|
+
def to_json(self) -> dict[str, Any]:
|
|
180
|
+
return {
|
|
181
|
+
"name": self.name,
|
|
182
|
+
"testState": self.test_state,
|
|
183
|
+
"members": [member.to_json() for member in sorted(self.members, key=lambda m: m.alias)],
|
|
184
|
+
"onPush": list(self.on_push),
|
|
185
|
+
"identities": [identity.to_json() for identity in self.identities],
|
|
186
|
+
"references": [reference.to_json() for reference in self.references],
|
|
187
|
+
"reserved": list(self.reserved),
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
class _Reader:
|
|
192
|
+
def __init__(self, root: dict[str, Any]) -> None:
|
|
193
|
+
self.root = root
|
|
194
|
+
self.issues: list[str] = []
|
|
195
|
+
self.members: list[BundleMember] = []
|
|
196
|
+
|
|
197
|
+
def read(self) -> BundleManifest | list[str]:
|
|
198
|
+
self._unknown_tables()
|
|
199
|
+
bundle = self._bundle()
|
|
200
|
+
self._member_tables()
|
|
201
|
+
on_push = self._actions()
|
|
202
|
+
members = self.root.get("members")
|
|
203
|
+
relationships = _RelationshipReader(self.issues, set(members) if isinstance(members, dict) else set())
|
|
204
|
+
relationships.read_identities(self.root.get("identities"))
|
|
205
|
+
relationships.read_references(self.root.get("references"))
|
|
206
|
+
if self.issues or bundle is None:
|
|
207
|
+
return self.issues
|
|
208
|
+
return BundleManifest(
|
|
209
|
+
name=bundle[0],
|
|
210
|
+
test_state=bundle[1],
|
|
211
|
+
members=tuple(self.members),
|
|
212
|
+
on_push=tuple(on_push),
|
|
213
|
+
reserved=tuple(sorted(t for t in BUNDLE_RESERVED_TABLES if t in self.root)),
|
|
214
|
+
identities=tuple(relationships.identities),
|
|
215
|
+
references=tuple(relationships.references),
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
def _unknown_tables(self) -> None:
|
|
219
|
+
for key in sorted(self.root):
|
|
220
|
+
if key not in _TABLES:
|
|
221
|
+
self.issues.append(
|
|
222
|
+
f"gateway-bundle.toml has no table `{key}`; it takes bundle, members, actions, identities, "
|
|
223
|
+
"references and integrations."
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
def _bundle(self) -> tuple[str, str | None] | None:
|
|
227
|
+
bundle = self.root.get("bundle")
|
|
228
|
+
if not isinstance(bundle, dict):
|
|
229
|
+
self.issues.append("gateway-bundle.toml needs a [bundle] table with the bundle's name.")
|
|
230
|
+
return None
|
|
231
|
+
for key in sorted(bundle):
|
|
232
|
+
if key not in _BUNDLE_KEYS:
|
|
233
|
+
self.issues.append(f"[bundle] has no key `{key}`; it takes name and test_state.")
|
|
234
|
+
name = bundle.get("name")
|
|
235
|
+
named = isinstance(name, str) and _world_slug(name)
|
|
236
|
+
if not named:
|
|
237
|
+
self.issues.append("[bundle] name must be a world slug: lowercase letters, digits, '-' or '_'.")
|
|
238
|
+
test_state = bundle.get("test_state")
|
|
239
|
+
stated = test_state is None or (
|
|
240
|
+
isinstance(test_state, str) and 1 <= _utf16_length(test_state) <= _MAX_TEST_STATE_LENGTH
|
|
241
|
+
)
|
|
242
|
+
if not stated:
|
|
243
|
+
self.issues.append(
|
|
244
|
+
"[bundle] test_state names a world state of every member: a name of 1 to "
|
|
245
|
+
f"{_MAX_TEST_STATE_LENGTH} characters."
|
|
246
|
+
)
|
|
247
|
+
if not named or not stated:
|
|
248
|
+
return None
|
|
249
|
+
return str(name), test_state
|
|
250
|
+
|
|
251
|
+
def _member_tables(self) -> None:
|
|
252
|
+
members = self.root.get("members")
|
|
253
|
+
if not isinstance(members, dict):
|
|
254
|
+
self.issues.append("gateway-bundle.toml needs [members.<alias>] tables, one per member world.")
|
|
255
|
+
return
|
|
256
|
+
count = len(members)
|
|
257
|
+
if count < MIN_BUNDLE_MEMBERS:
|
|
258
|
+
self.issues.append(f"gateway-bundle.toml names {count} members; a bundle names at least one member.")
|
|
259
|
+
if count > MAX_BUNDLE_MEMBERS:
|
|
260
|
+
self.issues.append(
|
|
261
|
+
f"gateway-bundle.toml names {count} members; a bundle holds at most {MAX_BUNDLE_MEMBERS}."
|
|
262
|
+
)
|
|
263
|
+
pinned_by: dict[str, str] = {}
|
|
264
|
+
for alias in sorted(members):
|
|
265
|
+
self._member(alias, members[alias], pinned_by)
|
|
266
|
+
|
|
267
|
+
def _member(self, alias: str, table: Any, pinned_by: dict[str, str]) -> None:
|
|
268
|
+
if alias in _RESERVED_ALIASES:
|
|
269
|
+
self.issues.append(f"member alias `{alias}` is reserved; name the member another way.")
|
|
270
|
+
return
|
|
271
|
+
if not _MEMBER_ALIAS.fullmatch(alias):
|
|
272
|
+
self.issues.append(
|
|
273
|
+
f"member alias `{alias}` must be lowercase letters, digits or '_', start with a letter and be at "
|
|
274
|
+
"most 32 characters."
|
|
275
|
+
)
|
|
276
|
+
if not isinstance(table, dict):
|
|
277
|
+
self.issues.append(f"[members.{alias}] must be a table with a pin.")
|
|
278
|
+
return
|
|
279
|
+
for key in sorted(table):
|
|
280
|
+
if key != "pin":
|
|
281
|
+
self.issues.append(f"[members.{alias}] has no key `{key}`; it takes pin.")
|
|
282
|
+
member = self._pin(alias, table.get("pin"))
|
|
283
|
+
if member is None:
|
|
284
|
+
return
|
|
285
|
+
first = pinned_by.get(member.slug)
|
|
286
|
+
if first is not None:
|
|
287
|
+
self.issues.append(
|
|
288
|
+
f"[members.{alias}] pins {member.slug}, which [members.{first}] already pins; a world is a member once."
|
|
289
|
+
)
|
|
290
|
+
return
|
|
291
|
+
pinned_by[member.slug] = alias
|
|
292
|
+
self.members.append(member)
|
|
293
|
+
|
|
294
|
+
def _pin(self, alias: str, pin: Any) -> BundleMember | None:
|
|
295
|
+
parsed = _MEMBER_PIN.fullmatch(pin.strip(" \t")) if isinstance(pin, str) else None
|
|
296
|
+
if parsed is None or not _MEMBER_REF.fullmatch(parsed.group(3)):
|
|
297
|
+
self.issues.append(f"[members.{alias}] pin must be `<slug>@<ref>`.")
|
|
298
|
+
return None
|
|
299
|
+
project, slug, ref = parsed.groups()
|
|
300
|
+
if project is not None:
|
|
301
|
+
self.issues.append(
|
|
302
|
+
f"[members.{alias}] pin names a project; a member is a world of the bundle's own project, so drop "
|
|
303
|
+
f"the `{project}/` prefix."
|
|
304
|
+
)
|
|
305
|
+
return None
|
|
306
|
+
if not _world_slug(slug):
|
|
307
|
+
self.issues.append(
|
|
308
|
+
f"[members.{alias}] pin's slug `{slug}` must be a world slug: lowercase letters, digits, '-' or '_'."
|
|
309
|
+
)
|
|
310
|
+
return None
|
|
311
|
+
return BundleMember(alias, slug, ref)
|
|
312
|
+
|
|
313
|
+
def _actions(self) -> list[str]:
|
|
314
|
+
actions = self.root.get("actions")
|
|
315
|
+
if actions is None:
|
|
316
|
+
return []
|
|
317
|
+
if not isinstance(actions, dict):
|
|
318
|
+
self.issues.append("[actions] must be a table.")
|
|
319
|
+
return []
|
|
320
|
+
for key in sorted(actions):
|
|
321
|
+
if key != "on_push":
|
|
322
|
+
self.issues.append(f"[actions] has no key `{key}`; it takes on_push.")
|
|
323
|
+
on_push = actions.get("on_push", [])
|
|
324
|
+
known = isinstance(on_push, list) and all(
|
|
325
|
+
isinstance(action, str) and action in BUNDLE_PUSH_ACTIONS for action in on_push
|
|
326
|
+
)
|
|
327
|
+
if not known:
|
|
328
|
+
self.issues.append(f"[actions] on_push lists what runs on push: {', '.join(BUNDLE_PUSH_ACTIONS)}.")
|
|
329
|
+
return []
|
|
330
|
+
return list(on_push)
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
class _RelationshipReader:
|
|
334
|
+
def __init__(self, issues: list[str], members: set[str]) -> None:
|
|
335
|
+
self.issues = issues
|
|
336
|
+
self.members = members
|
|
337
|
+
self.identities: list[BundleIdentity] = []
|
|
338
|
+
self.references: list[BundleReference] = []
|
|
339
|
+
self._named: set[str] = set()
|
|
340
|
+
self._declared: dict[tuple[str, ...], int] = {}
|
|
341
|
+
|
|
342
|
+
def read_identities(self, value: Any) -> None:
|
|
343
|
+
if value is None:
|
|
344
|
+
return
|
|
345
|
+
if not isinstance(value, list):
|
|
346
|
+
self.issues.append("`identities` must be an array of tables, one [[identities]] per identity.")
|
|
347
|
+
return
|
|
348
|
+
for position, entry in enumerate(value, start=1):
|
|
349
|
+
self._identity(entry, position)
|
|
350
|
+
|
|
351
|
+
def read_references(self, value: Any) -> None:
|
|
352
|
+
if value is None:
|
|
353
|
+
return
|
|
354
|
+
if not isinstance(value, list):
|
|
355
|
+
self.issues.append("`references` must be an array of tables, one [[references]] per reference.")
|
|
356
|
+
return
|
|
357
|
+
for position, entry in enumerate(value, start=1):
|
|
358
|
+
self._reference(entry, position)
|
|
359
|
+
|
|
360
|
+
def _identity(self, entry: Any, position: int) -> None:
|
|
361
|
+
if not isinstance(entry, dict):
|
|
362
|
+
self.issues.append(f"identity #{position} must be a table with a name, a key and in.<alias> tables.")
|
|
363
|
+
return
|
|
364
|
+
before = len(self.issues)
|
|
365
|
+
name = entry.get("name")
|
|
366
|
+
named = isinstance(name, str) and _MEMBER_ALIAS.fullmatch(name) is not None
|
|
367
|
+
at = f"identity `{name}`" if named else f"identity #{position}"
|
|
368
|
+
self._unknown_keys(entry, _IDENTITY_KEYS, at, "name, key, created_in and in")
|
|
369
|
+
if not named:
|
|
370
|
+
self.issues.append(
|
|
371
|
+
f"{at} name must be lowercase letters, digits or '_', start with a letter and be at most 32 characters."
|
|
372
|
+
)
|
|
373
|
+
if named and name in self._named:
|
|
374
|
+
self.issues.append(f"{at} is declared twice; an identity's name is unique in the bundle.")
|
|
375
|
+
if named:
|
|
376
|
+
self._named.add(str(name))
|
|
377
|
+
key = entry.get("key")
|
|
378
|
+
if not isinstance(key, str) or not _FIELD_NAME.fullmatch(key):
|
|
379
|
+
self.issues.append(
|
|
380
|
+
f"{at} key must be a field name: letters, digits, '_' or '-', starting with a letter or '_'."
|
|
381
|
+
)
|
|
382
|
+
spans = self._spans(entry.get("in"), at)
|
|
383
|
+
self._carried_once(spans, at)
|
|
384
|
+
created_in = self._created_in(entry.get("created_in"), spans, at)
|
|
385
|
+
if len(self.issues) > before:
|
|
386
|
+
return
|
|
387
|
+
self.identities.append(BundleIdentity(str(name), str(key), created_in, tuple(spans)))
|
|
388
|
+
|
|
389
|
+
def _spans(self, value: Any, at: str) -> list[BundleIdentityMember]:
|
|
390
|
+
if not isinstance(value, dict) or not value:
|
|
391
|
+
self.issues.append(
|
|
392
|
+
f'{at} needs in.<alias> = {{ entity = "...", field = "..." }}, one per member world it spans.'
|
|
393
|
+
)
|
|
394
|
+
return []
|
|
395
|
+
return [self._span(alias, value[alias], f"{at} in.{alias}") for alias in sorted(value)]
|
|
396
|
+
|
|
397
|
+
def _span(self, alias: str, value: Any, where: str) -> BundleIdentityMember:
|
|
398
|
+
self._member(alias, where)
|
|
399
|
+
if not isinstance(value, dict):
|
|
400
|
+
self.issues.append(f'{where} must be a table: {{ entity = "...", field = "..." }}.')
|
|
401
|
+
return BundleIdentityMember(alias, "", "")
|
|
402
|
+
self._unknown_keys(value, _IDENTITY_MEMBER_KEYS, where, "entity, field, transform and carry")
|
|
403
|
+
entity, field_ = self._endpoint(value, where)
|
|
404
|
+
transform = tuple(self._transform(value.get("transform"), where))
|
|
405
|
+
return BundleIdentityMember(alias, entity, field_, transform, self._carry(value.get("carry"), field_, where))
|
|
406
|
+
|
|
407
|
+
def _carry(self, value: Any, key_field: Any, where: str) -> tuple[tuple[str, str], ...]:
|
|
408
|
+
if value is None:
|
|
409
|
+
return ()
|
|
410
|
+
if not isinstance(value, dict):
|
|
411
|
+
self.issues.append(
|
|
412
|
+
f'{where}.carry must be a table: {{ <name> = "<field>" }}, the fields this span carries to its '
|
|
413
|
+
"counterparts."
|
|
414
|
+
)
|
|
415
|
+
return ()
|
|
416
|
+
carried: list[tuple[str, str]] = []
|
|
417
|
+
held: set[Any] = set()
|
|
418
|
+
for name in sorted(value):
|
|
419
|
+
target = value[name]
|
|
420
|
+
if not _FIELD_NAME.fullmatch(name):
|
|
421
|
+
self.issues.append(
|
|
422
|
+
f"{where}.carry name `{name}` must be a field name: letters, digits, '_' or '-', starting with a "
|
|
423
|
+
"letter or '_'."
|
|
424
|
+
)
|
|
425
|
+
if not _is_field(target):
|
|
426
|
+
self.issues.append(
|
|
427
|
+
f"{where}.carry.{name} must be a field name or a JSON pointer such as /profile/name."
|
|
428
|
+
)
|
|
429
|
+
continue
|
|
430
|
+
if target == key_field:
|
|
431
|
+
self.issues.append(f"{where}.carry.{name} names the span's own field; the key is carried already.")
|
|
432
|
+
if target in held:
|
|
433
|
+
self.issues.append(f"{where}.carry names `{target}` twice; a field carries one value.")
|
|
434
|
+
held.add(target)
|
|
435
|
+
carried.append((name, target))
|
|
436
|
+
return tuple(carried)
|
|
437
|
+
|
|
438
|
+
def _carried_once(self, spans: list[BundleIdentityMember], at: str) -> None:
|
|
439
|
+
aliases: dict[str, list[str]] = {}
|
|
440
|
+
for span in spans:
|
|
441
|
+
for name, _ in span.carry:
|
|
442
|
+
aliases.setdefault(name, []).append(span.alias)
|
|
443
|
+
for name in sorted(aliases):
|
|
444
|
+
if len(aliases[name]) == 1:
|
|
445
|
+
self.issues.append(
|
|
446
|
+
f"{at} carries `{name}` only in.{aliases[name][0]}; name it in another span too, or drop it."
|
|
447
|
+
)
|
|
448
|
+
|
|
449
|
+
def _created_in(self, value: Any, spans: list[BundleIdentityMember], at: str) -> str | None:
|
|
450
|
+
if value is None:
|
|
451
|
+
return None
|
|
452
|
+
if isinstance(value, str) and any(span.alias == value for span in spans):
|
|
453
|
+
return value
|
|
454
|
+
self.issues.append(f"{at} created_in must name one of the identity's members (in.<alias>).")
|
|
455
|
+
return None
|
|
456
|
+
|
|
457
|
+
def _reference(self, entry: Any, position: int) -> None:
|
|
458
|
+
at = f"reference #{position}"
|
|
459
|
+
if not isinstance(entry, dict):
|
|
460
|
+
self.issues.append(f"{at} must be a table with from and to.")
|
|
461
|
+
return
|
|
462
|
+
before = len(self.issues)
|
|
463
|
+
self._unknown_keys(entry, _REFERENCE_KEYS, at, "from and to")
|
|
464
|
+
source = self._end(entry.get("from"), f"{at} from")
|
|
465
|
+
target = self._end(entry.get("to"), f"{at} to")
|
|
466
|
+
if len(self.issues) > before:
|
|
467
|
+
return
|
|
468
|
+
signature = (source.world, source.entity, source.field, target.world, target.entity, target.field)
|
|
469
|
+
first = self._declared.get(signature)
|
|
470
|
+
if first is not None:
|
|
471
|
+
self.issues.append(f"{at} repeats reference #{first}; a reference is declared once.")
|
|
472
|
+
return
|
|
473
|
+
self._declared[signature] = position
|
|
474
|
+
self.references.append(BundleReference(source, target))
|
|
475
|
+
|
|
476
|
+
def _end(self, value: Any, where: str) -> BundleReferenceEnd:
|
|
477
|
+
if not isinstance(value, dict):
|
|
478
|
+
self.issues.append(f'{where} must be a table: {{ world = "<alias>", entity = "...", field = "..." }}.')
|
|
479
|
+
return BundleReferenceEnd("", "", "")
|
|
480
|
+
self._unknown_keys(value, _REFERENCE_END_KEYS, where, "world, entity and field")
|
|
481
|
+
self._member(value.get("world"), f"{where}.world")
|
|
482
|
+
entity, field_ = self._endpoint(value, where)
|
|
483
|
+
return BundleReferenceEnd(str(value.get("world")), entity, field_)
|
|
484
|
+
|
|
485
|
+
def _member(self, alias: Any, where: str) -> None:
|
|
486
|
+
if isinstance(alias, str) and alias in self.members:
|
|
487
|
+
return
|
|
488
|
+
self.issues.append(f"{where} must name a member of this bundle.")
|
|
489
|
+
|
|
490
|
+
def _endpoint(self, table: dict[str, Any], where: str) -> tuple[Any, Any]:
|
|
491
|
+
entity = table.get("entity")
|
|
492
|
+
field_ = table.get("field")
|
|
493
|
+
if not isinstance(entity, str) or not _ENTITY.fullmatch(entity):
|
|
494
|
+
self.issues.append(
|
|
495
|
+
f"{where}.entity must be an entity name: letters, digits or '_', a letter first, at most 64 characters."
|
|
496
|
+
)
|
|
497
|
+
if not _is_field(field_):
|
|
498
|
+
self.issues.append(f"{where}.field must be a field name or a JSON pointer such as /owner/email.")
|
|
499
|
+
return entity, field_
|
|
500
|
+
|
|
501
|
+
def _transform(self, value: Any, where: str) -> list[str]:
|
|
502
|
+
names = _transform_names(value)
|
|
503
|
+
if names is None or not all(isinstance(name, str) for name in names):
|
|
504
|
+
self.issues.append(f"{where}.transform must be a transform name or a list of them.")
|
|
505
|
+
return []
|
|
506
|
+
for name in names:
|
|
507
|
+
if not is_link_transform(name):
|
|
508
|
+
self.issues.append(f"{where}.transform `{name}` is not one of {_TRANSFORM_RULE}.")
|
|
509
|
+
return names
|
|
510
|
+
|
|
511
|
+
def _unknown_keys(self, table: dict[str, Any], allowed: tuple[str, ...], at: str, takes: str) -> None:
|
|
512
|
+
for key in sorted(table):
|
|
513
|
+
if key not in allowed:
|
|
514
|
+
self.issues.append(f"{at} has no key `{key}`; it takes {takes}.")
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
__all__ = [
|
|
518
|
+
"BUNDLE_MANIFEST",
|
|
519
|
+
"BUNDLE_PUSH_ACTIONS",
|
|
520
|
+
"BUNDLE_RESERVED_TABLES",
|
|
521
|
+
"LINK_TRANSFORMS",
|
|
522
|
+
"MAX_BUNDLE_MEMBERS",
|
|
523
|
+
"MIN_BUNDLE_MEMBERS",
|
|
524
|
+
"BundleIdentity",
|
|
525
|
+
"BundleIdentityMember",
|
|
526
|
+
"BundleManifest",
|
|
527
|
+
"BundleMember",
|
|
528
|
+
"BundleReference",
|
|
529
|
+
"BundleReferenceEnd",
|
|
530
|
+
"is_link_transform",
|
|
531
|
+
]
|