pico-engine 1.6.4 → 1.9.0
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 +16 -9
- package/dist/RulesetRegistryLoaderFs.js +60 -6
- package/dist/auth/cookies.js +32 -0
- package/dist/auth/index.js +6 -1
- package/dist/channelIdentityPolicy.js +22 -0
- package/dist/cli.js +106 -69
- package/dist/engineConfig.js +291 -0
- package/dist/identity/IdentityService.js +90 -0
- package/dist/identity/crossPico.js +24 -8
- package/dist/identity/didoModule.js +80 -18
- package/dist/identity/establishSubscription.js +2 -2
- package/dist/identity/identityPortable.js +92 -0
- package/dist/identity/index.js +10 -1
- package/dist/identity/localPeerReconcile.js +65 -0
- package/dist/identity/peerDid4.js +175 -0
- package/dist/identity/peerDid4Create.js +90 -0
- package/dist/identity/portableExportPrepare.js +196 -0
- package/dist/identity/portableMove.js +87 -0
- package/dist/identity/skyIntro.js +6 -3
- package/dist/identity/skyProtocol.js +26 -1
- package/dist/identity/skyRotation.js +121 -0
- package/dist/identity/store.js +5 -1
- package/dist/identity/subscriptionEntSync.js +72 -0
- package/dist/identity/veramoDidComm.js +41 -2
- package/dist/identity/webvh.js +4 -2
- package/dist/identity/webvhRelocation.js +115 -0
- package/dist/index.js +84 -27
- package/dist/logging.js +156 -16
- package/dist/oauth/OAuthService.js +6 -2
- package/dist/policyConfigFromJson.js +112 -0
- package/dist/runMcp.js +27 -0
- package/dist/server.js +261 -24
- package/dist/stageKrl.js +26 -0
- package/dist/subtreeWrangler.js +180 -0
- package/dist/uiChannelPolicies.js +15 -0
- package/dist/xmluiRuntime.js +68 -0
- package/krl/io.picolabs.oauth.krl +41 -2
- package/krl/io.picolabs.pds.krl +131 -10
- package/krl/io.picolabs.pico-engine-ui.krl +217 -94
- package/krl/io.picolabs.portable_subtree.krl +97 -0
- package/krl/io.picolabs.subscription.krl +180 -72
- package/krl/io.picolabs.wrangler.krl +313 -57
- package/krl/io.picolabs.xmlui.krl +295 -0
- package/mcp/devResources.js +118 -0
- package/mcp/devTools.js +351 -0
- package/mcp/engineClient.js +133 -0
- package/mcp/meshHttp.js +137 -0
- package/mcp/meshTools.js +189 -0
- package/mcp/runStdio.js +34 -0
- package/mcp/schemaToZod.js +56 -0
- package/package.json +24 -9
- package/public/.DS_Store +0 -0
- package/public/docs/_sidebar.md +3 -1
- package/public/docs/llms-full.txt +630 -0
- package/public/docs/llms.txt +38 -0
- package/public/docs/openapi.yaml +78 -0
- package/public/docs/pico-engine.md +239 -4
- package/public/docs/pico-overview.md +117 -0
- package/public/docs/pico-views-xmlui.md +5 -0
- package/public/docs/pico-views.md +140 -0
- package/public/docs/pico.md +3 -1
- package/public/docs/rulesets/README.md +26 -0
- package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
- package/public/docs/rulesets/io.picolabs.pds.md +327 -0
- package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
- package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
- package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
- package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
- package/public/pico-engine-ui.css +1 -1
- package/public/pico-engine-ui.js +27 -23
- package/public/xmlui/0.12.7.js +419 -0
- package/public/xmlui/pico-view-boot.js +153 -0
- package/src/RulesetRegistryLoaderFs.ts +66 -7
- package/src/auth/cookies.ts +34 -0
- package/src/auth/index.ts +7 -0
- package/src/channelIdentityPolicy.ts +29 -0
- package/src/cli.ts +70 -37
- package/src/engineConfig.ts +363 -0
- package/src/identity/IdentityService.ts +189 -1
- package/src/identity/crossPico.ts +57 -8
- package/src/identity/didoModule.ts +140 -23
- package/src/identity/establishSubscription.ts +2 -2
- package/src/identity/identityPortable.ts +153 -0
- package/src/identity/index.ts +14 -0
- package/src/identity/localPeerReconcile.ts +97 -0
- package/src/identity/peerDid4.ts +197 -0
- package/src/identity/peerDid4Create.ts +121 -0
- package/src/identity/portableExportPrepare.ts +302 -0
- package/src/identity/portableMove.ts +193 -0
- package/src/identity/skyIntro.ts +11 -11
- package/src/identity/skyProtocol.ts +46 -0
- package/src/identity/skyRotation.ts +211 -0
- package/src/identity/store.ts +5 -1
- package/src/identity/subscriptionEntSync.ts +97 -0
- package/src/identity/veramoDidComm.ts +52 -2
- package/src/identity/webvh.ts +4 -4
- package/src/identity/webvhRelocation.ts +167 -0
- package/src/index.ts +123 -31
- package/src/logging.ts +173 -18
- package/src/oauth/OAuthService.ts +11 -3
- package/src/policyConfigFromJson.ts +131 -0
- package/src/runMcp.ts +30 -0
- package/src/server.ts +328 -27
- package/src/stageKrl.ts +26 -0
- package/src/subtreeWrangler.ts +278 -0
- package/src/uiChannelPolicies.ts +15 -0
- package/src/xmluiRuntime.ts +66 -0
- package/krl/io.picolabs.did-o.krl +0 -349
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Pico views
|
|
2
|
+
|
|
3
|
+
A **view** is a shared function that returns [XMLUI](https://xmlui.org) markup. Install the ruleset, open it on a channel that may call that function, and the engine serves the page.
|
|
4
|
+
|
|
5
|
+
The engine ships the XMLUI runtime (`/xmlui/0.12.7.js`) and the optional ruleset `io.picolabs.xmlui`. That ruleset builds the app shell, navigation, and the markup helpers. It is not installed on every pico. Install it from the engine:
|
|
6
|
+
|
|
7
|
+
`/krl/io.picolabs.xmlui.krl`
|
|
8
|
+
|
|
9
|
+
Channel policy applies to views the same way it applies to any other query. A channel that cannot call the function does not get that page. Live data still comes from `/sky/query` and `/sky/event` on that same channel.
|
|
10
|
+
|
|
11
|
+
Examples live in `demos/xmlui/` in the pico-engine repository. The design record is `docs/design/pico-views-xmlui.md`.
|
|
12
|
+
|
|
13
|
+
## Write a view
|
|
14
|
+
|
|
15
|
+
Tag the function with `@view` and return one `<Component>`:
|
|
16
|
+
|
|
17
|
+
```krl
|
|
18
|
+
ruleset com.example.hello {
|
|
19
|
+
meta {
|
|
20
|
+
name "Hello"
|
|
21
|
+
shares hello
|
|
22
|
+
}
|
|
23
|
+
global {
|
|
24
|
+
/**
|
|
25
|
+
* A first view
|
|
26
|
+
* @view "Hello"
|
|
27
|
+
*/
|
|
28
|
+
hello = function() {
|
|
29
|
+
<<<Component name="Hello">
|
|
30
|
+
<H1>Hello</H1>
|
|
31
|
+
<Text>This view is a shared function in #{meta:rid}.</Text>
|
|
32
|
+
</Component>
|
|
33
|
+
>>
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`@view "Title"` sets the navigation label. The shell turns the function name into the component tag by capitalizing the first letter (`hello` → `<Hello />`). The `<Component name>` in the markup has to be that same name.
|
|
40
|
+
|
|
41
|
+
Give the function a path when you want a specific URL:
|
|
42
|
+
|
|
43
|
+
```krl
|
|
44
|
+
@view "Settings" /settings
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
With one view and no path, the page is `/`. With several views and no path, each page is `/` plus the function name. A path that contains `:` is a detail page (`@view "Contact" /contact/:id`). It is left out of the navigation. The component reads `{$routeParams.id}`. Other views link to it with `<Link to="/contact/{$item.id}">`.
|
|
48
|
+
|
|
49
|
+
Do not name a view after a built-in XMLUI tag (`List`, `Table`, `Form`, `Text`, …). A function named `list` becomes `<List />`, which is the framework list, not your page. Name it `contactsPage` and, if you want the URL to be `/list`, set the path.
|
|
50
|
+
|
|
51
|
+
`#{}` runs in KRL while the page is generated. Use it for constants: `meta:rid`, labels, and the helpers below. Do not put entity variables or query results in `#{}`. Those values belong in a `DataSource`, which XMLUI renders as text. `krl check` warns when a `@view` function interpolates `ent:` and when the heredoc is not well-formed XML.
|
|
52
|
+
|
|
53
|
+
## Open it
|
|
54
|
+
|
|
55
|
+
| URL | What it serves |
|
|
56
|
+
|-----|----------------|
|
|
57
|
+
| `/ui/{eci}` | A list of rulesets on this channel that have a view the channel may call |
|
|
58
|
+
| `/ui/{eci}/{rid}/` | That ruleset's app. Routes are hash URLs under this path |
|
|
59
|
+
|
|
60
|
+
The shell (`index.html`), `Main.xmlui`, and `config.json` come from `io.picolabs.xmlui:file`. `components/<Name>.xmlui` is the view function itself, queried on the channel in the URL.
|
|
61
|
+
|
|
62
|
+
In the developer UI, a ruleset with at least one `@view` function has a **View** button on the Rulesets tab. Pick the channel, then open the app.
|
|
63
|
+
|
|
64
|
+
The channel must allow:
|
|
65
|
+
|
|
66
|
+
- `io.picolabs.xmlui` / `file`, or the shell does not load
|
|
67
|
+
- the view function, or that component is not found
|
|
68
|
+
- every query and event the page calls
|
|
69
|
+
|
|
70
|
+
A policy denial on these routes is HTTP 403. Anything else the route cannot serve is HTTP 404.
|
|
71
|
+
|
|
72
|
+
These `/ui/` files are the ruleset's markup plus the ECI and RID already in the URL. They are served without a bearer token. Pico data is not in them. When the engine requires a bearer on `/sky/*`, the shell signs in and sends that token as `appGlobals.auth` on each `DataSource` and `APICall`.
|
|
73
|
+
|
|
74
|
+
## Read and write
|
|
75
|
+
|
|
76
|
+
`use module io.picolabs.xmlui alias ui`. The helpers return markup, so they go in the heredoc with `#{}`.
|
|
77
|
+
|
|
78
|
+
| Call | Result |
|
|
79
|
+
|------|--------|
|
|
80
|
+
| `ui:query(id, name, opts)` | A `DataSource`. `opts.rid` defaults to this ruleset. `opts.args` is a map of query parameters (values may be XMLUI bindings such as `"{$routeParams.id}"`). `opts.select` sets `resultSelector`. |
|
|
81
|
+
| `ui:event(id, domain, type, opts)` | An `APICall` that posts the form body. `opts.refresh` is a list of `DataSource` ids to refetch. `opts.confirm` sets a confirmation message. |
|
|
82
|
+
| `ui:query_url(name, rid, eci)` | `/sky/query/…` for this channel, ruleset, and query. |
|
|
83
|
+
| `ui:event_url(domain, type, eci)` | `/sky/event/{eci}/xmlui/{domain}/{type}`. |
|
|
84
|
+
| `ui:app_url(tags, app_rid)` | `/ui/{eci}/{rid}/` for the newest channel with those tags, or `null`. |
|
|
85
|
+
| `ui:escape(s)` | Escape `&`, `<`, `>`, and `"` for text placed in markup. |
|
|
86
|
+
|
|
87
|
+
A guestbook view:
|
|
88
|
+
|
|
89
|
+
```krl
|
|
90
|
+
meta {
|
|
91
|
+
name "Guestbook"
|
|
92
|
+
use module io.picolabs.xmlui alias ui
|
|
93
|
+
shares entries, book
|
|
94
|
+
}
|
|
95
|
+
global {
|
|
96
|
+
/** Guestbook entries, newest first. @returns Array */
|
|
97
|
+
entries = function() {
|
|
98
|
+
ent:entries.defaultsTo([]).reverse()
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Sign and read the guestbook
|
|
103
|
+
* @view "Guestbook"
|
|
104
|
+
*/
|
|
105
|
+
book = function() {
|
|
106
|
+
<<<Component name="Book">
|
|
107
|
+
#{ui:query("entries", "entries")}
|
|
108
|
+
#{ui:event("sign", "guestbook", "signed", {"refresh": ["entries"]})}
|
|
109
|
+
<Form onSubmit="(toSave) => sign.execute(toSave)">
|
|
110
|
+
<FormItem bindTo="name" label="Name" />
|
|
111
|
+
<FormItem bindTo="message" label="Message" type="textarea" />
|
|
112
|
+
</Form>
|
|
113
|
+
<Table data="{entries}">
|
|
114
|
+
<Column bindTo="name" header="Name" />
|
|
115
|
+
<Column bindTo="message" header="Message" />
|
|
116
|
+
</Table>
|
|
117
|
+
</Component>
|
|
118
|
+
>>
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The matching rule selects `guestbook signed`. After it fires, `entries.refetch()` reloads the table. The full ruleset is `demos/xmlui/com.example.guestbook.krl`.
|
|
124
|
+
|
|
125
|
+
## App channel
|
|
126
|
+
|
|
127
|
+
`ui:create_app_channel(tags, domains, queries, app_rid)` creates a channel whose events are limited to `domains` (each name is `*`) and whose queries are `queries` on `app_rid`. When `queries` is `null`, every shared function of `app_rid` is allowed. The query policy always includes `io.picolabs.xmlui` / `file`.
|
|
128
|
+
|
|
129
|
+
```krl
|
|
130
|
+
rule create_app_channel {
|
|
131
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
132
|
+
ui:create_app_channel(["guestbook", "app"], ["guestbook"], null, meta:rid)
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`ui:rotate_app_channel(tags)` creates a new channel with the same tags and policy as the newest channel that already has those tags.
|
|
137
|
+
|
|
138
|
+
## What a view does not do
|
|
139
|
+
|
|
140
|
+
A view does not subscribe to changes made somewhere else. It loads when the page opens and refetches the `DataSource`s named in `opts.refresh` after its own event. Another pico's data is reached by a query on this pico that calls out, not by pointing a `DataSource` at the other pico. See `demos/xmlui/com.example.temperature_sensors_view.krl`.
|
package/public/docs/pico.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
1
|
# Persistent Compute Objects
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The philosophy and model doc is **[pico-overview.md](pico-overview.md)** (source: `docs/design/pico-overview.md` in the repo; copied into `public/docs/` by `npm run generate:llms`).
|
|
4
|
+
|
|
5
|
+
Legacy wiki copy: [Persistent Compute Objects on Confluence](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189992) — prefer the repo overview when they differ.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Bundled rulesets (generated docs)
|
|
2
|
+
|
|
3
|
+
Markdown here is copied from `tools/krl-schema/samples/` when you run **`npm run generate:llms`** at the repo root. Sources are the annotated KRL under `packages/pico-engine/krl/`. To regenerate samples from KRL: **`npm run check:krl-schema-samples`** (CI) or `node tools/krl-schema/cli.js -f markdown path/to/ruleset.krl`.
|
|
4
|
+
|
|
5
|
+
## OS layer (every pico)
|
|
6
|
+
|
|
7
|
+
Installed on the root pico and on each new child automatically.
|
|
8
|
+
|
|
9
|
+
| Ruleset | Doc |
|
|
10
|
+
|---------|-----|
|
|
11
|
+
| **io.picolabs.wrangler** | [wrangler](io.picolabs.wrangler.md) — **pico OS**; the supported API for mesh lifecycle (not raw `ctx:*`). If an operation is missing here, treat it as out-of-bounds or [file an engine issue](https://github.com/Picolab/pico-engine/issues). |
|
|
12
|
+
| **io.picolabs.pds** | [pds](io.picolabs.pds.md) — profile and shared namespaced data |
|
|
13
|
+
| **io.picolabs.subscription** | [subscription](io.picolabs.subscription.md) — relationships to other picos |
|
|
14
|
+
| **io.picolabs.pico-engine-ui** | [pico-engine-ui](io.picolabs.pico-engine-ui.md) — developer UI channel |
|
|
15
|
+
|
|
16
|
+
## Optional (install when needed)
|
|
17
|
+
|
|
18
|
+
Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler:install_ruleset_request` with the ruleset URL.
|
|
19
|
+
|
|
20
|
+
| Ruleset | Doc | Notes |
|
|
21
|
+
|---------|-----|--------|
|
|
22
|
+
| **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
|
|
23
|
+
| **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
|
|
24
|
+
| **io.picolabs.xmlui** | [Pico views](../pico-views.md) | Optional. A `@view` function is a page at `/ui/{eci}/{rid}/` |
|
|
25
|
+
|
|
26
|
+
Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# io.picolabs.oauth
|
|
2
|
+
|
|
3
|
+
Optional mesh-level OAuth. Install on the root pico to require Bearer tokens on external /sky/*
|
|
4
|
+
for this mesh (except channels tagged mesh-oauth-exempt or didcomm+ingress), and to hold
|
|
5
|
+
per-mesh OAuth configuration (apps, consent policy, defaults).
|
|
6
|
+
Webhook Client Credentials (per channel, oauth-webhook tag) and app Authorization Code grants
|
|
7
|
+
coexist here. Not installed by default.
|
|
8
|
+
|
|
9
|
+
use module io.picolabs.oauth alias oauth
|
|
10
|
+
|
|
11
|
+
*Version draft. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
|
|
12
|
+
|
|
13
|
+
**Queries:** [meshEnabled](#meshenabled--boolean) · [meshRequiresOAuth](#meshrequiresoautheci--boolean) · [channelStatus](#channelstatuseci--map) · [createChannelSecret](#createchannelsecreteci--map) · [revokeChannelSecret](#revokechannelsecreteci--map) · [revokeTokens](#revoketokenseci--map)
|
|
14
|
+
|
|
15
|
+
## Queries
|
|
16
|
+
|
|
17
|
+
### `meshEnabled()` → Boolean
|
|
18
|
+
|
|
19
|
+
True when this ruleset is installed on the pico. Its presence is the mesh's opt-in to OAuth.
|
|
20
|
+
|
|
21
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/meshEnabled`, or `<alias>:meshEnabled()` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
22
|
+
|
|
23
|
+
### `meshRequiresOAuth(eci)` → Boolean
|
|
24
|
+
|
|
25
|
+
True when external /sky/* requests on this channel need a Bearer token: the mesh root has io.picolabs.oauth installed and the channel is not tagged mesh-oauth-exempt or didcomm+ingress.
|
|
26
|
+
|
|
27
|
+
| Parameter | Type | Required | Default | Description |
|
|
28
|
+
|-----------|------|----------|---------|-------------|
|
|
29
|
+
| `eci` | String | yes | | channel to check |
|
|
30
|
+
|
|
31
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/meshRequiresOAuth?eci=…`, or `<alias>:meshRequiresOAuth(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
32
|
+
|
|
33
|
+
### `channelStatus(eci)` → Map
|
|
34
|
+
|
|
35
|
+
OAuth webhook status of a channel: whether it is eligible (tagged oauth-webhook), whether OAuth is enabled on it, and whether a client secret exists. Includes a reason when the channel is not eligible or not found.
|
|
36
|
+
|
|
37
|
+
| Parameter | Type | Required | Default | Description |
|
|
38
|
+
|-----------|------|----------|---------|-------------|
|
|
39
|
+
| `eci` | String | yes | | channel to inspect |
|
|
40
|
+
|
|
41
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/channelStatus?eci=…`, or `<alias>:channelStatus(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
42
|
+
|
|
43
|
+
### `createChannelSecret(eci)` → Map
|
|
44
|
+
|
|
45
|
+
Create (or replace) the Client Credentials secret for a webhook channel and return it. The secret is returned only here; the engine stores a hash, so save it now. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
|
|
46
|
+
|
|
47
|
+
| Parameter | Type | Required | Default | Description |
|
|
48
|
+
|-----------|------|----------|---------|-------------|
|
|
49
|
+
| `eci` | String | yes | | webhook channel (tagged oauth-webhook); also the client_id |
|
|
50
|
+
|
|
51
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/createChannelSecret?eci=…`, or `<alias>:createChannelSecret(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
52
|
+
|
|
53
|
+
### `revokeChannelSecret(eci)` → Map
|
|
54
|
+
|
|
55
|
+
Revoke a webhook channel's client secret so it can no longer obtain tokens. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
|
|
56
|
+
|
|
57
|
+
| Parameter | Type | Required | Default | Description |
|
|
58
|
+
|-----------|------|----------|---------|-------------|
|
|
59
|
+
| `eci` | String | yes | | webhook channel |
|
|
60
|
+
|
|
61
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/revokeChannelSecret?eci=…`, or `<alias>:revokeChannelSecret(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
62
|
+
|
|
63
|
+
### `revokeTokens(eci)` → Map
|
|
64
|
+
|
|
65
|
+
Revoke all access tokens issued for a channel, without removing its secret. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
|
|
66
|
+
|
|
67
|
+
| Parameter | Type | Required | Default | Description |
|
|
68
|
+
|-----------|------|----------|---------|-------------|
|
|
69
|
+
| `eci` | String | yes | | channel whose tokens to revoke |
|
|
70
|
+
|
|
71
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.oauth/revokeTokens?eci=…`, or `<alias>:revokeTokens(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# io.picolabs.pds
|
|
2
|
+
|
|
3
|
+
Pico Data Services (PDS), a common data base structure for all rulesets to use.
|
|
4
|
+
|
|
5
|
+
*Version draft. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
|
|
6
|
+
|
|
7
|
+
**Operations:** [pds:new_data_available](#pdsnew_data_available) · [pds:updated_data_available](#pdsupdated_data_available) · [pds:remove_old_data](#pdsremove_old_data) · [pds:remove_namespace](#pdsremove_namespace) · [pds:map_item](#pdsmap_item) · [pds:updated_profile](#pdsupdated_profile) · [pds:add_settings](#pdsadd_settings)
|
|
8
|
+
**Queries:** [items](#itemsnamespace-key--map) · [get_keys](#get_keysnamespace--array) · [profile](#profilekey--map) · [settings](#settingsrid-key-detail--map) · [get_config_value](#get_config_valuesetkey--any) · [get_setting_data_value](#get_setting_data_valuesetrid-setkey--any) · [config_value](#config_valuesetkey--any) · [settings_names](#settings_names--array) · [getChannelEci](#getchanneleci--string)
|
|
9
|
+
|
|
10
|
+
## Operations
|
|
11
|
+
|
|
12
|
+
Events you can send to a pico with this ruleset installed. Whether an operation acts, and what it emits, depends on its condition and the pico's state when the event arrives.
|
|
13
|
+
|
|
14
|
+
### `pds:new_data_available`
|
|
15
|
+
|
|
16
|
+
Store one value in the general data under namespace and key, replacing any existing value. Raises pds:data_added.
|
|
17
|
+
|
|
18
|
+
**Send:** `pds:new_data_available`
|
|
19
|
+
**Rule:** `add_item`
|
|
20
|
+
|
|
21
|
+
| Attribute | Type | Required | Description |
|
|
22
|
+
|-----------|------|----------|-------------|
|
|
23
|
+
| `namespace` | String | yes | namespace, e.g. your app's name |
|
|
24
|
+
| `key` | String | yes | |
|
|
25
|
+
| `value` | Any | yes | value to store |
|
|
26
|
+
|
|
27
|
+
**Examples:**
|
|
28
|
+
|
|
29
|
+
- **store a value:** `{"namespace":"<app>","key":"<key>","value":"<value>"}`
|
|
30
|
+
|
|
31
|
+
**Acts when:** always, once selected
|
|
32
|
+
|
|
33
|
+
**May emit** (possible, not guaranteed):
|
|
34
|
+
|
|
35
|
+
- raises `pds:data_added` on this pico — always
|
|
36
|
+
|
|
37
|
+
<details><summary>Select expression</summary>
|
|
38
|
+
|
|
39
|
+
```krl
|
|
40
|
+
select when pds new_data_available
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
</details>
|
|
44
|
+
|
|
45
|
+
### `pds:updated_data_available`
|
|
46
|
+
|
|
47
|
+
Merge fields into a stored map: each entry of value is written under namespace / key / field, leaving other fields alone. Raises pds:data_updated once per field.
|
|
48
|
+
|
|
49
|
+
**Send:** `pds:updated_data_available`
|
|
50
|
+
**Rule:** `update_item`
|
|
51
|
+
|
|
52
|
+
| Attribute | Type | Required | Description |
|
|
53
|
+
|-----------|------|----------|-------------|
|
|
54
|
+
| `namespace` | String | yes | |
|
|
55
|
+
| `key` | String | yes | |
|
|
56
|
+
| `value` | Map | yes | fields to set on the stored map |
|
|
57
|
+
|
|
58
|
+
**Examples:**
|
|
59
|
+
|
|
60
|
+
- **set fields:** `{"namespace":"<app>","key":"<key>","value":{"<field>":"<value>"}}`
|
|
61
|
+
|
|
62
|
+
**Acts when:** always, once selected
|
|
63
|
+
|
|
64
|
+
**May emit** (possible, not guaranteed):
|
|
65
|
+
|
|
66
|
+
- raises `pds:data_updated` on this pico — always
|
|
67
|
+
|
|
68
|
+
<details><summary>Select expression</summary>
|
|
69
|
+
|
|
70
|
+
```krl
|
|
71
|
+
select when pds updated_data_available
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
</details>
|
|
75
|
+
|
|
76
|
+
### `pds:remove_old_data`
|
|
77
|
+
|
|
78
|
+
Delete one key from a namespace of the general data. Raises pds:data_deleted.
|
|
79
|
+
|
|
80
|
+
**Send:** `pds:remove_old_data`
|
|
81
|
+
**Rule:** `remove_item`
|
|
82
|
+
|
|
83
|
+
| Attribute | Type | Required | Description |
|
|
84
|
+
|-----------|------|----------|-------------|
|
|
85
|
+
| `namespace` | String | yes | |
|
|
86
|
+
| `key` | String | yes | |
|
|
87
|
+
|
|
88
|
+
**Acts when:** always, once selected
|
|
89
|
+
|
|
90
|
+
**May emit** (possible, not guaranteed):
|
|
91
|
+
|
|
92
|
+
- raises `pds:data_deleted` on this pico — always
|
|
93
|
+
|
|
94
|
+
<details><summary>Select expression</summary>
|
|
95
|
+
|
|
96
|
+
```krl
|
|
97
|
+
select when pds remove_old_data
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
</details>
|
|
101
|
+
|
|
102
|
+
### `pds:remove_namespace`
|
|
103
|
+
|
|
104
|
+
Delete a whole namespace of the general data. Raises pds:namespace_deleted.
|
|
105
|
+
|
|
106
|
+
**Send:** `pds:remove_namespace`
|
|
107
|
+
**Rule:** `remove_namespace`
|
|
108
|
+
|
|
109
|
+
| Attribute | Type | Required | Description |
|
|
110
|
+
|-----------|------|----------|-------------|
|
|
111
|
+
| `namespace` | String | yes | |
|
|
112
|
+
|
|
113
|
+
**Acts when:** always, once selected
|
|
114
|
+
|
|
115
|
+
**May emit** (possible, not guaranteed):
|
|
116
|
+
|
|
117
|
+
- raises `pds:namespace_deleted` on this pico — always
|
|
118
|
+
|
|
119
|
+
<details><summary>Select expression</summary>
|
|
120
|
+
|
|
121
|
+
```krl
|
|
122
|
+
select when pds remove_namespace
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
</details>
|
|
126
|
+
|
|
127
|
+
### `pds:map_item`
|
|
128
|
+
|
|
129
|
+
Replace an entire namespace of the general data with a map. Raises pds:new_map_added.
|
|
130
|
+
|
|
131
|
+
**Send:** `pds:map_item`
|
|
132
|
+
**Rule:** `itemed_mapped`
|
|
133
|
+
|
|
134
|
+
| Attribute | Type | Required | Description |
|
|
135
|
+
|-----------|------|----------|-------------|
|
|
136
|
+
| `namespace` | String | yes | |
|
|
137
|
+
| `mapvalues` | String | yes | the new namespace contents, as a JSON-encoded map |
|
|
138
|
+
|
|
139
|
+
**Examples:**
|
|
140
|
+
|
|
141
|
+
- **replace namespace:** `{"namespace":"<app>","mapvalues":"{\"<key>\": \"<value>\"}"}`
|
|
142
|
+
|
|
143
|
+
**Acts when:** always, once selected
|
|
144
|
+
|
|
145
|
+
**May emit** (possible, not guaranteed):
|
|
146
|
+
|
|
147
|
+
- raises `pds:new_map_added` on this pico — always
|
|
148
|
+
|
|
149
|
+
<details><summary>Select expression</summary>
|
|
150
|
+
|
|
151
|
+
```krl
|
|
152
|
+
select when pds map_item
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
</details>
|
|
156
|
+
|
|
157
|
+
### `pds:updated_profile`
|
|
158
|
+
|
|
159
|
+
Update this pico's profile. Send only the fields to change; fields not sent keep their current values. _created is set on the first update and _modified on every update. Raises pds:profile_updated with _status "success", or "failure" when no fields were sent.
|
|
160
|
+
|
|
161
|
+
**Send:** `pds:updated_profile`
|
|
162
|
+
**Rule:** `update_profile`
|
|
163
|
+
|
|
164
|
+
| Attribute | Type | Required | Description |
|
|
165
|
+
|-----------|------|----------|-------------|
|
|
166
|
+
| `name` | String | no | display name |
|
|
167
|
+
| `description` | String | no | |
|
|
168
|
+
| `photo` | String | no | image URL or data: URI |
|
|
169
|
+
| `email` | String | no | |
|
|
170
|
+
| `phone` | String | no | |
|
|
171
|
+
|
|
172
|
+
**Examples:**
|
|
173
|
+
|
|
174
|
+
- **rename:** `{"name":"<name>"}`
|
|
175
|
+
- **contact info:** `{"email":"<email>","phone":"<phone>"}`
|
|
176
|
+
|
|
177
|
+
**Acts when:** `newly_constructed_profile != "nothing to update"`
|
|
178
|
+
|
|
179
|
+
**May emit** (possible, not guaranteed):
|
|
180
|
+
|
|
181
|
+
- raises `pds:profile_updated` on this pico — when it acts
|
|
182
|
+
- raises `pds:profile_updated` on this pico — when it doesn't act
|
|
183
|
+
|
|
184
|
+
<details><summary>Select expression</summary>
|
|
185
|
+
|
|
186
|
+
```krl
|
|
187
|
+
select when pds updated_profile
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
</details>
|
|
191
|
+
|
|
192
|
+
### `pds:add_settings`
|
|
193
|
+
|
|
194
|
+
Create or update a ruleset's settings record, and optionally set one data value in it. Raises pds:settings_added.
|
|
195
|
+
|
|
196
|
+
**Send:** `pds:add_settings`
|
|
197
|
+
**Rule:** `settings_added`
|
|
198
|
+
|
|
199
|
+
| Attribute | Type | Required | Description |
|
|
200
|
+
|-----------|------|----------|-------------|
|
|
201
|
+
| `keyed_rid` | String | yes | ruleset id the settings belong to |
|
|
202
|
+
| `name` | String | yes | display name for the settings |
|
|
203
|
+
| `schema` | Array | no | settings schema, stored as given |
|
|
204
|
+
| `data_key` | String | no | data key to set |
|
|
205
|
+
| `value` | Any | no | value for data_key |
|
|
206
|
+
|
|
207
|
+
**Examples:**
|
|
208
|
+
|
|
209
|
+
- **register settings:** `{"keyed_rid":"<rid>","name":"<display name>"}`
|
|
210
|
+
- **set one value:** `{"keyed_rid":"<rid>","name":"<display name>","data_key":"<key>","value":"<value>"}`
|
|
211
|
+
|
|
212
|
+
**Acts when:** always, once selected
|
|
213
|
+
|
|
214
|
+
**May emit** (possible, not guaranteed):
|
|
215
|
+
|
|
216
|
+
- raises `pds:settings_added` on this pico — always
|
|
217
|
+
|
|
218
|
+
<details><summary>Select expression</summary>
|
|
219
|
+
|
|
220
|
+
```krl
|
|
221
|
+
select when pds add_settings
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
</details>
|
|
225
|
+
|
|
226
|
+
## Queries
|
|
227
|
+
|
|
228
|
+
### `items(namespace?, key?)` → Map
|
|
229
|
+
|
|
230
|
+
Read general (namespaced) data. With no namespace, returns all of it; with a namespace, that namespace's map; with both, one value. status is "failed" when no namespace is given (the data is still returned).
|
|
231
|
+
|
|
232
|
+
| Parameter | Type | Required | Default | Description |
|
|
233
|
+
|-----------|------|----------|---------|-------------|
|
|
234
|
+
| `namespace` | String | no | | namespace to read; omit for everything |
|
|
235
|
+
| `key` | String | no | | key within the namespace; omit for the whole namespace |
|
|
236
|
+
|
|
237
|
+
**Examples:**
|
|
238
|
+
|
|
239
|
+
- **one namespace:** `{"namespace":"<app>"}`
|
|
240
|
+
- **one value:** `{"namespace":"<app>","key":"<key>"}`
|
|
241
|
+
|
|
242
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/items?namespace=…&key=…`, or `<alias>:items(namespace?, key?)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
243
|
+
|
|
244
|
+
### `get_keys(namespace)` → Array
|
|
245
|
+
|
|
246
|
+
Keys stored in one namespace of the general data.
|
|
247
|
+
|
|
248
|
+
| Parameter | Type | Required | Default | Description |
|
|
249
|
+
|-----------|------|----------|---------|-------------|
|
|
250
|
+
| `namespace` | String | yes | | |
|
|
251
|
+
|
|
252
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_keys?namespace=…`, or `<alias>:get_keys(namespace)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
253
|
+
|
|
254
|
+
### `profile(key?)` → Map
|
|
255
|
+
|
|
256
|
+
This pico's profile: name, description, photo, email, phone, and the _created / _modified timestamps. With a key, just that field.
|
|
257
|
+
|
|
258
|
+
| Parameter | Type | Required | Default | Description |
|
|
259
|
+
|-----------|------|----------|---------|-------------|
|
|
260
|
+
| `key` | String | no | | profile field to read; omit for the whole profile |
|
|
261
|
+
|
|
262
|
+
**Examples:**
|
|
263
|
+
|
|
264
|
+
- **whole profile:** `{}`
|
|
265
|
+
- **name only:** `{"key":"name"}`
|
|
266
|
+
|
|
267
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/profile?key=…`, or `<alias>:profile(key?)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
268
|
+
|
|
269
|
+
### `settings(Rid?, Key?, detail?)` → Map
|
|
270
|
+
|
|
271
|
+
Read per-ruleset settings. No arguments: all settings. Rid: that ruleset's settings record ({ name, rid, data, schema }). Rid and Key: one field of the record. Rid, Key, and detail: the value of data key `detail` (Key is ignored).
|
|
272
|
+
|
|
273
|
+
| Parameter | Type | Required | Default | Description |
|
|
274
|
+
|-----------|------|----------|---------|-------------|
|
|
275
|
+
| `Rid` | String | no | | ruleset id whose settings to read |
|
|
276
|
+
| `Key` | String | no | | field of the settings record (name, rid, data, schema) |
|
|
277
|
+
| `detail` | String | no | | key within the record's data map |
|
|
278
|
+
|
|
279
|
+
**Examples:**
|
|
280
|
+
|
|
281
|
+
- **one ruleset:** `{"Rid":"<rid>"}`
|
|
282
|
+
- **one data value:** `{"Rid":"<rid>","Key":"data","detail":"<key>"}`
|
|
283
|
+
|
|
284
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/settings?Rid=…&Key=…&detail=…`, or `<alias>:settings(Rid?, Key?, detail?)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
285
|
+
|
|
286
|
+
### `get_config_value(setKey)` → Any
|
|
287
|
+
|
|
288
|
+
Same as config_value: a value from the calling ruleset's own settings data, for use as a module function.
|
|
289
|
+
|
|
290
|
+
| Parameter | Type | Required | Default | Description |
|
|
291
|
+
|-----------|------|----------|---------|-------------|
|
|
292
|
+
| `setKey` | String | yes | | data key |
|
|
293
|
+
|
|
294
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_config_value?setKey=…`, or `<alias>:get_config_value(setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
295
|
+
|
|
296
|
+
### `get_setting_data_value(setRID, setKey)` → Any
|
|
297
|
+
|
|
298
|
+
One configuration value from a ruleset's settings data.
|
|
299
|
+
|
|
300
|
+
| Parameter | Type | Required | Default | Description |
|
|
301
|
+
|-----------|------|----------|---------|-------------|
|
|
302
|
+
| `setRID` | String | yes | | ruleset id |
|
|
303
|
+
| `setKey` | String | yes | | data key |
|
|
304
|
+
|
|
305
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_setting_data_value?setRID=…&setKey=…`, or `<alias>:get_setting_data_value(setRID, setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
306
|
+
|
|
307
|
+
### `config_value(setKey)` → Any
|
|
308
|
+
|
|
309
|
+
One configuration value from the calling ruleset's own settings data. Meant to be used as a module function (use module io.picolabs.pds): the ruleset is the caller's, from meta:callingRID().
|
|
310
|
+
|
|
311
|
+
| Parameter | Type | Required | Default | Description |
|
|
312
|
+
|-----------|------|----------|---------|-------------|
|
|
313
|
+
| `setKey` | String | yes | | data key |
|
|
314
|
+
|
|
315
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/config_value?setKey=…`, or `<alias>:config_value(setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
316
|
+
|
|
317
|
+
### `settings_names()` → Array
|
|
318
|
+
|
|
319
|
+
Rulesets that have stored settings here, with their display names.
|
|
320
|
+
|
|
321
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/settings_names`, or `<alias>:settings_names()` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
322
|
+
|
|
323
|
+
### `getChannelEci()` → String
|
|
324
|
+
|
|
325
|
+
The ECI of this pico's pds channel, which allows all pds events and queries. Created when this ruleset is installed.
|
|
326
|
+
|
|
327
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pds/getChannelEci`, or `<alias>:getChannelEci()` from KRL with `use module io.picolabs.pds alias <alias>`
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# io.picolabs.pico-engine-ui
|
|
2
|
+
|
|
3
|
+
This is the only ruleset the pico-engine-ui.js needs to operate
|
|
4
|
+
|
|
5
|
+
*Version 0.0.0. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
|
|
6
|
+
|
|
7
|
+
**Queries:** [box](#box--map) · [uiECI](#uieci--string) · [pico](#pico--map) · [logs](#logs--array) · [testingECI](#testingeci--string) · [testingHistory](#testinghistoryrid--map) · [testingSaved](#testingsavedrid--map) · [name](#name--string)
|
|
8
|
+
|
|
9
|
+
## Queries
|
|
10
|
+
|
|
11
|
+
### `box()` → Map
|
|
12
|
+
|
|
13
|
+
How the developer UI draws this pico: name, color, position, size, and the UI channels of its parent and children.
|
|
14
|
+
|
|
15
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/box`, or `<alias>:box()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
16
|
+
|
|
17
|
+
### `uiECI()` → String
|
|
18
|
+
|
|
19
|
+
The ECI of this pico's UI channel (tagged engine,ui), used by the developer UI to send engine_ui events and queries to this pico.
|
|
20
|
+
|
|
21
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/uiECI`, or `<alias>:uiECI()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
22
|
+
|
|
23
|
+
### `pico()` → Map
|
|
24
|
+
|
|
25
|
+
This pico's channels (with their policies) and installed rulesets, plus the UI channels of its parent and children. A quick way to see what a pico is.
|
|
26
|
+
|
|
27
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/pico`, or `<alias>:pico()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
28
|
+
|
|
29
|
+
### `logs()` → Array
|
|
30
|
+
|
|
31
|
+
Recent activity on this pico, grouped by transaction, newest first: each incoming event or query with the rules it selected, klog output, and errors. The developer UI's own queries are left out.
|
|
32
|
+
|
|
33
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/logs`, or `<alias>:logs()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
34
|
+
|
|
35
|
+
### `testingECI()` → String
|
|
36
|
+
|
|
37
|
+
The channel the developer UI's Testing tab last selected for sending events and queries to this pico, or null.
|
|
38
|
+
|
|
39
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingECI`, or `<alias>:testingECI()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
40
|
+
|
|
41
|
+
### `testingHistory(rid?)` → Map
|
|
42
|
+
|
|
43
|
+
Recent Testing-tab sends for this pico, keyed by ruleset rid (newest first).
|
|
44
|
+
|
|
45
|
+
| Parameter | Type | Required | Default | Description |
|
|
46
|
+
|-----------|------|----------|---------|-------------|
|
|
47
|
+
| `rid` | String | no | | optional ruleset id; omit for the full map rid → entries |
|
|
48
|
+
|
|
49
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingHistory?rid=…`, or `<alias>:testingHistory(rid?)` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
50
|
+
|
|
51
|
+
### `testingSaved(rid?)` → Map
|
|
52
|
+
|
|
53
|
+
Named Testing-tab requests kept on this pico, keyed by ruleset rid.
|
|
54
|
+
|
|
55
|
+
| Parameter | Type | Required | Default | Description |
|
|
56
|
+
|-----------|------|----------|---------|-------------|
|
|
57
|
+
| `rid` | String | no | | optional ruleset id; omit for the full map rid → entries |
|
|
58
|
+
|
|
59
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingSaved?rid=…`, or `<alias>:testingSaved(rid?)` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|
|
60
|
+
|
|
61
|
+
### `name()` → String
|
|
62
|
+
|
|
63
|
+
This pico's display name in the developer UI ("Pico" if never set).
|
|
64
|
+
|
|
65
|
+
**Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/name`, or `<alias>:name()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
|