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.
Files changed (108) hide show
  1. package/README.md +16 -9
  2. package/dist/RulesetRegistryLoaderFs.js +60 -6
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/channelIdentityPolicy.js +22 -0
  6. package/dist/cli.js +106 -69
  7. package/dist/engineConfig.js +291 -0
  8. package/dist/identity/IdentityService.js +90 -0
  9. package/dist/identity/crossPico.js +24 -8
  10. package/dist/identity/didoModule.js +80 -18
  11. package/dist/identity/establishSubscription.js +2 -2
  12. package/dist/identity/identityPortable.js +92 -0
  13. package/dist/identity/index.js +10 -1
  14. package/dist/identity/localPeerReconcile.js +65 -0
  15. package/dist/identity/peerDid4.js +175 -0
  16. package/dist/identity/peerDid4Create.js +90 -0
  17. package/dist/identity/portableExportPrepare.js +196 -0
  18. package/dist/identity/portableMove.js +87 -0
  19. package/dist/identity/skyIntro.js +6 -3
  20. package/dist/identity/skyProtocol.js +26 -1
  21. package/dist/identity/skyRotation.js +121 -0
  22. package/dist/identity/store.js +5 -1
  23. package/dist/identity/subscriptionEntSync.js +72 -0
  24. package/dist/identity/veramoDidComm.js +41 -2
  25. package/dist/identity/webvh.js +4 -2
  26. package/dist/identity/webvhRelocation.js +115 -0
  27. package/dist/index.js +84 -27
  28. package/dist/logging.js +156 -16
  29. package/dist/oauth/OAuthService.js +6 -2
  30. package/dist/policyConfigFromJson.js +112 -0
  31. package/dist/runMcp.js +27 -0
  32. package/dist/server.js +261 -24
  33. package/dist/stageKrl.js +26 -0
  34. package/dist/subtreeWrangler.js +180 -0
  35. package/dist/uiChannelPolicies.js +15 -0
  36. package/dist/xmluiRuntime.js +68 -0
  37. package/krl/io.picolabs.oauth.krl +41 -2
  38. package/krl/io.picolabs.pds.krl +131 -10
  39. package/krl/io.picolabs.pico-engine-ui.krl +217 -94
  40. package/krl/io.picolabs.portable_subtree.krl +97 -0
  41. package/krl/io.picolabs.subscription.krl +180 -72
  42. package/krl/io.picolabs.wrangler.krl +313 -57
  43. package/krl/io.picolabs.xmlui.krl +295 -0
  44. package/mcp/devResources.js +118 -0
  45. package/mcp/devTools.js +351 -0
  46. package/mcp/engineClient.js +133 -0
  47. package/mcp/meshHttp.js +137 -0
  48. package/mcp/meshTools.js +189 -0
  49. package/mcp/runStdio.js +34 -0
  50. package/mcp/schemaToZod.js +56 -0
  51. package/package.json +24 -9
  52. package/public/.DS_Store +0 -0
  53. package/public/docs/_sidebar.md +3 -1
  54. package/public/docs/llms-full.txt +630 -0
  55. package/public/docs/llms.txt +38 -0
  56. package/public/docs/openapi.yaml +78 -0
  57. package/public/docs/pico-engine.md +239 -4
  58. package/public/docs/pico-overview.md +117 -0
  59. package/public/docs/pico-views-xmlui.md +5 -0
  60. package/public/docs/pico-views.md +140 -0
  61. package/public/docs/pico.md +3 -1
  62. package/public/docs/rulesets/README.md +26 -0
  63. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  64. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  65. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  66. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  67. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  68. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  69. package/public/pico-engine-ui.css +1 -1
  70. package/public/pico-engine-ui.js +27 -23
  71. package/public/xmlui/0.12.7.js +419 -0
  72. package/public/xmlui/pico-view-boot.js +153 -0
  73. package/src/RulesetRegistryLoaderFs.ts +66 -7
  74. package/src/auth/cookies.ts +34 -0
  75. package/src/auth/index.ts +7 -0
  76. package/src/channelIdentityPolicy.ts +29 -0
  77. package/src/cli.ts +70 -37
  78. package/src/engineConfig.ts +363 -0
  79. package/src/identity/IdentityService.ts +189 -1
  80. package/src/identity/crossPico.ts +57 -8
  81. package/src/identity/didoModule.ts +140 -23
  82. package/src/identity/establishSubscription.ts +2 -2
  83. package/src/identity/identityPortable.ts +153 -0
  84. package/src/identity/index.ts +14 -0
  85. package/src/identity/localPeerReconcile.ts +97 -0
  86. package/src/identity/peerDid4.ts +197 -0
  87. package/src/identity/peerDid4Create.ts +121 -0
  88. package/src/identity/portableExportPrepare.ts +302 -0
  89. package/src/identity/portableMove.ts +193 -0
  90. package/src/identity/skyIntro.ts +11 -11
  91. package/src/identity/skyProtocol.ts +46 -0
  92. package/src/identity/skyRotation.ts +211 -0
  93. package/src/identity/store.ts +5 -1
  94. package/src/identity/subscriptionEntSync.ts +97 -0
  95. package/src/identity/veramoDidComm.ts +52 -2
  96. package/src/identity/webvh.ts +4 -4
  97. package/src/identity/webvhRelocation.ts +167 -0
  98. package/src/index.ts +123 -31
  99. package/src/logging.ts +173 -18
  100. package/src/oauth/OAuthService.ts +11 -3
  101. package/src/policyConfigFromJson.ts +131 -0
  102. package/src/runMcp.ts +30 -0
  103. package/src/server.ts +328 -27
  104. package/src/stageKrl.ts +26 -0
  105. package/src/subtreeWrangler.ts +278 -0
  106. package/src/uiChannelPolicies.ts +15 -0
  107. package/src/xmluiRuntime.ts +66 -0
  108. 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`.
@@ -1,3 +1,5 @@
1
1
  # Persistent Compute Objects
2
2
 
3
- TODO
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>`