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,84 @@
1
+ /**
2
+ * Try It! bootstrap for the Echo demo. Install it on a new pico: it installs
3
+ * io.picolabs.xmlui and com.example.echo. tryIt() reports progress and links
4
+ * to the Echo page.
5
+ *
6
+ * This ruleset does not use io.picolabs.xmlui as a module, because it is the
7
+ * one that installs it.
8
+ */
9
+ ruleset com.example.echo.bootstrap {
10
+ meta {
11
+ name "Echo"
12
+ description "Shows the basics of events: selecting an event with select when, matching an attribute with a regex, answering with send_directive, and sending the same event from a page and from curl."
13
+ author "PICOLABS"
14
+
15
+ use module io.picolabs.wrangler alias wrangler
16
+
17
+ shares tryIt
18
+ }
19
+
20
+ global {
21
+ app_rid = "com.example.echo"
22
+ xmlui_rid = "io.picolabs.xmlui"
23
+
24
+ host = function() {
25
+ meta:host.defaultsTo("").replace(re#/$#, "")
26
+ }
27
+
28
+ /**
29
+ * Progress of this demo's setup, and the links to open when it is ready.
30
+ * @returns Map
31
+ */
32
+ tryIt = function() {
33
+ app = wrangler:channels(["echo", "app"]).head()
34
+ ready = (ent:stage == "ready" && app) => true | false
35
+ status = {
36
+ "ready": ready,
37
+ "stage": ent:stage.defaultsTo("starting"),
38
+ "links": ready => [
39
+ {"label": "Echo page", "url": host() + "/ui/" + app{"id"} + "/" + app_rid + "/"}
40
+ ] | []
41
+ }
42
+ status
43
+ }
44
+ }
45
+
46
+ rule start {
47
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
48
+ pre {
49
+ has_xmlui = wrangler:installedRIDs() >< xmlui_rid
50
+ }
51
+ if not has_xmlui then noop()
52
+ fired {
53
+ raise wrangler event "install_ruleset_request" attributes
54
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
55
+ }
56
+ else {
57
+ raise wrangler event "install_ruleset_request" attributes
58
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
59
+ }
60
+ finally {
61
+ ent:stage := "installing"
62
+ raise wrangler event "new_channel_request" attributes {
63
+ "tags": ["try_it"],
64
+ "eventPolicy": {"allow": [], "deny": []},
65
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
66
+ }
67
+ }
68
+ }
69
+
70
+ rule install_app {
71
+ select when wrangler ruleset_installed where event:attr("rids") >< xmlui_rid
72
+ always {
73
+ raise wrangler event "install_ruleset_request" attributes
74
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
75
+ }
76
+ }
77
+
78
+ rule app_installed {
79
+ select when wrangler ruleset_installed where event:attr("rids") >< app_rid
80
+ always {
81
+ ent:stage := "ready"
82
+ }
83
+ }
84
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Echo: the hello world of events and directives. An event comes in; a rule
3
+ * selects on it and answers with a directive, which the sender gets back in the
4
+ * response. The view sends the events and shows the directive.
5
+ */
6
+ ruleset com.example.echo {
7
+ meta {
8
+ name "Echo"
9
+ description "Answers echo:hello and echo:message events with a say directive."
10
+ author "PICOLABS"
11
+
12
+ use module io.picolabs.xmlui alias ui
13
+
14
+ shares echoPage
15
+ }
16
+
17
+ global {
18
+ channel_tags = ["echo", "app"]
19
+
20
+ /**
21
+ * Send an echo event and see the directive that comes back.
22
+ * @view "Echo"
23
+ */
24
+ echoPage = function() {
25
+ hello_url = ui:event_url("echo", "hello")
26
+ message_url = ui:event_url("echo", "message")
27
+ <<
28
+ <Component name="EchoPage" var.reply="">
29
+ <APICall id="hello" method="post" url="#{hello_url}" headers="{appGlobals.auth}"
30
+ onSuccess="(result) => reply = result.directives[0].options.something" />
31
+ <APICall id="say" method="post" url="#{message_url}" headers="{appGlobals.auth}" body="{$param}"
32
+ onSuccess="(result) => reply = result.directives[0].options.something" />
33
+ <PicoTheme>
34
+ <Card title="Echo"
35
+ subtitle="Each button raises an event on this pico. A rule answers with a say directive, shown below." />
36
+ <HStack>
37
+ <Button label="Say hello" onClick="hello.execute({})" />
38
+ </HStack>
39
+ <Form saveLabel="Echo it" onSubmit="(data) => say.execute(data)">
40
+ <FormItem bindTo="input" label="Message" initialValue="KRL programs the Internet!" />
41
+ </Form>
42
+ <Card title="The pico said" subtitle="{reply || '(nothing yet)'}" />
43
+ <Text>The same message event from a terminal:</Text>
44
+ <Text variant="code">curl "#{meta:host}/sky/event/#{meta:eci}/curl/echo/message?input=hello"</Text>
45
+ </PicoTheme>
46
+ </Component>
47
+ >>
48
+ }
49
+ }
50
+
51
+ /**
52
+ * Answer with "Hello World".
53
+ */
54
+ rule hello_world {
55
+ select when echo hello
56
+ send_directive("say", {"something": "Hello World"})
57
+ }
58
+
59
+ /**
60
+ * Answer with the message that came in.
61
+ * @attr input String "what to echo"
62
+ * @example "hi" { "input": "hi" }
63
+ */
64
+ rule echo {
65
+ select when echo message input re#(.*)# setting(m)
66
+ send_directive("say", {"something": m})
67
+ }
68
+
69
+ rule create_app_channel {
70
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
71
+ ui:create_app_channel(channel_tags, ["echo"], ["echoPage"], meta:rid)
72
+ }
73
+ }
@@ -0,0 +1,5 @@
1
+ - Open **Echo page**. Click **Say hello**, then **Echo it**. Each answer is the `say` directive a rule sent back.
2
+ - Copy the `curl` line at the bottom of the page into a terminal. The JSON has the same directive, plus `ruleOutcomes`, which names the rule that fired.
3
+ - Change `echo/message` in that URL to `wrangler/new_child_request?name=x`. The pico refuses it: `Not allowed by channel policy`.
4
+ - Open the child pico and look at its **Channels** tab. The `echo, app` channel allows `echo` events and nothing else. That's why the last step failed.
5
+ - On its **Logging** tab, find the `echo:message` events you sent and the rule each one fired.
@@ -0,0 +1,12 @@
1
+ # Guard rules demo
2
+
3
+ Ask for something five times and get it once. A guard rule makes a request idempotent, and a gate rule with `last` refuses work until it can be done.
4
+
5
+ - Overview: [`docs/cookbook/guard_rules/README.md`](../../docs/cookbook/guard_rules/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/guard_rules/)
6
+ - Instructions: [`docs/cookbook/guard_rules/instructions.md`](../../docs/cookbook/guard_rules/instructions.md)
7
+
8
+ | File | Shows |
9
+ |------|-------|
10
+ | `com.example.archive.krl` | A guard rule and the rule it starts, a gate rule with `last`, and the Archive page |
11
+ | `com.example.archive_store.krl` | Installed on the Archive child pico; keeps the notes |
12
+ | `com.example.archive.bootstrap.krl` | Sets up the demo on a new pico, asks for the archive five times, and tries a note too early; the **Try It!** tab runs it |
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Try It! bootstrap for the Guard rules demo. Install it on a new pico: it
3
+ * installs io.picolabs.xmlui and com.example.archive. Then, in one go, it asks
4
+ * for the archive five times and tries to add a note before the archive exists.
5
+ * The guard lets one request through and the gate refuses the early note. When
6
+ * the archive is created, it adds a note that is stored. tryIt() reports
7
+ * progress and links to the Archive page.
8
+ *
9
+ * This ruleset does not use io.picolabs.xmlui as a module, because it is the
10
+ * one that installs it.
11
+ */
12
+ ruleset com.example.archive.bootstrap {
13
+ meta {
14
+ name "Guard rules"
15
+ description "Shows guard rules for idempotent requests, a gate rule that stops later rules with last, and why rule order within a ruleset matters."
16
+ author "PICOLABS"
17
+
18
+ use module io.picolabs.wrangler alias wrangler
19
+
20
+ shares tryIt
21
+ }
22
+
23
+ global {
24
+ app_rid = "com.example.archive"
25
+ xmlui_rid = "io.picolabs.xmlui"
26
+
27
+ host = function() {
28
+ meta:host.defaultsTo("").replace(re#/$#, "")
29
+ }
30
+
31
+ /**
32
+ * Progress of this demo's setup, and the links to open when it is ready.
33
+ * @returns Map
34
+ */
35
+ tryIt = function() {
36
+ app = wrangler:channels(["archive", "app"]).head()
37
+ ready = (ent:stage == "ready" && app) => true | false
38
+ status = {
39
+ "ready": ready,
40
+ "stage": ent:stage.defaultsTo("starting"),
41
+ "links": ready => [
42
+ {"label": "Archive", "url": host() + "/ui/" + app{"id"} + "/" + app_rid + "/"}
43
+ ] | []
44
+ }
45
+ status
46
+ }
47
+ }
48
+
49
+ rule start {
50
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
51
+ pre {
52
+ has_xmlui = wrangler:installedRIDs() >< xmlui_rid
53
+ }
54
+ if not has_xmlui then noop()
55
+ fired {
56
+ raise wrangler event "install_ruleset_request" attributes
57
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
58
+ }
59
+ else {
60
+ raise wrangler event "install_ruleset_request" attributes
61
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
62
+ }
63
+ finally {
64
+ ent:stage := "installing"
65
+ raise wrangler event "new_channel_request" attributes {
66
+ "tags": ["try_it"],
67
+ "eventPolicy": {"allow": [], "deny": []},
68
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
69
+ }
70
+ }
71
+ }
72
+
73
+ rule install_app {
74
+ select when wrangler ruleset_installed where event:attr("rids") >< xmlui_rid
75
+ always {
76
+ raise wrangler event "install_ruleset_request" attributes
77
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
78
+ }
79
+ }
80
+
81
+ rule ask_five_times {
82
+ select when wrangler ruleset_installed where event:attr("rids") >< app_rid
83
+ foreach [1, 2, 3, 4, 5] setting(n)
84
+ always {
85
+ ent:stage := "asking for the archive"
86
+ raise archive event "needed" attributes {"try": n}
87
+ raise archive event "note_added" attributes {"text": "Too early"} on final
88
+ }
89
+ }
90
+
91
+ rule add_a_note {
92
+ select when archive archive_created where ent:stage != "ready"
93
+ always {
94
+ raise archive event "note_added" attributes {"text": "Written after the archive was created"}
95
+ ent:stage := "ready"
96
+ }
97
+ }
98
+ }
@@ -0,0 +1,213 @@
1
+ /**
2
+ * Guard rules: this pico needs exactly one Archive child pico, however many
3
+ * times archive:needed arrives. A guard rule decides whether to go ahead and
4
+ * raises an event; a second rule does the work. Asking again changes nothing,
5
+ * so the request is idempotent.
6
+ *
7
+ * Notes are stored in the archive. A gate rule stops archive:note_added with
8
+ * `last` until the archive exists. Rules in one ruleset that select the same
9
+ * event run in the order they are written, and `last` skips the rest of this
10
+ * ruleset's rules for the event, so the gate comes first and lives in the same
11
+ * ruleset as the rule it guards.
12
+ */
13
+ ruleset com.example.archive {
14
+ meta {
15
+ name "Archive keeper"
16
+ description "Creates one Archive child however often it is asked, and stores notes in it once it exists."
17
+ author "PICOLABS"
18
+
19
+ use module io.picolabs.wrangler alias wrangler
20
+ use module io.picolabs.xmlui alias ui
21
+
22
+ shares status, notes, archivePage
23
+ }
24
+
25
+ global {
26
+ channel_tags = ["archive", "app"]
27
+ store_rid = "com.example.archive_store"
28
+
29
+ archives = function() {
30
+ wrangler:children().filter(function(child) { child{"name"} == "Archive" })
31
+ }
32
+
33
+ /**
34
+ * The archive's state and the counts the page shows.
35
+ * @returns Map
36
+ */
37
+ status = function() {
38
+ state = ent:archive_eci => "ready" | ent:creating => "being created" | "none"
39
+ counts = {
40
+ "archive": state,
41
+ "archive_picos": archives().length(),
42
+ "requests": ent:requests.defaultsTo(0),
43
+ "ignored": ent:ignored.defaultsTo(0),
44
+ "gated": ent:gated.defaultsTo(0)
45
+ }
46
+ counts
47
+ }
48
+
49
+ /**
50
+ * The notes stored in the archive, oldest first.
51
+ * @returns Array of { text, time }
52
+ */
53
+ notes = function() {
54
+ stored = ent:archive_eci => wrangler:picoQuery(ent:archive_eci, store_rid, "notes") | []
55
+ stored.typeof() == "Array" => stored | []
56
+ }
57
+
58
+ /**
59
+ * Ask for the archive as often as you like, and add notes.
60
+ * @view "Archive"
61
+ */
62
+ archivePage = function() {
63
+ status_url = ui:query_url("status", meta:rid, meta:eci)
64
+ notes_url = ui:query_url("notes", meta:rid, meta:eci)
65
+ needed_url = ui:event_url("archive", "needed")
66
+ note_url = ui:event_url("archive", "note_added")
67
+ reset_url = ui:event_url("archive", "reset")
68
+ <<
69
+ <Component name="ArchivePage" var.said="">
70
+ <DataSource id="status" url="#{status_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="1" />
71
+ <DataSource id="notes" url="#{notes_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="2" />
72
+ <APICall id="needed" method="post" url="#{needed_url}" headers="{appGlobals.auth}"
73
+ onSuccess="(result) => { said = result.directives.length ? 'Guard: go ahead' : 'Guard: already have one, ignored'; status.refetch(); }" />
74
+ <APICall id="note" method="post" url="#{note_url}" headers="{appGlobals.auth}" body="{$param}"
75
+ onSuccess="(result) => { said = result.directives.length ? 'Note: ' + result.directives[0].options.result : ''; status.refetch(); notes.refetch(); }" />
76
+ <APICall id="reset" method="post" url="#{reset_url}" headers="{appGlobals.auth}"
77
+ onSuccess="said = ''; status.refetch(); notes.refetch();" />
78
+ <PicoTheme>
79
+ <Card title="Archive"
80
+ subtitle="Click Request the archive as often as you like. The guard lets one request through; the rest change nothing." />
81
+ <HStack>
82
+ <Button label="Request the archive" onClick="needed.execute({})" />
83
+ <Button label="Start over" variant="outlined" onClick="reset.execute({})" />
84
+ </HStack>
85
+ <Text when="{said}">{said}</Text>
86
+ <Table data="{[status.value]}">
87
+ <Column bindTo="archive" header="Archive" />
88
+ <Column bindTo="archive_picos" header="Archive picos" />
89
+ <Column bindTo="requests" header="Requests" />
90
+ <Column bindTo="ignored" header="Ignored" />
91
+ <Column bindTo="gated" header="Notes refused" />
92
+ </Table>
93
+ <Form saveLabel="Add a note" onSubmit="(data) => note.execute(data)">
94
+ <FormItem bindTo="text" label="Note" initialValue="Remember the milk" />
95
+ </Form>
96
+ <Table data="{notes}">
97
+ <Column bindTo="text" header="Notes in the archive" />
98
+ <Column bindTo="time" header="Stored" />
99
+ </Table>
100
+ </PicoTheme>
101
+ </Component>
102
+ >>
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Guard: go ahead only when there is no archive and none is being created.
108
+ * The flag ent:creating matters: the child does not exist until
109
+ * child_initialized arrives, and requests can come in before then.
110
+ */
111
+ rule archive_needed {
112
+ select when archive needed
113
+ pre {
114
+ allowed = not ent:archive_eci && not ent:creating
115
+ }
116
+ if allowed then send_directive("archive", {"result": "creating"})
117
+ fired {
118
+ ent:creating := true
119
+ raise archive event "creation_approved"
120
+ }
121
+ else {
122
+ ent:ignored := ent:ignored.defaultsTo(0) + 1
123
+ }
124
+ finally {
125
+ ent:requests := ent:requests.defaultsTo(0) + 1
126
+ }
127
+ }
128
+
129
+ // The work: create the archive. Only the guard raises this event.
130
+ rule create_archive {
131
+ select when archive creation_approved
132
+ always {
133
+ raise wrangler event "new_child_request" attributes {"name": "Archive", "archive_role": "store"}
134
+ }
135
+ }
136
+
137
+ // The child is set up: give it the store ruleset, and tell anyone listening.
138
+ rule archive_initialized {
139
+ select when wrangler child_initialized where event:attr("archive_role") == "store"
140
+ event:send({
141
+ "eci": event:attr("eci"),
142
+ "domain": "wrangler",
143
+ "type": "install_ruleset_request",
144
+ "attrs": {"absoluteURL": meta:rulesetURI, "rid": store_rid}
145
+ })
146
+ always {
147
+ ent:archive_eci := event:attr("eci")
148
+ ent:creating := false
149
+ raise archive event "archive_created" attributes {"eci": event:attr("eci")}
150
+ }
151
+ }
152
+
153
+ /**
154
+ * Gate: no archive, no notes. It comes before store_note, and `last` skips
155
+ * store_note for this event.
156
+ */
157
+ rule require_archive {
158
+ select when archive note_added
159
+ if not ent:archive_eci then send_directive("note", {"result": "refused, no archive yet"})
160
+ fired {
161
+ ent:gated := ent:gated.defaultsTo(0) + 1
162
+ last
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Store a note in the archive.
168
+ * @attr text String "the note"
169
+ * @example "milk" { "text": "Remember the milk" }
170
+ */
171
+ rule store_note {
172
+ select when archive note_added
173
+ text re#(.+)#
174
+ setting(text)
175
+ every {
176
+ event:send({
177
+ "eci": ent:archive_eci,
178
+ "domain": "archive",
179
+ "type": "store",
180
+ "attrs": {"text": text}
181
+ })
182
+ send_directive("note", {"result": "stored"})
183
+ }
184
+ }
185
+
186
+ /**
187
+ * Delete the archive and the counts, to try again.
188
+ */
189
+ rule reset {
190
+ select when archive reset
191
+ always {
192
+ raise archive event "archives_to_delete" attributes {"archives": archives()}
193
+ ent:archive_eci := null
194
+ ent:creating := false
195
+ ent:requests := 0
196
+ ent:ignored := 0
197
+ ent:gated := 0
198
+ }
199
+ }
200
+
201
+ rule delete_archives {
202
+ select when archive archives_to_delete
203
+ foreach event:attr("archives") setting(child)
204
+ always {
205
+ raise wrangler event "child_deletion_request" attributes {"eci": child{"eci"}}
206
+ }
207
+ }
208
+
209
+ rule create_app_channel {
210
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
211
+ ui:create_app_channel(channel_tags, ["archive"], ["status", "notes", "archivePage"], meta:rid)
212
+ }
213
+ }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Archive store: installed on the Archive child pico. Keeps the notes its
3
+ * parent sends and shares them back.
4
+ */
5
+ ruleset com.example.archive_store {
6
+ meta {
7
+ name "Archive store"
8
+ description "Keeps the notes the archive keeper sends."
9
+ author "PICOLABS"
10
+
11
+ shares notes
12
+ }
13
+
14
+ global {
15
+ /**
16
+ * Every note, oldest first.
17
+ * @returns Array of { text, time }
18
+ */
19
+ notes = function() {
20
+ ent:notes.defaultsTo([])
21
+ }
22
+ }
23
+
24
+ /**
25
+ * Keep a note.
26
+ * @attr text String "the note"
27
+ */
28
+ rule store {
29
+ select when archive store
30
+ text re#(.+)#
31
+ setting(text)
32
+ always {
33
+ ent:notes := notes().append({"text": text, "time": time:now()})
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,5 @@
1
+ - Open **Archive**. The bootstrap asked for the archive five times: 1 archive pico, 5 requests, 4 ignored. It also added a note too early, so 1 note was refused.
2
+ - Click **Request the archive** several times. **Ignored** goes up, and **Archive picos** stays at 1.
3
+ - Leave the **Try It!** tab and close the pico. The demo's child has exactly one child, Archive.
4
+ - Click **Start over**, then **Add a note** before requesting the archive. The gate rule refuses it.
5
+ - Look at `archive_needed` in `com.example.archive.krl`. Why does it check `ent:creating` as well as `ent:archive_eci`? Remove `&& not ent:creating`, click **Flush**, and run the demo again from this window to find out.
@@ -0,0 +1,11 @@
1
+ # Querying JSON demo
2
+
3
+ Find values in nested JSON with KRL's `query()` operator and JSONPath. The pico holds a fleet's vehicles, trips, and fill-ups, and a page runs four canned queries against it, or one you type.
4
+
5
+ - Overview: [`docs/cookbook/json_query/README.md`](../../docs/cookbook/json_query/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/json_query/)
6
+ - Instructions: [`docs/cookbook/json_query/instructions.md`](../../docs/cookbook/json_query/instructions.md)
7
+
8
+ | File | Shows |
9
+ |------|-------|
10
+ | `com.example.json_query.krl` | The fleet data, the canned queries, a `runQuery(path)` function that calls `fleet.query(path)`, and a page that shows the data and runs the queries |
11
+ | `com.example.json_query.bootstrap.krl` | Sets up the demo on a new pico; the **Try It!** tab runs it |
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Try It! bootstrap for the Querying JSON demo. Install it on a new pico: it
3
+ * installs io.picolabs.xmlui and com.example.json_query. tryIt() reports
4
+ * progress and links to the query page.
5
+ *
6
+ * This ruleset does not use io.picolabs.xmlui as a module, because it is the
7
+ * one that installs it.
8
+ */
9
+ ruleset com.example.json_query.bootstrap {
10
+ meta {
11
+ name "Querying JSON"
12
+ description "Shows the query() operator: finding values in nested JSON with JSONPath child, wildcard, descendant, and filter selectors, and filter functions such as count()."
13
+ author "PICOLABS"
14
+
15
+ use module io.picolabs.wrangler alias wrangler
16
+
17
+ shares tryIt
18
+ }
19
+
20
+ global {
21
+ app_rid = "com.example.json_query"
22
+ xmlui_rid = "io.picolabs.xmlui"
23
+
24
+ host = function() {
25
+ meta:host.defaultsTo("").replace(re#/$#, "")
26
+ }
27
+
28
+ /**
29
+ * Progress of this demo's setup, and the links to open when it is ready.
30
+ * @returns Map
31
+ */
32
+ tryIt = function() {
33
+ app = wrangler:channels(["json_query", "app"]).head()
34
+ ready = (ent:stage == "ready" && app) => true | false
35
+ status = {
36
+ "ready": ready,
37
+ "stage": ent:stage.defaultsTo("starting"),
38
+ "links": ready => [
39
+ {"label": "Query page", "url": host() + "/ui/" + app{"id"} + "/" + app_rid + "/"}
40
+ ] | []
41
+ }
42
+ status
43
+ }
44
+ }
45
+
46
+ rule start {
47
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
48
+ pre {
49
+ has_xmlui = wrangler:installedRIDs() >< xmlui_rid
50
+ }
51
+ if not has_xmlui then noop()
52
+ fired {
53
+ raise wrangler event "install_ruleset_request" attributes
54
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
55
+ }
56
+ else {
57
+ raise wrangler event "install_ruleset_request" attributes
58
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
59
+ }
60
+ finally {
61
+ ent:stage := "installing"
62
+ raise wrangler event "new_channel_request" attributes {
63
+ "tags": ["try_it"],
64
+ "eventPolicy": {"allow": [], "deny": []},
65
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
66
+ }
67
+ }
68
+ }
69
+
70
+ rule install_app {
71
+ select when wrangler ruleset_installed where event:attr("rids") >< xmlui_rid
72
+ always {
73
+ raise wrangler event "install_ruleset_request" attributes
74
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
75
+ }
76
+ }
77
+
78
+ rule app_installed {
79
+ select when wrangler ruleset_installed where event:attr("rids") >< app_rid
80
+ always {
81
+ ent:stage := "ready"
82
+ }
83
+ }
84
+ }