@withgateway/sdk 0.2.6 → 0.2.9
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/README.md +24 -8
- package/dist/cli.js +15468 -11263
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +15233 -11028
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +291 -40
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +284 -37
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +203 -47
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +198 -42
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
- package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
- package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
- package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2149 -615
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2053 -566
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +268 -31
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +262 -28
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +19 -11
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +19 -11
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +886 -117
- package/dist/worlds/index.d.ts +886 -117
- package/dist/worlds/index.js +1770 -452
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1752 -434
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +14 -10
- package/runtime/gatewaysdk/environment/_toml.py +3 -10
- package/runtime/gatewaysdk/environment/_world.py +95 -28
- package/runtime/gatewaysdk/environment/runtime.py +10 -6
- package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/api.py +19 -23
- package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
- package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
- package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
- package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
- package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
- package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
- package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
- package/runtime/gatewaysdk/environment/schema/host.py +68 -115
- package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
- package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
- package/runtime/gatewaysdk/environment/schema/local.py +7 -10
- package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
- package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
- package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
- package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
- package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
- package/runtime/gatewaysdk/environment/schema/store.py +15 -6
- package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
- package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
- package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
- package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
- package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
- package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
- package/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/skills/connector-schema-authoring/SKILL.md +54 -4
- package/skills/connector-schema-authoring/connector-worlds.md +21 -7
- package/skills/connector-schema-authoring/world-schema.md +144 -83
- package/skills/hooks-getting-started/SKILL.md +27 -2
- package/skills/world-data-ingestion/ROWS.md +62 -0
- package/skills/world-data-ingestion/SKILL.md +91 -54
- package/skills/worlds-getting-started/SKILL.md +146 -146
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/skills/worlds-getting-started/references/openapi-import.md +90 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# A world from nothing: `sandbox open --new`
|
|
2
|
+
|
|
3
|
+
`gateway worlds sandbox open --new <slug> --from custom|<template>` (`bench sandbox` is the
|
|
4
|
+
same command; MCP `open_world_sandbox({ new, from })`) opens a hosted sandbox for a world that
|
|
5
|
+
does not exist yet in the key's project. Nothing is needed on the caller's disk — not a
|
|
6
|
+
checkout, not `schema init`.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
gateway worlds sandbox open --new acme-crm --from custom # or --from slack|github|…
|
|
10
|
+
gateway worlds sandbox exec <id> "gateway worlds schema entity add . crm_accounts --fields id:string,name:string --key id"
|
|
11
|
+
gateway worlds sandbox exec <id> "gateway worlds schema compile . && gateway worlds schema check ."
|
|
12
|
+
gateway worlds sandbox check <id> # the push gate the first commit will run
|
|
13
|
+
gateway worlds sandbox commit <id> -m "first cut" # creates the world: first READY version on main
|
|
14
|
+
gateway worlds sandbox close <id>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
What `open` does and does not do:
|
|
18
|
+
|
|
19
|
+
- The slug goes through the one world slug validator and must be free in the project. A taken
|
|
20
|
+
slug is a 409 `world_exists`; the sandbox never renames it (pick another slug).
|
|
21
|
+
- `--from custom` seeds the working tree with exactly what `gateway worlds schema init <slug>`
|
|
22
|
+
writes; `--from <template>` with a shipped template (`gateway worlds schema templates`,
|
|
23
|
+
`GET /api/public/worlds/templates`). An unknown template is a 400 that names the list.
|
|
24
|
+
- No world, container or version is created at open. `open`/`status` say so:
|
|
25
|
+
`containerId: null`, `baseVersionId: null`, `baseContentHash: null`, `branch: "main"`,
|
|
26
|
+
`pendingSlug: "<slug>"`.
|
|
27
|
+
- Paths stay under `/workspace/env`; the staged `gateway` CLI and `sqlite3` run on the tree.
|
|
28
|
+
|
|
29
|
+
The first `commit`:
|
|
30
|
+
|
|
31
|
+
- runs the same push gate as `check` (nothing is written to the versions tables when it fails);
|
|
32
|
+
- creates the world through the door `gateway worlds create --from <dir>` uses — slug, kind
|
|
33
|
+
detected from the tree (a retired kind is refused the same way), first READY version on
|
|
34
|
+
`main`, attributed to the key;
|
|
35
|
+
- flips the sandbox to a normal one in the same transaction: it now has a container, a base
|
|
36
|
+
version and a base hash, and every later `commit` behaves like today's (parent check, dedup,
|
|
37
|
+
no-change).
|
|
38
|
+
|
|
39
|
+
Two new-world sandboxes racing for one slug: exactly one first commit wins; the other gets a
|
|
40
|
+
409 `world_exists` and keeps its tree intact. To keep that work, open a new sandbox with another
|
|
41
|
+
slug (`sandbox open --new <other> --from custom`), copy the files across with `read`/`write`,
|
|
42
|
+
then `sandbox close <id> --force` the loser. A never-committed `--new` sandbox counts as
|
|
43
|
+
uncommitted (its base is empty), so a plain `close` exits 1; a closed sandbox cannot be reopened.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# From an OpenAPI spec: `schema init --from-openapi`
|
|
2
|
+
|
|
3
|
+
`gateway worlds schema init <dir> --from-openapi <source>` turns a Swagger 2.0 or OpenAPI 3.0.x /
|
|
4
|
+
3.1 document (JSON or YAML) into a world: `schema/world.json` (entities), `connector.toml` (the
|
|
5
|
+
served routes) and `schema/provenance.json` (where it came from). The importer is the Python
|
|
6
|
+
package's `OpenApiImport` → `OpenApiWorldPlan`; the plan is handed to the same scaffold writer
|
|
7
|
+
`schema init` always uses, so the tree it writes is a plain schema world you keep editing with
|
|
8
|
+
`schema entity add` and `connector route add`.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
gateway worlds schema init ./x --from-openapi petstore.yaml # local file: plan printed, tree written
|
|
12
|
+
gateway worlds schema init ./x --from-openapi drive:specs/petstore.json # a file on the project drive (read platform-side, never downloaded)
|
|
13
|
+
gateway worlds schema init ./x --from-openapi https://vendor.test/openapi.json # fetched from where the command runs
|
|
14
|
+
gateway worlds schema init ./x --from-openapi github.json --plan-only # print the plan, write nothing
|
|
15
|
+
gateway worlds schema init ./x --from-openapi github.json --include '/repos/{owner}/{repo}/issues*' --exclude reactions
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Sources
|
|
19
|
+
|
|
20
|
+
| `<source>` | Read by | Notes |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| a local path | the CLI process | must be a file under 64 MiB |
|
|
23
|
+
| `drive:<path>` | the platform, with your `GATEWAY_*` keys | the same reader as `worlds data import drive:…`; bytes stay in memory, nothing lands on disk |
|
|
24
|
+
| `http(s)://…` | the process running the command | the TS CLI fetches it like `files fetch`; the Python `gateway` fetches behind its private-address guard (loopback, RFC 1918, link-local and metadata addresses are refused, redirects re-checked). Other schemes (`file:`, `ftp:`) are refused. |
|
|
25
|
+
|
|
26
|
+
Inside a world sandbox (`run_gateway_cli`, `sandbox exec`) only a workspace path is accepted:
|
|
27
|
+
write the document into the workspace first (`sandbox write --from spec.yaml`), then import.
|
|
28
|
+
|
|
29
|
+
## What the plan says
|
|
30
|
+
|
|
31
|
+
`--from-openapi` always prints the plan first (JSON, one object):
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"status": "ok", "written": true,
|
|
36
|
+
"plan": {
|
|
37
|
+
"source": "petstore.yaml", "document": {"version": "openapi 3.0.3", "title": "Petstore", "sha256": "…"},
|
|
38
|
+
"connector": "petstore",
|
|
39
|
+
"entities": [{"name": "pets", "key": "id", "source": "Pet", "pointer": "/components/schemas/Pet"}],
|
|
40
|
+
"operations": [{"name": "list_pets", "method": "GET", "path": "/pets", "entity": "pets", "action": "read",
|
|
41
|
+
"params": ["limit", "status"], "filter": {"status": "status"}, "pointer": "/paths/~1pets/get"}],
|
|
42
|
+
"skipped": [{"method": "TRACE", "path": "/pets", "pointer": "/paths/~1pets/trace", "skipped_reason": "method TRACE is not one a connector serves"}],
|
|
43
|
+
"excluded": 0, "warnings": ["/paths/~1pets/post: operation name add_pet is taken; using add_pet_2"]
|
|
44
|
+
},
|
|
45
|
+
"domain": "petstore", "next": ["gateway worlds schema compile ./x # …", "…"]
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
With `--plan-only` the same object carries `"written": false` and no `domain`/`next`.
|
|
50
|
+
|
|
51
|
+
## Conversion rules (decided; the importer documents them in `schema/provenance.json`)
|
|
52
|
+
|
|
53
|
+
- **Entities.** Every object schema under `definitions` / `components.schemas` that some selected
|
|
54
|
+
operation returns and that has an id-like key (`id`, `<name>Id`, `<name>_id`, a `readOnly`
|
|
55
|
+
field the vendor marks `x-unique`/`x-primary-key`, else the first `required` string/integer field) becomes a `$defs` entry plus
|
|
56
|
+
`x-gateway.entities.<snake_plural>` with `primary_key` (snake_case, at most 64 characters —
|
|
57
|
+
a longer vendor name is truncated, the original kept in provenance). Keyless objects stay `$defs`,
|
|
58
|
+
referenced inline. `allOf` is merged; `oneOf`/`anyOf` become a union the world validator
|
|
59
|
+
accepts. Entity roots close (`additionalProperties: false`); the vendor's field names are kept
|
|
60
|
+
as spelled (so a rows file shaped like the vendor's response imports as it is); the vendor's
|
|
61
|
+
schema name stays the `$defs` key and `schema/provenance.json` maps every entity and operation
|
|
62
|
+
back to its source name and JSON pointer.
|
|
63
|
+
- **Routes.** Every path+method in `get|post|put|patch|delete` becomes an `[[operations]]` entry:
|
|
64
|
+
`name` = `operationId` snake_cased, at most 64 characters, deduped with `_2`, `_3` and a
|
|
65
|
+
warning; `entity` = the response schema's entity when it resolves to one (an array → a list
|
|
66
|
+
route, an object → `read|create|update|delete` by method); path parameters and declared query
|
|
67
|
+
parameters become `params`; a `{data: [...]}` wrapper becomes `results`; on a list route a
|
|
68
|
+
declared query parameter that names a top-level entity field becomes a `filter` (paging names
|
|
69
|
+
such as `page`, `limit`, `offset`, `cursor` never do). A path that repeats a placeholder
|
|
70
|
+
(`/a/{id}/{id}`) is skipped with its reason. An operation whose response is not an
|
|
71
|
+
entity (login, upload, HTML) stays a **passthrough** route with no entity — it is served, and
|
|
72
|
+
answers `501 {"error": "not_modelled"}` until you give it a handler.
|
|
73
|
+
- **Skipped, with a reason:** `HEAD`/`OPTIONS`/`TRACE`; a path argument that is not an
|
|
74
|
+
identifier; a second operation on the same method+path shape. **Refused, with a JSON pointer
|
|
75
|
+
into the document, nothing written:** no `paths`; an unknown or external `$ref`; an entity root
|
|
76
|
+
that is (transitively) cyclic — model the recursion as a relationship field (`parent_id`)
|
|
77
|
+
instead; a path parameter nothing declares (`--param <name>` on a hand-written route); a
|
|
78
|
+
document with no keyed schema at all.
|
|
79
|
+
- **Big documents.** `--include GLOB|TAG` / `--exclude GLOB|TAG` (repeatable) select operations
|
|
80
|
+
by path glob or tag before anything is resolved; only the schemas the selected operations reach
|
|
81
|
+
are converted, so the 9.9 MB GitHub document imports as an issues subset in seconds. A
|
|
82
|
+
document over 64 MiB is refused before it is read.
|
|
83
|
+
|
|
84
|
+
## After import
|
|
85
|
+
|
|
86
|
+
The printed `next` steps are the loop, in order: `schema compile`, `schema check`, `data import
|
|
87
|
+
<rows.json> --entity <first list entity>` (rows shaped like the vendor's response), `worlds serve`
|
|
88
|
+
then `worlds call http://127.0.0.1:<port> <list_route> --args '{}'`, and `sandbox commit` when the
|
|
89
|
+
tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
|
|
90
|
+
served world back against the spec.
|