pico-engine 1.9.4 → 1.10.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 (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,109 @@
1
+ /**
2
+ * KBlog posting: layered on the other KBlog rulesets so that only authors can
3
+ * post. It checks each submitted post and raises kblog:new_article_available
4
+ * for the data ruleset. It provides the PostForm component the Post page shows.
5
+ *
6
+ * On install it creates the author channel: every KBlog page, including Post,
7
+ * and exactly two events, kblog:post_submitted and kblog:clear_requested. The
8
+ * channel does not allow kblog:new_article_available, so an author cannot skip
9
+ * the check in handle_submit.
10
+ */
11
+ ruleset com.example.kblog.posting {
12
+ meta {
13
+ name "KBlog posting"
14
+ description "Lets authors post to KBlog, on a channel only they get."
15
+ author "PICOLABS"
16
+
17
+ use module io.picolabs.wrangler alias wrangler
18
+ use module io.picolabs.xmlui alias ui
19
+
20
+ shares postForm
21
+ }
22
+
23
+ global {
24
+ kblog_rid = "com.example.kblog"
25
+ xmlui_rid = "io.picolabs.xmlui"
26
+ author_tags = ["kblog", "author"]
27
+ kblog_queries = ["articles", "article", "homePage", "articlePage", "contactPage", "postPage"]
28
+
29
+ componentsOf = function(rid) {
30
+ wrangler:rulesetSchema(rid){"queries"}.defaultsTo([])
31
+ .filter(function(q) { not q{"component"}.isnull() })
32
+ .map(function(q) { q{"name"} })
33
+ }
34
+
35
+ authorQueryPolicy = function() {
36
+ kblog = kblog_queries.append(componentsOf(kblog_rid))
37
+ .map(function(name) { {"rid": kblog_rid, "name": name} })
38
+ xmlui = componentsOf(xmlui_rid).append(["file"])
39
+ .map(function(name) { {"rid": xmlui_rid, "name": name} })
40
+ policy = {"allow": kblog.append(xmlui).append([{"rid": meta:rid, "name": "postForm"}]), "deny": []}
41
+ policy
42
+ }
43
+
44
+ /**
45
+ * The post form, and the path the last post took through the rulesets.
46
+ * @component
47
+ */
48
+ postForm = function() {
49
+ submit_url = ui:event_url("kblog", "post_submitted")
50
+ clear_url = ui:event_url("kblog", "clear_requested")
51
+ <<
52
+ <Component name="PostForm" var.path="">
53
+ <APICall id="submit" method="post" url="#{submit_url}" headers="{appGlobals.auth}" body="{$param}"
54
+ onSuccess="(result) => path = result.directives.map((d) => d.name).join(' → ')" />
55
+ <APICall id="clear" method="post" url="#{clear_url}" headers="{appGlobals.auth}"
56
+ onSuccess="(result) => path = result.directives.map((d) => d.name).join(' → ')" />
57
+ <Form saveLabel="Post" onSubmit="(data) => submit.execute(data)">
58
+ <FormItem bindTo="author" label="Name" />
59
+ <FormItem bindTo="title" label="Title" />
60
+ <FormItem bindTo="body" label="Body (Markdown)" type="textarea" />
61
+ </Form>
62
+ <Card title="Event path"
63
+ subtitle="{path || 'Post something to see which rules ran, in order, across the rulesets.'}" />
64
+ <HStack>
65
+ <Button label="Clear the blog" variant="outlined" onClick="clear.execute({})" />
66
+ </HStack>
67
+ </Component>
68
+ >>
69
+ }
70
+ }
71
+
72
+ /**
73
+ * A post was submitted: check it, and pass it on as a new article.
74
+ * @attr author String "who wrote it"
75
+ * @attr title String "the title"
76
+ * @attr body String optional "the text, in Markdown"
77
+ * @example "hello" { "author": "Phil", "title": "Hello", "body": "First post" }
78
+ */
79
+ rule handle_submit {
80
+ select when kblog post_submitted
81
+ author re#(\S.*)#
82
+ title re#(\S.*)#
83
+ setting(author, title)
84
+ send_directive("handle_submit", {"title": title})
85
+ fired {
86
+ raise kblog event "new_article_available" attributes
87
+ {"author": author, "title": title, "body": event:attr("body") || ""}
88
+ }
89
+ }
90
+
91
+ /**
92
+ * A post without a name or a title is turned back.
93
+ */
94
+ rule reject_submit {
95
+ select when kblog post_submitted
96
+ where not (event:attr("author").defaultsTo("").match(re#\S#)
97
+ && event:attr("title").defaultsTo("").match(re#\S#))
98
+ send_directive("reject_submit", {"reason": "a post needs a name and a title"})
99
+ }
100
+
101
+ rule create_author_channel {
102
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
103
+ wrangler:createChannel(
104
+ author_tags,
105
+ {"allow": [{"domain": "kblog", "name": "post_submitted"}, {"domain": "kblog", "name": "clear_requested"}], "deny": []},
106
+ authorQueryPolicy()
107
+ )
108
+ }
109
+ }
@@ -0,0 +1,6 @@
1
+ - Open both links. On the reader channel the navigation has Home and Contact. On the author channel it also has **Post**.
2
+ - On the author channel, write a post. The **Event path** shows one rule from each of three rulesets: `handle_submit → add_article → show_new_article`. Home lists your post first, marked **New**.
3
+ - Submit a post without a title. The path is just `reject_submit`.
4
+ - Click an article's title. It has its own address (`#/post/<id>`), and the browser's back button returns to Home.
5
+ - Open the child pico's **Channels** tab. The `kblog, author` channel allows exactly two events, `post_submitted` and `clear_requested`. Send `kblog/new_article_available` on it with `curl`, trying to skip the check: the pico refuses it.
6
+ - Open the **Rulesets** tab: four KBlog rulesets, each with one job. `com.example.kblog.data` is the only one that stores articles.
@@ -0,0 +1,13 @@
1
+ # Layered rulesets demo
2
+
3
+ A base ruleset whose rule does one thing and raises an event, and two add-on rulesets that change what the pico does without editing it.
4
+
5
+ - Overview: [`docs/cookbook/layered_rulesets/README.md`](../../docs/cookbook/layered_rulesets/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/layered_rulesets/)
6
+ - Instructions: [`docs/cookbook/layered_rulesets/instructions.md`](../../docs/cookbook/layered_rulesets/instructions.md)
7
+
8
+ | File | Shows |
9
+ |------|-------|
10
+ | `com.example.invitations.krl` | The base: accepts full invitation URLs, records connections, raises `invite:connection_made`, and has the Invitations page, which adds the layers one at a time |
11
+ | `com.example.invitations.short_links.krl` | An add-on that selects the same event with a different URL pattern and raises it again with the full invitation |
12
+ | `com.example.invitations.welcome.krl` | An add-on that reacts to `invite:connection_made` |
13
+ | `com.example.invitations.bootstrap.krl` | Installs only the base on a new pico; the **Try It!** tab runs it |
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Try It! bootstrap for the Layered rulesets demo. Install it on a new pico: it
3
+ * installs io.picolabs.xmlui and the base com.example.invitations ruleset, and
4
+ * stops there. The Invitations page adds the two add-ons one at a time, so you
5
+ * can see what each one changes. tryIt() reports progress and links to the
6
+ * page.
7
+ *
8
+ * This ruleset does not use io.picolabs.xmlui as a module, because it is the
9
+ * one that installs it.
10
+ */
11
+ ruleset com.example.invitations.bootstrap {
12
+ meta {
13
+ name "Layered rulesets"
14
+ description "Shows rule chaining and layering: rules that each do one thing and raise an event, and add-on rulesets, installed one at a time, that select the same event or a raised one to change the pico without editing the base."
15
+ author "PICOLABS"
16
+
17
+ use module io.picolabs.wrangler alias wrangler
18
+
19
+ shares tryIt
20
+ }
21
+
22
+ global {
23
+ base_rid = "com.example.invitations"
24
+ xmlui_rid = "io.picolabs.xmlui"
25
+
26
+ host = function() {
27
+ meta:host.defaultsTo("").replace(re#/$#, "")
28
+ }
29
+
30
+ /**
31
+ * Progress of this demo's setup, and the links to open when it is ready.
32
+ * @returns Map
33
+ */
34
+ tryIt = function() {
35
+ app = wrangler:channels(["invitations", "app"]).head()
36
+ ready = (ent:stage == "ready" && app) => true | false
37
+ status = {
38
+ "ready": ready,
39
+ "stage": ent:stage.defaultsTo("starting"),
40
+ "links": ready => [
41
+ {"label": "Invitations", "url": host() + "/ui/" + app{"id"} + "/" + base_rid + "/"}
42
+ ] | []
43
+ }
44
+ status
45
+ }
46
+ }
47
+
48
+ rule start {
49
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
50
+ pre {
51
+ has_xmlui = wrangler:installedRIDs() >< xmlui_rid
52
+ }
53
+ if not has_xmlui then noop()
54
+ fired {
55
+ raise wrangler event "install_ruleset_request" attributes
56
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
57
+ }
58
+ else {
59
+ raise wrangler event "install_ruleset_request" attributes
60
+ {"absoluteURL": meta:rulesetURI, "rid": base_rid}
61
+ }
62
+ finally {
63
+ ent:stage := "installing"
64
+ raise wrangler event "new_channel_request" attributes {
65
+ "tags": ["try_it"],
66
+ "eventPolicy": {"allow": [], "deny": []},
67
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
68
+ }
69
+ }
70
+ }
71
+
72
+ rule install_base {
73
+ select when wrangler ruleset_installed where event:attr("rids") >< xmlui_rid
74
+ always {
75
+ raise wrangler event "install_ruleset_request" attributes
76
+ {"absoluteURL": meta:rulesetURI, "rid": base_rid}
77
+ }
78
+ }
79
+
80
+ // Only the base. The page adds the layers.
81
+ rule base_installed {
82
+ select when wrangler ruleset_installed where event:attr("rids") >< base_rid
83
+ always {
84
+ ent:stage := "ready"
85
+ }
86
+ }
87
+ }
@@ -0,0 +1,164 @@
1
+ /**
2
+ * Invitations: the base ruleset. It accepts a full invitation, an http(s) URL
3
+ * with a c_i parameter that encodes who is inviting, and records the
4
+ * connection. Its one rule does one thing, then raises invite:connection_made
5
+ * so other rulesets can react. It doesn't end the chain.
6
+ *
7
+ * Other rulesets layer on top without changing this one:
8
+ * com.example.invitations.short_links selects the same event with a different
9
+ * URL pattern, and com.example.invitations.welcome selects connection_made.
10
+ *
11
+ * The demo page installs them one at a time (layers:next_layer_requested), so
12
+ * you can see what each one changes. That rule is demo scaffolding: on a real
13
+ * pico the operator installs rulesets, and a page can't.
14
+ */
15
+ ruleset com.example.invitations {
16
+ meta {
17
+ name "Invitations"
18
+ description "Accepts full invitation URLs and records connections; other rulesets layer on top."
19
+ author "PICOLABS"
20
+
21
+ use module io.picolabs.wrangler alias wrangler
22
+ use module io.picolabs.xmlui alias ui
23
+
24
+ shares connections, layers, invitationsPage
25
+ }
26
+
27
+ global {
28
+ channel_tags = ["invitations", "app"]
29
+ add_ons = ["com.example.invitations.short_links", "com.example.invitations.welcome"]
30
+ full_invitation = "https://agents.example/invite?c_i=eyJsYWJlbCI6IkFkYSBMb3ZlbGFjZSJ9"
31
+ short_link = "https://short.example/alan"
32
+
33
+ labelOf = function(code) {
34
+ invitation = math:base64decode(code).decode()
35
+ label = invitation.typeof() == "Map" => invitation{"label"} | null
36
+ label || "someone"
37
+ }
38
+
39
+ /**
40
+ * Every connection made, oldest first.
41
+ * @returns Array of { label, url, time }
42
+ */
43
+ connections = function() {
44
+ ent:connections.defaultsTo([])
45
+ }
46
+
47
+ /**
48
+ * The add-on rulesets, in the order they are layered on, and whether each
49
+ * is installed on this pico.
50
+ * @returns Array of { rid, installed }
51
+ */
52
+ layers = function() {
53
+ installed = wrangler:installedRIDs()
54
+ add_ons.map(function(rid) { {"rid": rid, "installed": installed >< rid} })
55
+ }
56
+
57
+ nextLayer = function() {
58
+ layers().filter(function(layer) { not layer{"installed"} }).head(){"rid"}
59
+ }
60
+
61
+ /**
62
+ * Try the base ruleset alone, then add one layer at a time and see what
63
+ * each one changes.
64
+ * @view "Invitations"
65
+ */
66
+ invitationsPage = function() {
67
+ connections_url = ui:query_url("connections", meta:rid, meta:eci)
68
+ layers_url = ui:query_url("layers", meta:rid, meta:eci)
69
+ invite_url = ui:event_url("invite", "new_invitation")
70
+ next_url = ui:event_url("layers", "next_layer_requested")
71
+ <<
72
+ <Component name="InvitationsPage" var.answered="">
73
+ <DataSource id="connections" url="#{connections_url}" headers="{appGlobals.auth}" />
74
+ <DataSource id="layers" url="#{layers_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="3" />
75
+ <APICall id="invite" method="post" url="#{invite_url}" headers="{appGlobals.auth}" body="{$param}"
76
+ onSuccess="(result) => { answered = result.directives.map((d) => d.name).join(', ') || 'nothing: no rule selected that URL'; connections.refetch(); }" />
77
+ <APICall id="nextLayer" method="post" url="#{next_url}" headers="{appGlobals.auth}"
78
+ onSuccess="answered = ''; layers.refetch();" />
79
+ <PicoTheme>
80
+ <Card title="Invitations"
81
+ subtitle="Start with the base ruleset alone. Try both kinds of invitation, then add a layer and try them again. The reply lists the directive of every rule that ran, from every ruleset on this pico." />
82
+
83
+ <Card when="{layers.value &amp;&amp; layers.value.filter((l) => l.installed).length === 0}"
84
+ title="Step 1 of 3: the base ruleset alone">
85
+ <Text>Only com.example.invitations is installed. Its rule selects full invitations, the ones with a c_i parameter.</Text>
86
+ <Text>Expect: the full invitation answers "connected". The short link answers "nothing", because no rule selects it.</Text>
87
+ </Card>
88
+ <Card when="{layers.value &amp;&amp; layers.value.filter((l) => l.installed).length === 1}"
89
+ title="Step 2 of 3: short links layered on">
90
+ <Text>com.example.invitations.short_links selects the same event, but only for short links. It expands the link and raises the event again with the full invitation, which the base rule now selects.</Text>
91
+ <Text>Expect: the short link answers "expanded, connected". The full invitation still answers "connected": the new layer didn't select it.</Text>
92
+ </Card>
93
+ <Card when="{layers.value &amp;&amp; layers.value.filter((l) => l.installed).length === 2}"
94
+ title="Step 3 of 3: welcome layered on">
95
+ <Text>com.example.invitations.welcome selects invite:connection_made, the event the base rule raises after every connection, however it was made.</Text>
96
+ <Text>Expect: the short link answers "expanded, connected, welcome", and the full invitation "connected, welcome". The base ruleset never changed.</Text>
97
+ </Card>
98
+
99
+ <HStack wrapContent="true">
100
+ <Button label="Try the full invitation" onClick="invite.execute({url: '#{full_invitation}'})" />
101
+ <Button label="Try the short link" onClick="invite.execute({url: '#{short_link}'})" />
102
+ <Button label="{'Add the next layer: ' + layers.value.filter((l) => !l.installed)[0].rid}"
103
+ when="{layers.value &amp;&amp; layers.value.filter((l) => !l.installed).length > 0}"
104
+ variant="outlined" onClick="nextLayer.execute({})" />
105
+ </HStack>
106
+ <Card title="The pico answered" subtitle="{answered || '(nothing yet)'}" />
107
+
108
+ <Form saveLabel="Accept" onSubmit="(data) => invite.execute(data)">
109
+ <FormItem bindTo="url" label="Or paste any invitation URL" initialValue="https://short.example/grace" />
110
+ </Form>
111
+ <Table data="{connections}">
112
+ <Column bindTo="label" header="Connected to" />
113
+ <Column bindTo="url" header="From" />
114
+ </Table>
115
+ <Table data="{layers}">
116
+ <Column bindTo="rid" header="Layer" />
117
+ <Column bindTo="installed" header="Installed" />
118
+ </Table>
119
+ </PicoTheme>
120
+ </Component>
121
+ >>
122
+ }
123
+ }
124
+
125
+ /**
126
+ * Accept a full invitation and record the connection.
127
+ * @attr url String "an http(s) URL with a c_i parameter"
128
+ * @example "Ada" { "url": "https://agents.example/invite?c_i=eyJsYWJlbCI6IkFkYSBMb3ZlbGFjZSJ9" }
129
+ */
130
+ rule accept_invitation {
131
+ select when invite new_invitation
132
+ url re#^(https?://[^?]+[?](?:.*&)?c_i=([A-Za-z0-9+/_=-]+).*)$#
133
+ setting(url, code)
134
+ pre {
135
+ label = labelOf(code)
136
+ }
137
+ send_directive("connected", {"label": label})
138
+ fired {
139
+ ent:connections := connections().append({"label": label, "url": url, "time": time:now()})
140
+ raise invite event "connection_made" attributes {"label": label, "url": url}
141
+ }
142
+ }
143
+
144
+ /**
145
+ * Demo scaffolding: install the next add-on that isn't installed yet, from
146
+ * the folder this ruleset came from. Only the add-ons listed in this ruleset
147
+ * can be installed this way.
148
+ */
149
+ rule add_next_layer {
150
+ select when layers next_layer_requested
151
+ pre {
152
+ rid = nextLayer()
153
+ }
154
+ if rid then send_directive("add_next_layer", {"rid": rid})
155
+ fired {
156
+ raise wrangler event "install_ruleset_request" attributes {"absoluteURL": meta:rulesetURI, "rid": rid}
157
+ }
158
+ }
159
+
160
+ rule create_app_channel {
161
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
162
+ ui:create_app_channel(channel_tags, ["invite", "layers"], ["connections", "layers", "invitationsPage"], meta:rid)
163
+ }
164
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Short links: layered on com.example.invitations. A short link has no c_i
3
+ * parameter, so the base ruleset's rule doesn't select it. This rule selects
4
+ * the same event with a pattern only short links match, looks up the full
5
+ * invitation, and raises invite:new_invitation again with it. That time the
6
+ * base ruleset's rule selects it, and this one doesn't.
7
+ *
8
+ * A real short link would be expanded with http:get and its redirect; this one
9
+ * uses a table so the demo works offline.
10
+ */
11
+ ruleset com.example.invitations.short_links {
12
+ meta {
13
+ name "Invitation short links"
14
+ description "Expands short invitation links and passes the full invitation to the base ruleset."
15
+ author "PICOLABS"
16
+ }
17
+
18
+ global {
19
+ links = {
20
+ "grace": "https://agents.example/invite?c_i=eyJsYWJlbCI6IkdyYWNlIEhvcHBlciJ9",
21
+ "alan": "https://agents.example/invite?c_i=eyJsYWJlbCI6IkFsYW4gVHVyaW5nIn0="
22
+ }
23
+ }
24
+
25
+ /**
26
+ * Expand a short link and raise the event again with the full invitation.
27
+ * @attr url String "a short link, https://short.example/<code>"
28
+ * @example "Grace" { "url": "https://short.example/grace" }
29
+ */
30
+ rule expand_short_link {
31
+ select when invite new_invitation
32
+ url re#^https://short[.]example/(\w+)$#
33
+ setting(code)
34
+ pre {
35
+ full = links{code}
36
+ }
37
+ if full then send_directive("expanded", {"from": event:attr("url"), "to": full})
38
+ fired {
39
+ raise invite event "new_invitation" attributes event:attrs.put("url", full)
40
+ }
41
+ else {
42
+ raise invite event "unknown_short_link" attributes event:attrs
43
+ }
44
+ }
45
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Welcome: layered on com.example.invitations. It reacts to the event the base
3
+ * ruleset raises when it makes a connection, which the base ruleset raises
4
+ * whether or not anything listens.
5
+ */
6
+ ruleset com.example.invitations.welcome {
7
+ meta {
8
+ name "Invitation welcome"
9
+ description "Welcomes each new connection the base ruleset makes."
10
+ author "PICOLABS"
11
+
12
+ shares welcomed
13
+ }
14
+
15
+ global {
16
+ /**
17
+ * Everyone welcomed so far.
18
+ * @returns Array of String
19
+ */
20
+ welcomed = function() {
21
+ ent:welcomed.defaultsTo([])
22
+ }
23
+ }
24
+
25
+ /**
26
+ * Welcome a new connection.
27
+ * @attr label String "who the connection is with"
28
+ */
29
+ rule send_welcome {
30
+ select when invite connection_made
31
+ pre {
32
+ label = event:attr("label") || "friend"
33
+ }
34
+ send_directive("welcome", {"message": "Welcome, " + label + "!"})
35
+ fired {
36
+ ent:welcomed := welcomed().append(label)
37
+ }
38
+ }
39
+ }
@@ -0,0 +1,5 @@
1
+ - Open **Invitations** and follow its three steps. At each step, try both invitations and compare the answers with what the step says to expect, then click **Add the next layer**.
2
+ - After each layer, open the child pico's **Rulesets** tab. A ruleset was added, and `com.example.invitations` didn't change.
3
+ - With the short links layer installed, accept a short link and look at the **Logging** tab. `invite:new_invitation` arrives with the short URL, and under **Raised** it appears again with the full one.
4
+ - Uninstall `com.example.invitations.short_links` on the **Rulesets** tab. The page goes back a step, and the button offers that layer again.
5
+ - Write your own layer: a ruleset that selects `invite:unknown_short_link` (the short links layer raises it whether or not anything listens) and records the links nobody could expand.
@@ -0,0 +1,15 @@
1
+ # Moving picos demo
2
+
3
+ A pico and its children move from one engine to another, keeping their did:webvh identity and relationships.
4
+
5
+ - Overview: [`docs/cookbook/moving_picos/README.md`](../../docs/cookbook/moving_picos/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/moving_picos/)
6
+ - Instructions: [`docs/cookbook/moving_picos/instructions.md`](../../docs/cookbook/moving_picos/instructions.md)
7
+
8
+ | File | Install on |
9
+ |------|------------|
10
+ | `io.picolabs.club_gear_demo.krl` | Engine A, the Manifold app pico |
11
+ | `io.picolabs.ride_coordinator_demo.krl` | Engine B, the mesh root (optional) |
12
+
13
+ `docker-compose.cross-engine.yml` mounts `demos/` at `/var/pico-demos`, so install from `file:///var/pico-demos/moving_picos/<file>`.
14
+
15
+ Both rulesets use `ctx:newChannel` (and `club_gear_demo` uses `ctx:query`), a known exception to the rule that application rulesets go through wrangler.