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
@@ -1,7 +1,6 @@
1
- /* Rules with a public facing point of entry are camelCase, internal rules are snake_case
2
- For skyQuery and parent-child trees:
3
- wrangler is built so that the parent can skyQuery its children for info at any time,
4
- but children only get information from their direct parent through event-passing to prevent race conditions
1
+ /*
2
+ Rules with a public facing point of entry are camelCase, internal rules are snake_case
3
+ For skyQuery and parent-child trees: wrangler is built so that the parent can skyQuery its children for info at any time, but children only get information from their direct parent through event-passing to prevent race conditions
5
4
  */
6
5
  ruleset io.picolabs.wrangler {
7
6
  meta {
@@ -12,18 +11,18 @@ ruleset io.picolabs.wrangler {
12
11
  This Ruleset/Module provides a developer interface to the pico (persistent compute object).
13
12
  When a pico is created this ruleset will be installed to provide essential services.
14
13
  >>
15
- author "BYU Pico Lab"
14
+ author "Pico Labs"
16
15
 
17
16
  provides skyQuery, picoQuery,
18
17
  channels, createChannel, updateChannel, deleteChannel, //channel
19
18
  discoveryChannel, filterBindingsForCaller, //discovery
20
- rulesetConfig, rulesetMeta, installedRIDs, //ruleset
19
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
21
20
  children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, establishRelationship, callerDid //pico
22
21
 
23
22
  shares skyQuery, picoQuery,
24
23
  channels, //channel
25
24
  discoveryChannel, filterBindingsForCaller, //discovery
26
- rulesetConfig, rulesetMeta,installedRIDs, //ruleset
25
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
27
26
  children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, establishRelationship, callerDid, id //pico
28
27
  }
29
28
  global {
@@ -32,7 +31,7 @@ ruleset io.picolabs.wrangler {
32
31
  { "name": "channels", "args":["tags"] },
33
32
  { "name": "discoveryChannel"},
34
33
  { "name": "installedRIDs"},
35
- {"name":"skyQuery", "args":["eci", "mod", "func", "params","_host","_path","_root_url"]},
34
+ {"name":"picoQuery", "args":["eci", "mod", "func", "params","_host","_path","_root_url"]},
36
35
  {"name":"children", "args":[]}
37
36
  ],
38
37
  "events": [
@@ -122,6 +121,7 @@ ruleset io.picolabs.wrangler {
122
121
  (status == 200 && not is_bad_response) => response_content | error.klog("error: ")
123
122
  }
124
123
 
124
+ // Deprecated: use picoQuery. Shared for old rulesets; not discoverable.
125
125
  skyQuery = function(eci, mod, func, params,_host,_path,_root_url) { // path must start with "/"", _host must include protocol(http:// or https://)
126
126
  //.../sky/query/<eci>/<rid>/<name>?name0=value0&...&namen=valuen
127
127
  thisPico = ctx:channels.any(function(c){c{"id"}==eci})
@@ -143,6 +143,36 @@ ruleset io.picolabs.wrangler {
143
143
  response
144
144
  }
145
145
 
146
+ /**
147
+ * Query a shared function on another pico. Picos on this engine are queried
148
+ * directly (which also works over parent/child family channels); a DID is
149
+ * queried over DIDComm; picos on another engine (_host) over HTTP. Querying
150
+ * one of this pico's own channels is refused. On failure, returns a map with
151
+ * error, httpStatus, and picoQueryError.
152
+ * @param eci String "channel on the other pico, or its DID"
153
+ * @param mod String "ruleset id on the other pico"
154
+ * @param func String "shared function to call"
155
+ * @param params Map "arguments for the function"
156
+ * @param _host String "the other pico's engine URL, if on a different engine"
157
+ * @param _path String "path prefix on that engine (default /sky/cloud/)"
158
+ * @param _root_url String "full query URL prefix, instead of _host and _path"
159
+ * @returns Any "the function's result, or an error map"
160
+ * @example "child's name" { "eci": "<child family eci>", "mod": "io.picolabs.wrangler", "func": "name" }
161
+ * @example "another engine" { "eci": "<eci>", "mod": "<rid>", "func": "<function>", "params": {}, "_host": "https://other.example" }
162
+ */
163
+ /**
164
+ * Query through a channel on this pico (policy applies). Used by view file()
165
+ * to render components on the same channel as the browser request.
166
+ * @param eci String "channel on this pico"
167
+ * @param rid String "ruleset id"
168
+ * @param name String "shared function"
169
+ * @param params Map "query arguments"
170
+ * @returns Any
171
+ */
172
+ channelQuery = function(eci, rid, name, params) {
173
+ ctx:query(eci, rid, name, params.defaultsTo({}))
174
+ }
175
+
146
176
  picoQuery = function(eci, mod, func, params,_host,_path,_root_url) {
147
177
  isDid = eci.match(re#^did:#)
148
178
  thisPico = ctx:channels.any(function(c){c{"id"}==eci})
@@ -168,22 +198,95 @@ ruleset io.picolabs.wrangler {
168
198
  ctx:rulesets.filter(function(rs){rs{"rid"}==rid}).head()
169
199
  }
170
200
 
201
+ /**
202
+ * The configuration an installed ruleset was installed with, or null if it
203
+ * isn't installed.
204
+ * @param rid String "ruleset id"
205
+ * @returns Map
206
+ */
171
207
  rulesetConfig = function(rid) {
172
208
  rulesetByRID(rid){"config"}
173
209
  }
174
210
 
211
+ /**
212
+ * The meta block of an installed ruleset (name, description, shares, provides,
213
+ * …), or null if it isn't installed.
214
+ * @param rid String "ruleset id"
215
+ * @returns Map
216
+ */
175
217
  rulesetMeta = function(rid) {
176
218
  rulesetByRID(rid){["meta","krlMeta"]}
177
219
  }
178
220
 
221
+ /**
222
+ * Ids of the rulesets installed on this pico.
223
+ * @returns Array
224
+ */
179
225
  installedRIDs = function() {
180
226
  ctx:rulesets.map(function(rs){rs{"rid"}})
181
227
  }
182
228
 
229
+ /**
230
+ * Everything discoverable on this pico: the annotated operations and queries of
231
+ * all installed rulesets, merged and grouped by event, with any attr type
232
+ * conflicts between rulesets. For discovery and generated tools (MCP).
233
+ * @returns Map "{ version, rulesets, events, queries, conflicts }"
234
+ */
235
+ picoSchema = function() {
236
+ ctx:picoSchema()
237
+ }
238
+
239
+ /**
240
+ * The discovery schema of one installed ruleset: its annotated operations (with
241
+ * their select, condition, prechecks, emits, and the other rules on the same
242
+ * event) and queries. What the Testing tab shows. Null if not installed.
243
+ * @param rid String "ruleset id"
244
+ * @returns Map
245
+ * @example "one ruleset" { "rid": "io.picolabs.pds" }
246
+ * @example "all installed" {}
247
+ */
248
+ rulesetSchema = function(rid = null) {
249
+ ctx:rulesetSchema(rid)
250
+ }
251
+
252
+ /**
253
+ * Compiler/schema warnings for an installed ruleset (from last flush/load).
254
+ * @param rid String "ruleset id"
255
+ * @returns Array
256
+ */
257
+ rulesetWarnings = function(rid) {
258
+ ctx:rulesetWarnings(rid)
259
+ }
260
+
261
+ /**
262
+ * The part of picoSchema() a channel allows: what a caller holding this ECI can
263
+ * discover and use. Use the caller's own ECI for "what can I do here?", or any
264
+ * channel to check what it would expose.
265
+ * @param eci String "channel on this pico"
266
+ * @returns Map
267
+ */
268
+ channelSchema = function(eci) {
269
+ ctx:channelSchema(eci)
270
+ }
271
+
272
+ // Builds the discovery bindings() shape from a ruleset schema, for rulesets that
273
+ // implement discovery capabilities. A KRL helper; not discoverable.
274
+ schemaBindings = function(rid) {
275
+ ctx:schemaBindings(rid)
276
+ }
277
+
183
278
  // ********************************************************************************************
184
279
  // *** Channels ***
185
280
  // ********************************************************************************************
186
281
 
282
+ /**
283
+ * This pico's channels, with their tags and event and query policies. With tags,
284
+ * only channels whose tags are exactly those (order and case don't matter).
285
+ * @param tags String "comma-separated tags, or an array of tags"
286
+ * @returns Array
287
+ * @example "all" {}
288
+ * @example "by tags" { "tags": "discovery" }
289
+ */
187
290
  channels = function(tags){
188
291
  all_channels = ctx:channels
189
292
  str_tags = tags.typeof()=="Array" => tags.join(",") | tags
@@ -233,6 +336,11 @@ ruleset io.picolabs.wrangler {
233
336
  }
234
337
  }
235
338
 
339
+ /**
340
+ * This pico's discovery channel, which every pico has: integrators query it to
341
+ * learn what the pico can do.
342
+ * @returns Map "the channel, including its id"
343
+ */
236
344
  discoveryChannel = function() {
237
345
  channels("discovery").head()
238
346
  }
@@ -309,6 +417,8 @@ ruleset io.picolabs.wrangler {
309
417
  }
310
418
  }
311
419
 
420
+ // Filters a bindings() map down to what caller_eci's channel policy allows. A KRL
421
+ // helper for discovery rulesets; not discoverable.
312
422
  filterBindingsForCaller = function(bindings, caller_eci, rid) {
313
423
  caller_eci.isnull() => bindings |
314
424
  filterBindingsBody(bindings.defaultsTo({}), caller_eci, rid)
@@ -318,6 +428,10 @@ ruleset io.picolabs.wrangler {
318
428
  // *** Picos ***
319
429
  // ********************************************************************************************
320
430
 
431
+ /**
432
+ * This pico's wrangler name, id, and the ECI it was created with.
433
+ * @returns Map "{ name, id, eci }"
434
+ */
321
435
  myself = function(){
322
436
  {
323
437
  "name":ent:name,
@@ -326,12 +440,21 @@ ruleset io.picolabs.wrangler {
326
440
  }
327
441
  }
328
442
 
329
- /** Portable did:webvh for this pico (Layer 2). */
443
+ /**
444
+ * This pico's portable did:webvh, the identity other picos and meshes use for
445
+ * Layer 2 relationships. It survives moving the pico to another engine.
446
+ * @returns String
447
+ */
330
448
  myDid = function() {
331
449
  dido:myDid()
332
450
  }
333
451
 
334
- /** True when this pico accepts unsolicited intro DIDComm on its did:webvh. */
452
+ /**
453
+ * True when this pico accepts unsolicited introduction messages (Layer 2
454
+ * relationship requests) on its did:webvh. Change it with
455
+ * wrangler:set_public_intro.
456
+ * @returns Boolean
457
+ */
335
458
  publicIntro = function() {
336
459
  dido:publicIntro()
337
460
  }
@@ -340,19 +463,25 @@ ruleset io.picolabs.wrangler {
340
463
  dido:setPublicIntro(enabled)
341
464
  }
342
465
 
343
- /** Layer 2: create did:peer + internal Rx for a relationship bus map. */
466
+ // Layer 2: create did:peer + internal Rx for a relationship bus map.
467
+ // Called by io.picolabs.subscription; not discoverable.
344
468
  establishSubscription = function(bus) {
345
469
  dido:establishSubscription(bus)
346
470
  }
347
471
 
348
- /** Alias for establishSubscription (preferred name in new rulesets). */
472
+ // Alias for establishSubscription (preferred name in new rulesets).
349
473
  establishRelationship = establishSubscription
350
474
 
351
- /** did:webvh of the pico that sent the current event (layer2 cross-pico delivery). */
475
+ // did:webvh of the pico that sent the current event (layer2 cross-pico delivery).
476
+ // Only meaningful inside a rule handling that event; not discoverable.
352
477
  callerDid = function() {
353
478
  event:attr("callerDid")
354
479
  }
355
480
 
481
+ /**
482
+ * This pico's children, each with its family-channel ECI, name, and parent ECI.
483
+ * @returns Array "[ { eci, name, parent_eci } ]"
484
+ */
356
485
  children = function() {
357
486
  convert = function(eci){
358
487
  pico = {}
@@ -366,17 +495,84 @@ ruleset io.picolabs.wrangler {
366
495
  wrangler_children
367
496
  }
368
497
 
498
+ /**
499
+ * The family-channel ECI of this pico's parent; null for a root pico.
500
+ * @returns String
501
+ */
369
502
  parent_eci = function() {
370
503
  ent:parent_eci
371
504
  }
372
505
 
506
+ /**
507
+ * This pico's wrangler name.
508
+ * @returns String
509
+ */
373
510
  name = function() {
374
511
  ent:name
375
512
  }
376
513
 
514
+ /**
515
+ * This pico's id.
516
+ * @returns String
517
+ */
377
518
  id = function() {
378
519
  meta:picoId
379
520
  }
521
+
522
+ // OS bootstrap for a new child (shared by events and import queries).
523
+ bootstrapNewChild = defaction(name, passthroughAttrs) {
524
+ attrs = passthroughAttrs.defaultsTo({})
525
+ policyCeiling = attrs{"policyCeiling"}
526
+ engine_ui_rid = "io.picolabs.pico-engine-ui"
527
+ engine_ui_ruleset = function(){
528
+ the_ruleset = ctx:rulesets
529
+ .filter(function(r){r.get("rid")==engine_ui_rid})
530
+ .head();
531
+ { "url":the_ruleset.get("url"),
532
+ "config":the_ruleset.get("config")
533
+ }
534
+ }
535
+ parentUiEci = ctx:channels
536
+ .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
537
+ .map(function(c){c["id"]})
538
+ .head()
539
+ childBoxAttrs = {
540
+ "name": name,
541
+ "parentUiEci": parentUiEci
542
+ }
543
+ boxAttrs = attrs{"backgroundColor"}.match(re#^\#[0-9A-F]{6}$#i)
544
+ => childBoxAttrs.put("backgroundColor", attrs{"backgroundColor"})
545
+ | childBoxAttrs
546
+ every {
547
+ ctx:newPico(
548
+ rulesets=[
549
+ engine_ui_ruleset(),
550
+ { "url": ctx:rid_url, "config": {} }
551
+ ],
552
+ policyCeiling=policyCeiling
553
+ ) setting(newEci)
554
+ ctx:eventQuery(
555
+ eci=newEci,
556
+ domain="engine_ui",
557
+ name="setup",
558
+ rid=engine_ui_rid,
559
+ queryName="uiECI"
560
+ ) setting(newUiECI)
561
+ ctx:event(
562
+ eci=newEci,
563
+ domain="wrangler",
564
+ name="pico_created",
565
+ attrs=attrs
566
+ )
567
+ ctx:event(
568
+ eci=newUiECI,
569
+ domain="engine_ui",
570
+ name="box",
571
+ attrs=boxAttrs
572
+ )
573
+ }
574
+ return {"eci": newEci, "uiEci": newUiECI}
575
+ }
380
576
 
381
577
  }
382
578
 
@@ -400,6 +596,15 @@ ruleset io.picolabs.wrangler {
400
596
  // ********************************************************************************************
401
597
 
402
598
 
599
+ /**
600
+ * Install a ruleset that lives next to another one: the URL is built by
601
+ * replacing the last part of absoluteURL with <rid>.krl (pass meta:rulesetURI to
602
+ * install a sibling of the calling ruleset). Continues as an install by url.
603
+ * @attr absoluteURL String "URL of a ruleset in the same directory"
604
+ * @attr rid String "id of the ruleset to install"
605
+ * @attr config Map optional "configuration for the installed ruleset"
606
+ * @example "sibling of this ruleset" { "absoluteURL": "<meta:rulesetURI>", "rid": "<rid>" }
607
+ */
403
608
  rule install_ruleset_relatively {
404
609
  select when wrangler install_ruleset_request
405
610
  absoluteURL re#(.+)# // required
@@ -417,14 +622,28 @@ ruleset io.picolabs.wrangler {
417
622
  }
418
623
  }
419
624
 
625
+ /**
626
+ * Install (or reinstall) a ruleset from a URL on this pico. The URL is fetched
627
+ * and compiled first, so this also picks up a new version. Raises
628
+ * wrangler:ruleset_installed with the installed rid.
629
+ * @attr url String "URL of the .krl file"
630
+ * @attr config Map optional "configuration for the installed ruleset"
631
+ * @example "from a URL" { "url": "https://example.com/krl/<rid>.krl" }
632
+ * @example "with config" { "url": "https://example.com/krl/<rid>.krl", "config": { "<key>": "<value>" } }
633
+ */
420
634
  rule install_ruleset_absolutely {
421
635
  select when wrangler install_ruleset_request
422
636
  url re#(.+)# // required
423
637
  setting(url)
424
638
  pre {
425
639
  config = event:attr("config") || {}
640
+ validation = ctx:validate(url)
641
+ ok = validation{"ok"}
642
+ validate_errors = validation{"errors"}
643
+ validate_warnings = validation{"warnings"}
644
+ validate_rid = validation{"rid"}
426
645
  }
427
- every {
646
+ if ok then every {
428
647
  ctx:flush(url=url)
429
648
  ctx:install(url=url, config=config) setting(rid)
430
649
  }
@@ -432,8 +651,18 @@ ruleset io.picolabs.wrangler {
432
651
  raise wrangler event "ruleset_installed" attributes
433
652
  event:attrs.put({"rids": [rid]})
434
653
  }
654
+ else {
655
+ raise wrangler event "ruleset_install_failed" attributes
656
+ {"url": url, "rid": validate_rid, "errors": validate_errors, "warnings": validate_warnings}
657
+ }
435
658
  }
436
659
 
660
+ /**
661
+ * Uninstall a ruleset from this pico. Refused if another installed ruleset uses
662
+ * it as a module. Raises wrangler:ruleset_uninstalled.
663
+ * @attr rid String "ruleset id"
664
+ * @example "by rid" { "rid": "<rid>" }
665
+ */
437
666
  rule uninstall_one_ruleset {
438
667
  select when wrangler uninstall_ruleset_request
439
668
  rid re#(.+)# setting(rid)
@@ -443,6 +672,10 @@ ruleset io.picolabs.wrangler {
443
672
  }
444
673
  }
445
674
 
675
+ /**
676
+ * Re-fetch and recompile every ruleset installed on this pico, so each picks up
677
+ * its latest source. Raises wrangler:rulesets_flushed when done.
678
+ */
446
679
  rule flush_all_rulesets {
447
680
  select when wrangler rulesets_need_flushing
448
681
  foreach ctx:rulesets setting(rs)
@@ -456,6 +689,14 @@ ruleset io.picolabs.wrangler {
456
689
  // *** Channels ***
457
690
  // ********************************************************************************************
458
691
 
692
+ /**
693
+ * Create a channel on this pico. Raises wrangler:channel_created with the new
694
+ * channel (including its id).
695
+ * @attr tags Array "tags for the channel, e.g. [\"myapp\", \"webhook\"]"
696
+ * @attr eventPolicy Map "{ allow: [ { domain, name } ], deny: [ … ] }"
697
+ * @attr queryPolicy Map "{ allow: [ { rid, name } ], deny: [ … ] }"
698
+ * @example "webhook" { "tags": ["<app>", "webhook"], "eventPolicy": { "allow": [ { "domain": "<app>", "name": "*" } ], "deny": [] }, "queryPolicy": { "allow": [], "deny": [] } }
699
+ */
459
700
  rule createChannel {
460
701
  select when wrangler new_channel_request
461
702
  pre {
@@ -471,6 +712,10 @@ ruleset io.picolabs.wrangler {
471
712
  }
472
713
  }
473
714
 
715
+ /**
716
+ * Delete a channel on this pico. Raises wrangler:channel_deleted.
717
+ * @attr eci String "the channel to delete"
718
+ */
474
719
  rule deleteChannel {
475
720
  select when wrangler channel_deletion_request
476
721
  eci re#^(.+)$# // required
@@ -481,6 +726,14 @@ ruleset io.picolabs.wrangler {
481
726
  }
482
727
  }
483
728
 
729
+ /**
730
+ * Replace a channel's tags and policies. Raises wrangler:channel_updated with the
731
+ * updated channel.
732
+ * @attr eci String "the channel to update"
733
+ * @attr tags Array "new tags"
734
+ * @attr eventPolicy Map "new event policy"
735
+ * @attr queryPolicy Map "new query policy"
736
+ */
484
737
  rule updateChannel {
485
738
  select when wrangler channel_update_request
486
739
  pre {
@@ -502,57 +755,28 @@ ruleset io.picolabs.wrangler {
502
755
  // ********************************************************************************************
503
756
  //-------------------- Picos initializing ----------------------
504
757
 
758
+ /**
759
+ * Create a child pico with wrangler, PDS, and relationships installed. Raises
760
+ * wrangler:new_child_created here with the child's family-channel eci and uiEci.
761
+ * Other attrs are passed to the child, and come back to this pico in
762
+ * wrangler:child_initialized once the child is set up (Manifold uses this, e.g.
763
+ * event_name, to tell its creations apart).
764
+ * @attr name String "name for the child"
765
+ * @attr backgroundColor String optional "developer UI color, e.g. #87cefa"
766
+ * @attr policyCeiling Map optional "max channel policy for the child pico; must not exceed parent ceiling"
767
+ * @example "named" { "name": "<name>" }
768
+ * @example "with color" { "name": "<name>", "backgroundColor": "#ffb347" }
769
+ */
505
770
  rule createChild {
506
771
  select when wrangler new_child_request
507
772
  name re#.+# // required
508
773
  backgroundColor re#.*# // optional (layout rule assigns palette color)
509
- pre {
510
- name = event:attrs{"name"}
511
- engine_ui_rid = "io.picolabs.pico-engine-ui"
512
- engine_ui_ruleset = function(){
513
- the_ruleset = ctx:rulesets
514
- .filter(function(r){r.get("rid")==engine_ui_rid})
515
- .head();
516
- { "url":the_ruleset.get("url"),
517
- "config":the_ruleset.get("config")
518
- }
519
- }
520
- parentUiEci = ctx:channels
521
- .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
522
- .map(function(c){c["id"]})
523
- .head()
524
- }
525
774
  every {
526
- ctx:newPico(rulesets=[
527
- engine_ui_ruleset(),
528
- { "url": ctx:rid_url, "config": {} }
529
- ]) setting(newEci)
530
- ctx:eventQuery(
531
- eci=newEci,
532
- domain="engine_ui",
533
- name="setup",
534
- rid=engine_ui_rid,
535
- queryName="uiECI"
536
- ) setting(newUiECI)
537
- ctx:event(
538
- eci=newEci,
539
- domain="wrangler",
540
- name="pico_created",
541
- attrs=event:attrs
542
- )
543
- ctx:event(
544
- eci=newUiECI,
545
- domain="engine_ui",
546
- name="box",
547
- attrs={
548
- "name": name,
549
- "parentUiEci": parentUiEci
550
- }
551
- )
775
+ bootstrapNewChild(event:attrs{"name"}, event:attrs) setting(boot)
552
776
  }
553
777
  fired {
554
778
  raise wrangler event "new_child_created"
555
- attributes event:attrs.put({"eci":newEci, "uiEci": newUiECI})
779
+ attributes event:attrs.put(boot)
556
780
  }
557
781
  }
558
782
 
@@ -589,6 +813,15 @@ ruleset io.picolabs.wrangler {
589
813
  "domain": "wrangler", "type": "child_initialized",
590
814
  "attrs" : event:attrs })
591
815
  }
816
+
817
+ rule note_subtree_import {
818
+ select when wrangler pico_imported
819
+ fired {
820
+ ent:last_subtree_import := event:attrs
821
+ raise wrangler event "subtree_imported"
822
+ attributes event:attrs
823
+ }
824
+ }
592
825
 
593
826
  // this pico is the primary pico
594
827
 
@@ -602,6 +835,10 @@ ruleset io.picolabs.wrangler {
602
835
  }
603
836
  }
604
837
 
838
+ /**
839
+ * Change this pico's wrangler name (what name() and myself() return).
840
+ * @attr name String "new name"
841
+ */
605
842
  rule take_note_of_name_change {
606
843
  select when wrangler name_changed
607
844
  name re#(.+)# // required
@@ -612,6 +849,11 @@ ruleset io.picolabs.wrangler {
612
849
  }
613
850
 
614
851
  //-------------------- PARENT PERSPECTIVE ----------------------
852
+ /**
853
+ * Delete a child pico and all of its descendants. Raises wrangler:child_deleted.
854
+ * @attr eci String "the child's family-channel ECI (from children())"
855
+ * @example "by eci" { "eci": "<child family eci>" }
856
+ */
615
857
  rule deleteOneChild {
616
858
  select when wrangler child_deletion_request
617
859
  eci re#^(.+)$# setting(eci)
@@ -671,6 +913,20 @@ ruleset io.picolabs.wrangler {
671
913
  createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
672
914
  }
673
915
 
916
+ rule schema_updated_on_ruleset_set {
917
+ select when engine ruleset_set_changed
918
+ always {
919
+ raise wrangler event "schema_updated" attributes event:attrs
920
+ }
921
+ }
922
+
923
+ /**
924
+ * Turn on or off accepting unsolicited introduction messages (Layer 2
925
+ * relationship requests) on this pico's did:webvh. See publicIntro().
926
+ * @attr enabled Boolean "true to accept introductions"
927
+ * @example "accept" { "enabled": true }
928
+ * @example "refuse" { "enabled": false }
929
+ */
674
930
  rule wrangler_set_public_intro {
675
931
  select when wrangler set_public_intro
676
932
  setPublicIntro(event:attr("enabled"))