pico-engine 1.9.5 → 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.
- package/README.md +11 -5
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
- package/demos/echo/com.example.echo.bootstrap.krl +10 -7
- package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
- package/demos/json_query/README.md +11 -0
- package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
- package/demos/json_query/com.example.json_query.krl +162 -0
- package/demos/json_query/try-it.md +5 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
- package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
- package/demos/try-it-order.json +1 -1
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
- package/dist/cli.js +5 -1
- package/dist/engineConfig.js +1 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +44 -12
- package/dist/internalAccess.js +110 -0
- package/dist/oauth/OAuthService.js +172 -10
- package/dist/oauth/acg.js +194 -24
- package/dist/oauth/cimd.js +381 -0
- package/dist/oauth/discovery.js +175 -0
- package/dist/runMcp.js +1 -1
- package/dist/server.js +197 -48
- package/dist/subtreeWrangler.js +8 -5
- package/dist/uiChannelPolicies.js +2 -0
- package/krl/io.picolabs.pds.krl +109 -21
- package/krl/io.picolabs.pico-engine-ui.krl +13 -7
- package/krl/io.picolabs.wrangler.krl +21 -9
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +3 -2
- package/mcp/docs/cookbook/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
- package/mcp/docs/cookbook/child_tasks/README.md +20 -0
- package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
- package/mcp/docs/cookbook/collection/README.md +21 -0
- package/mcp/docs/cookbook/collection/instructions.md +93 -0
- package/mcp/docs/cookbook/echo/README.md +19 -0
- package/mcp/docs/cookbook/echo/instructions.md +59 -0
- package/mcp/docs/cookbook/guard_rules/README.md +22 -0
- package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
- package/mcp/docs/cookbook/json_query/README.md +26 -0
- package/mcp/docs/cookbook/json_query/instructions.md +64 -0
- package/mcp/docs/cookbook/kblog/README.md +60 -0
- package/mcp/docs/cookbook/kblog/instructions.md +102 -0
- package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
- package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
- package/mcp/docs/cookbook/moving_picos/README.md +44 -0
- package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
- package/mcp/docs/cookbook/score_tracker/README.md +19 -0
- package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
- package/mcp/docs/cookbook/secrets/README.md +25 -0
- package/mcp/docs/cookbook/secrets/instructions.md +98 -0
- package/mcp/docs/cookbook/two_picos/README.md +20 -0
- package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
- package/mcp/docs/cookbook/xmlui/README.md +23 -0
- package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
- package/mcp/docs/developing/README.md +28 -0
- package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
- package/mcp/docs/developing/arrays-and-maps.md +77 -0
- package/mcp/docs/developing/converting-time-formats.md +28 -0
- package/mcp/docs/developing/cookies-and-redirects.md +81 -0
- package/mcp/docs/developing/decoding-form-data.md +67 -0
- package/mcp/docs/developing/engine-log-files.md +34 -0
- package/mcp/docs/developing/event-loop.md +77 -0
- package/mcp/docs/developing/events-from-email.md +80 -0
- package/mcp/docs/developing/initializing-entity-variables.md +83 -0
- package/mcp/docs/developing/mcp-ai-tools.md +98 -0
- package/mcp/docs/developing/misconceptions.md +467 -0
- package/mcp/docs/developing/names-and-scope.md +44 -0
- package/mcp/docs/developing/postman.md +159 -0
- package/mcp/docs/developing/querying-another-pico.md +47 -0
- package/mcp/docs/developing/singleton-picos.md +36 -0
- package/mcp/docs/developing/tabular-data.md +67 -0
- package/mcp/docs/developing/tips.md +251 -0
- package/mcp/docs/developing/webhook-signatures.md +56 -0
- package/mcp/docs/developing/workflow.md +106 -0
- package/mcp/docs/exp/README.md +46 -0
- package/mcp/docs/exp/event.md +110 -0
- package/mcp/docs/exp/query.md +94 -0
- package/mcp/docs/lessons/README.md +59 -0
- package/mcp/docs/lessons/events-and-queries.md +247 -0
- package/mcp/docs/lessons/gossip.md +28 -0
- package/mcp/docs/lessons/modules-and-apis.md +270 -0
- package/mcp/docs/lessons/pico-based-systems.md +470 -0
- package/mcp/docs/lessons/pico-state.md +267 -0
- package/mcp/docs/lessons/pico-views.md +290 -0
- package/mcp/docs/lessons/quickstart.md +157 -0
- package/mcp/docs/lessons/relationships.md +530 -0
- package/mcp/docs/lessons/scatter-gather.md +362 -0
- package/mcp/docs/pico-engine.md +7 -5
- package/mcp/docs/pico-overview.md +3 -3
- package/mcp/docs/wrangler/README.md +47 -0
- package/mcp/docs/wrangler/channels.md +235 -0
- package/mcp/docs/wrangler/oauth.md +56 -0
- package/mcp/docs/wrangler/pds.md +423 -0
- package/mcp/docs/wrangler/portable-subtree.md +44 -0
- package/mcp/docs/wrangler/relationships.md +297 -0
- package/mcp/docs/wrangler/wrangler.md +253 -0
- package/mcp/docs/wrangler/xmlui.md +60 -0
- package/mcp/engineClient.js +57 -5
- package/mcp/mcpScopes.js +118 -0
- package/mcp/meshHttp.js +151 -45
- package/mcp/runStdio.js +2 -0
- package/mcp/subtreeTools.js +184 -0
- package/mcp/tryItTools.js +202 -0
- package/package.json +14 -8
- package/public/pico-engine-ui.js +26 -26
- package/src/cli.ts +6 -2
- package/src/engineConfig.ts +5 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -430
- package/src/internalAccess.ts +127 -0
- package/src/oauth/OAuthService.ts +243 -11
- package/src/oauth/acg.ts +289 -25
- package/src/oauth/cimd.ts +508 -0
- package/src/oauth/discovery.ts +233 -0
- package/src/runMcp.ts +3 -1
- package/src/server.ts +252 -52
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
package/krl/io.picolabs.pds.krl
CHANGED
|
@@ -17,8 +17,7 @@ ruleset io.picolabs.pds {
|
|
|
17
17
|
|
|
18
18
|
shares items, get_keys,
|
|
19
19
|
profile,
|
|
20
|
-
settings, get_config_value, get_setting_data_value, config_value, settings_names
|
|
21
|
-
getChannelEci
|
|
20
|
+
settings, get_config_value, get_setting_data_value, config_value, settings_names
|
|
22
21
|
|
|
23
22
|
}
|
|
24
23
|
|
|
@@ -49,7 +48,8 @@ ruleset io.picolabs.pds {
|
|
|
49
48
|
// "name": "<display name>",
|
|
50
49
|
// "rid": "<rulesetRID>",
|
|
51
50
|
// "data": { "<configKey>": <value>, ... },
|
|
52
|
-
// "schema": []
|
|
51
|
+
// "schema": [],
|
|
52
|
+
// "secret": ["<configKey>", ...] // those data values are masked in settings
|
|
53
53
|
// }
|
|
54
54
|
// Path: ent:settings{[rulesetRID, "data", configKey]} for config_value()
|
|
55
55
|
//
|
|
@@ -132,12 +132,39 @@ ruleset io.picolabs.pds {
|
|
|
132
132
|
})
|
|
133
133
|
};
|
|
134
134
|
|
|
135
|
+
is_secret_key = function(rid, key) {
|
|
136
|
+
listed = ent:settings{[rid, "secret"]} || [];
|
|
137
|
+
listed >< key
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
mask_secret = function(value) {
|
|
141
|
+
{ "secret": true, "set": not value.isnull() }
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
// Present secret values become the mask. Secret keys with no value are
|
|
145
|
+
// reported as set: false.
|
|
146
|
+
mask_data = function(rid, data) {
|
|
147
|
+
values = data || {};
|
|
148
|
+
secrets = ent:settings{[rid, "secret"]} || [];
|
|
149
|
+
masked = values.map(function(v, k) {
|
|
150
|
+
secrets >< k => mask_secret(v) | v
|
|
151
|
+
});
|
|
152
|
+
secrets.reduce(function(acc, key) {
|
|
153
|
+
values{key}.isnull() => acc.put([key], mask_secret(null)) | acc
|
|
154
|
+
}, masked)
|
|
155
|
+
};
|
|
156
|
+
|
|
157
|
+
mask_record = function(rid, record) {
|
|
158
|
+
record.isnull() => record | record.put(["data"], mask_data(rid, record{"data"}))
|
|
159
|
+
};
|
|
160
|
+
|
|
135
161
|
/**
|
|
136
162
|
* Read per-ruleset settings. No arguments: all settings. Rid: that ruleset's
|
|
137
|
-
* settings record ({ name, rid, data, schema }). Rid and Key: one field of the
|
|
163
|
+
* settings record ({ name, rid, data, schema, secret }). Rid and Key: one field of the
|
|
138
164
|
* record. Rid, Key, and detail: the value of data key `detail` (Key is ignored).
|
|
165
|
+
* A key listed in `secret` is returned as { secret: true, set }, never the value.
|
|
139
166
|
* @param Rid String "ruleset id whose settings to read"
|
|
140
|
-
* @param Key String "field of the settings record (name, rid, data, schema)"
|
|
167
|
+
* @param Key String "field of the settings record (name, rid, data, schema, secret)"
|
|
141
168
|
* @param detail String "key within the record's data map"
|
|
142
169
|
* @returns Map "{ status, settings }"
|
|
143
170
|
* @example "one ruleset" { "Rid": "<rid>" }
|
|
@@ -145,16 +172,19 @@ ruleset io.picolabs.pds {
|
|
|
145
172
|
*/
|
|
146
173
|
settings = function(Rid = null, Key = null, detail = null){
|
|
147
174
|
get_setting_all = function() {
|
|
148
|
-
ent:settings
|
|
175
|
+
ent:settings.isnull() => ent:settings |
|
|
176
|
+
ent:settings.map(function(record, rid) { mask_record(rid, record) })
|
|
149
177
|
};
|
|
150
178
|
get_setting = function(rid) {
|
|
151
|
-
ent:settings{rid}
|
|
179
|
+
mask_record(rid, ent:settings{rid})
|
|
152
180
|
};
|
|
153
181
|
get_setting_value = function(rid, varible) {
|
|
182
|
+
varible == "data" => mask_data(rid, ent:settings{[rid, "data"]}) |
|
|
154
183
|
ent:settings{[rid, varible]}
|
|
155
184
|
};
|
|
156
185
|
get_data_value = function(rid, dataKey) {
|
|
157
|
-
ent:settings{[rid, "data", dataKey]}
|
|
186
|
+
raw = ent:settings{[rid, "data", dataKey]};
|
|
187
|
+
is_secret_key(rid, dataKey) => mask_secret(raw) | raw
|
|
158
188
|
};
|
|
159
189
|
pick = function() {
|
|
160
190
|
Rid.isnull() => get_setting_all()
|
|
@@ -181,13 +211,15 @@ ruleset io.picolabs.pds {
|
|
|
181
211
|
};
|
|
182
212
|
|
|
183
213
|
/**
|
|
184
|
-
* One configuration value from a ruleset's settings data.
|
|
214
|
+
* One configuration value from a ruleset's settings data. A secret key is
|
|
215
|
+
* returned as { secret: true, set }, never the value.
|
|
185
216
|
* @param setRID String "ruleset id"
|
|
186
217
|
* @param setKey String "data key"
|
|
187
218
|
* @returns Any
|
|
188
219
|
*/
|
|
189
220
|
get_setting_data_value = function(setRID, setKey) {
|
|
190
|
-
setting_data_value(setRID, setKey)
|
|
221
|
+
raw = setting_data_value(setRID, setKey);
|
|
222
|
+
is_secret_key(setRID, setKey) => mask_secret(raw) | raw
|
|
191
223
|
}
|
|
192
224
|
|
|
193
225
|
/**
|
|
@@ -213,14 +245,36 @@ ruleset io.picolabs.pds {
|
|
|
213
245
|
}
|
|
214
246
|
|
|
215
247
|
/**
|
|
216
|
-
* The ECI of this pico's pds channel
|
|
217
|
-
*
|
|
248
|
+
* The ECI of this pico's pds channel. Provided to rulesets on this pico.
|
|
249
|
+
* Not a shared query: a channel that can read settings must not receive an
|
|
250
|
+
* ECI that can rewrite them.
|
|
218
251
|
* @returns String
|
|
219
252
|
*/
|
|
220
253
|
getChannelEci = function() {
|
|
221
254
|
ent:pds_channel_eci
|
|
222
255
|
}
|
|
223
256
|
|
|
257
|
+
keys_from_secret_attr = function(secret, data_key) {
|
|
258
|
+
secret == true && data_key.typeof() == "String" => [data_key] |
|
|
259
|
+
secret.typeof() == "Array" => secret.filter(function(k) { k.typeof() == "String" }) |
|
|
260
|
+
[]
|
|
261
|
+
};
|
|
262
|
+
|
|
263
|
+
keys_from_schema = function(schema) {
|
|
264
|
+
schema.typeof() == "Array" => schema.filter(function(entry) {
|
|
265
|
+
entry.typeof() == "Map" && entry{"secret"}
|
|
266
|
+
}).map(function(entry) {
|
|
267
|
+
entry{"key"} || entry{"name"}
|
|
268
|
+
}).filter(function(k) { k.typeof() == "String" }) |
|
|
269
|
+
[]
|
|
270
|
+
};
|
|
271
|
+
|
|
272
|
+
merge_secret_keys = function(already, more) {
|
|
273
|
+
more.reduce(function(acc, key) {
|
|
274
|
+
acc >< key => acc | acc.append(key)
|
|
275
|
+
}, already || [])
|
|
276
|
+
};
|
|
277
|
+
|
|
224
278
|
defaultProfile = {
|
|
225
279
|
"name": "",
|
|
226
280
|
"description": "",
|
|
@@ -389,14 +443,18 @@ ruleset io.picolabs.pds {
|
|
|
389
443
|
|
|
390
444
|
/**
|
|
391
445
|
* Create or update a ruleset's settings record, and optionally set one data
|
|
392
|
-
* value in it. Raises pds:settings_added.
|
|
446
|
+
* value in it. Raises pds:settings_added. A key named in `secret`, or a schema
|
|
447
|
+
* entry with secret true, is stored as a secret: settings queries return
|
|
448
|
+
* { secret: true, set } and the raised event does not carry the value.
|
|
393
449
|
* @attr keyed_rid String "ruleset id the settings belong to"
|
|
394
450
|
* @attr name String "display name for the settings"
|
|
395
451
|
* @attr schema Array optional "settings schema, stored as given"
|
|
396
452
|
* @attr data_key String optional "data key to set"
|
|
397
453
|
* @attr value Any optional "value for data_key"
|
|
454
|
+
* @attr secret Array|Boolean optional "key names to mark secret, or true to mark data_key"
|
|
398
455
|
* @example "register settings" { "keyed_rid": "<rid>", "name": "<display name>" }
|
|
399
456
|
* @example "set one value" { "keyed_rid": "<rid>", "name": "<display name>", "data_key": "<key>", "value": "<value>" }
|
|
457
|
+
* @example "secret" { "keyed_rid": "<rid>", "name": "<display name>", "data_key": "apiKey", "value": "<secret>", "secret": true }
|
|
400
458
|
*/
|
|
401
459
|
rule settings_added {
|
|
402
460
|
select when pds add_settings
|
|
@@ -406,35 +464,65 @@ ruleset io.picolabs.pds {
|
|
|
406
464
|
set_schema = event:attr("schema").defaultsTo(0, "no Schema");
|
|
407
465
|
set_attr = event:attr("data_key").defaultsTo(0, "no setAttr");
|
|
408
466
|
set_value = event:attr("value").defaultsTo(0, "no Value");
|
|
409
|
-
|
|
467
|
+
already = ent:settings{[set_rid, "secret"]} || [];
|
|
468
|
+
next_secret = merge_secret_keys(
|
|
469
|
+
merge_secret_keys(already, keys_from_secret_attr(event:attr("secret"), event:attr("data_key"))),
|
|
470
|
+
keys_from_schema(set_schema)
|
|
471
|
+
);
|
|
472
|
+
hiding = set_attr.typeof() == "String" && (next_secret >< set_attr);
|
|
473
|
+
announced = hiding => event:attrs.put(["value"], mask_secret(set_value)) | event:attrs;
|
|
410
474
|
}
|
|
411
475
|
noop()
|
|
412
476
|
always {
|
|
413
477
|
ent:settings{[set_rid, "name"]} := set_name;
|
|
414
478
|
ent:settings{[set_rid, "rid"]} := set_rid;
|
|
415
479
|
ent:settings{[set_rid, "schema"]} := set_schema if set_schema;
|
|
480
|
+
ent:settings{[set_rid, "secret"]} := next_secret if next_secret.length() > 0;
|
|
416
481
|
ent:settings{[set_rid, "data", set_attr]} := set_value if set_attr;
|
|
417
|
-
raise pds event "settings_added" attributes
|
|
482
|
+
raise pds event "settings_added" attributes announced;
|
|
418
483
|
}
|
|
419
484
|
}
|
|
420
485
|
|
|
486
|
+
// On install, and on the root pico at engine start: a pico whose PDS came
|
|
487
|
+
// with an older engine may have no pds channel yet.
|
|
421
488
|
rule create_pds_channel {
|
|
422
489
|
select when wrangler ruleset_installed where event:attr("rids") >< ctx:rid
|
|
490
|
+
or engine started
|
|
423
491
|
pre {
|
|
424
492
|
channelName = "pds"
|
|
425
|
-
eventPolicy = {"allow": [{"domain": "pds", "name": "*"}], "deny": []}
|
|
493
|
+
eventPolicy = {"allow": [{"domain": "pds", "name": "*"}], "deny": [{"domain": "pds", "name": "clear_all_data"}]}
|
|
426
494
|
queryPolicy = {"allow": [{"rid": "io.picolabs.pds", "name": "*"}], "deny": []}
|
|
427
|
-
|
|
428
|
-
pds_channel = existing_channels.filter(function(chan) {
|
|
429
|
-
chan{"name"} == channelName
|
|
430
|
-
})
|
|
495
|
+
pds_channel = wrangler:channels([channelName])
|
|
431
496
|
channel_exists = pds_channel.length() > 0
|
|
432
497
|
}
|
|
433
498
|
if not channel_exists then
|
|
434
499
|
wrangler:createChannel([channelName], eventPolicy, queryPolicy) setting(channel)
|
|
435
500
|
fired {
|
|
436
|
-
ent:pds_channel_eci :=
|
|
501
|
+
ent:pds_channel_eci := channel{"id"}
|
|
502
|
+
}
|
|
503
|
+
else {
|
|
504
|
+
ent:pds_channel_eci := pds_channel.head(){"id"}
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
// A channel created by an older engine allowed clear_all_data. Deny that
|
|
509
|
+
// event on the pds channel. A ruleset on this pico can still raise it.
|
|
510
|
+
rule narrow_pds_channel {
|
|
511
|
+
select when wrangler ruleset_installed where event:attr("rids") >< ctx:rid
|
|
512
|
+
or engine started
|
|
513
|
+
pre {
|
|
514
|
+
found = wrangler:channels(["pds"]).head()
|
|
515
|
+
denied = found.isnull() => [] | found{"eventPolicy"}{"deny"}.defaultsTo([])
|
|
516
|
+
already = denied.filter(function(rule) { rule{"name"} == "clear_all_data" })
|
|
517
|
+
open = found && already.length() == 0
|
|
437
518
|
}
|
|
519
|
+
if open then
|
|
520
|
+
wrangler:updateChannel(
|
|
521
|
+
found{"id"},
|
|
522
|
+
["pds"],
|
|
523
|
+
{"allow": [{"domain": "pds", "name": "*"}], "deny": [{"domain": "pds", "name": "clear_all_data"}]},
|
|
524
|
+
{"allow": [{"rid": "io.picolabs.pds", "name": "*"}], "deny": []}
|
|
525
|
+
)
|
|
438
526
|
}
|
|
439
527
|
|
|
440
528
|
rule seed_profile_name {
|
|
@@ -143,7 +143,8 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
143
143
|
{ "domain": "wrangler", "name": "new_child_request" },
|
|
144
144
|
{ "domain": "wrangler", "name": "new_child_created" },
|
|
145
145
|
{ "domain": "wrangler", "name": "install_ruleset_request" },
|
|
146
|
-
{ "domain": "wrangler", "name": "new_channel_request" }
|
|
146
|
+
{ "domain": "wrangler", "name": "new_channel_request" },
|
|
147
|
+
{ "domain": "pds", "name": "add_settings" }
|
|
147
148
|
],
|
|
148
149
|
"deny": []
|
|
149
150
|
}
|
|
@@ -168,7 +169,8 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
168
169
|
{ "rid": "io.picolabs.wrangler", "name": "myDid" },
|
|
169
170
|
{ "rid": "io.picolabs.wrangler", "name": "publicIntro" },
|
|
170
171
|
{ "rid": "io.picolabs.wrangler", "name": "rulesetSchema" },
|
|
171
|
-
{ "rid": "io.picolabs.wrangler", "name": "picoSchema" }
|
|
172
|
+
{ "rid": "io.picolabs.wrangler", "name": "picoSchema" },
|
|
173
|
+
{ "rid": "io.picolabs.pds", "name": "settings" }
|
|
172
174
|
],
|
|
173
175
|
"deny": []
|
|
174
176
|
}
|
|
@@ -259,7 +261,7 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
259
261
|
gridRow = (childIndex - childIndex % 4) / 4
|
|
260
262
|
layoutX = ent:x.defaultsTo(100) + 48 + gridCol * 143
|
|
261
263
|
layoutY = ent:y.defaultsTo(100) + 48 + gridRow * 108
|
|
262
|
-
childBox = ctx:query(uiEci, ctx:rid, "box")
|
|
264
|
+
childBox = uiEci => ctx:query(uiEci, ctx:rid, "box") | {}
|
|
263
265
|
layoutColor = childBox{"backgroundColor"}
|
|
264
266
|
.defaultsTo(childPalette[childIndex % childPalette.length])
|
|
265
267
|
}
|
|
@@ -282,7 +284,7 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
282
284
|
select when engine started
|
|
283
285
|
foreach ctx:children setting(familyEci)
|
|
284
286
|
if ent:child_ui_ecis{familyEci}.isnull() then noop()
|
|
285
|
-
|
|
287
|
+
fired {
|
|
286
288
|
ent:child_ui_ecis{[familyEci]} := ctx:query(familyEci, ctx:rid, "uiECI")
|
|
287
289
|
}
|
|
288
290
|
}
|
|
@@ -304,7 +306,7 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
304
306
|
rule backfill_parent_ui_eci {
|
|
305
307
|
select when engine started
|
|
306
308
|
if ctx:parent && ent:parent_ui_eci.isnull() then noop()
|
|
307
|
-
|
|
309
|
+
fired {
|
|
308
310
|
ent:parent_ui_eci := ctx:query(ctx:parent, ctx:rid, "uiECI")
|
|
309
311
|
}
|
|
310
312
|
}
|
|
@@ -409,7 +411,9 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
409
411
|
tags=event:attrs{"tags"},
|
|
410
412
|
eventPolicy=event:attrs{"eventPolicy"},
|
|
411
413
|
queryPolicy=event:attrs{"queryPolicy"},
|
|
412
|
-
id=event:attrs{"id"}
|
|
414
|
+
id=event:attrs{"id"},
|
|
415
|
+
mcpPolicy=event:attrs{"mcpPolicy"},
|
|
416
|
+
rawBody=event:attrs{"rawBody"}
|
|
413
417
|
)
|
|
414
418
|
}
|
|
415
419
|
rule del_channel {
|
|
@@ -422,7 +426,9 @@ ruleset io.picolabs.pico-engine-ui {
|
|
|
422
426
|
eci=event:attrs{"eci"},
|
|
423
427
|
tags=event:attrs{"tags"},
|
|
424
428
|
eventPolicy=event:attrs{"eventPolicy"},
|
|
425
|
-
queryPolicy=event:attrs{"queryPolicy"}
|
|
429
|
+
queryPolicy=event:attrs{"queryPolicy"},
|
|
430
|
+
mcpPolicy=event:attrs{"mcpPolicy"},
|
|
431
|
+
rawBody=event:attrs{"rawBody"}
|
|
426
432
|
)
|
|
427
433
|
}
|
|
428
434
|
rule testing_eci {
|
|
@@ -40,9 +40,9 @@ ruleset io.picolabs.wrangler {
|
|
|
40
40
|
{ "domain": "wrangler", "name": "child_deletion_request",
|
|
41
41
|
"attrs": [ "eci"] },
|
|
42
42
|
{ "domain": "wrangler", "name": "new_channel_request",
|
|
43
|
-
"attrs": [ "tags", "eventPolicy", "queryPolicy" ] },
|
|
43
|
+
"attrs": [ "tags", "eventPolicy", "queryPolicy", "mcpPolicy", "rawBody" ] },
|
|
44
44
|
{ "domain": "wrangler", "name": "channel_update_request",
|
|
45
|
-
"attrs": [ "eci", "tags", "eventPolicy", "queryPolicy" ] },
|
|
45
|
+
"attrs": [ "eci", "tags", "eventPolicy", "queryPolicy", "mcpPolicy", "rawBody" ] },
|
|
46
46
|
{ "domain": "wrangler", "name": "channel_deletion_request",
|
|
47
47
|
"attrs": [ "eci" ] },
|
|
48
48
|
{ "domain": "wrangler", "name": "install_ruleset_request",
|
|
@@ -299,21 +299,25 @@ ruleset io.picolabs.wrangler {
|
|
|
299
299
|
ctx:delChannel(eci)
|
|
300
300
|
}
|
|
301
301
|
|
|
302
|
-
createChannel = defaction(tags,eventPolicy,queryPolicy){
|
|
302
|
+
createChannel = defaction(tags,eventPolicy,queryPolicy,mcpPolicy,rawBody){
|
|
303
303
|
ctx:newChannel(
|
|
304
304
|
tags=tags,
|
|
305
305
|
eventPolicy=eventPolicy,
|
|
306
|
-
queryPolicy=queryPolicy
|
|
306
|
+
queryPolicy=queryPolicy,
|
|
307
|
+
mcpPolicy=mcpPolicy,
|
|
308
|
+
rawBody=rawBody
|
|
307
309
|
) setting(channel)
|
|
308
310
|
return channel
|
|
309
311
|
}
|
|
310
312
|
|
|
311
|
-
updateChannel = defaction(eci, tags, eventPolicy, queryPolicy) {
|
|
313
|
+
updateChannel = defaction(eci, tags, eventPolicy, queryPolicy, mcpPolicy, rawBody) {
|
|
312
314
|
ctx:putChannel(
|
|
313
315
|
eci=eci,
|
|
314
316
|
tags=tags,
|
|
315
317
|
eventPolicy=eventPolicy,
|
|
316
|
-
queryPolicy=queryPolicy
|
|
318
|
+
queryPolicy=queryPolicy,
|
|
319
|
+
mcpPolicy=mcpPolicy,
|
|
320
|
+
rawBody=rawBody
|
|
317
321
|
) setting(channel)
|
|
318
322
|
return channel
|
|
319
323
|
}
|
|
@@ -701,7 +705,9 @@ ruleset io.picolabs.wrangler {
|
|
|
701
705
|
* @attr tags Array "tags for the channel, e.g. [\"myapp\", \"webhook\"]"
|
|
702
706
|
* @attr eventPolicy Map "{ allow: [ { domain, name } ], deny: [ … ] }"
|
|
703
707
|
* @attr queryPolicy Map "{ allow: [ { rid, name } ], deny: [ … ] }"
|
|
704
|
-
* @
|
|
708
|
+
* @attr mcpPolicy Map "optional { allow: [ { surface } ], deny: [ … ] }. surface is channel, mesh, or *. Absent denies MCP."
|
|
709
|
+
* @attr rawBody Boolean "optional. true keeps the raw HTTP body for event:raw_body(). Absent does not."
|
|
710
|
+
* @example "webhook" { "tags": ["<app>", "webhook"], "eventPolicy": { "allow": [ { "domain": "<app>", "name": "*" } ], "deny": [] }, "queryPolicy": { "allow": [], "deny": [] }, "rawBody": true }
|
|
705
711
|
*/
|
|
706
712
|
rule createChannel {
|
|
707
713
|
select when wrangler new_channel_request
|
|
@@ -709,9 +715,11 @@ ruleset io.picolabs.wrangler {
|
|
|
709
715
|
tags = event:attrs{"tags"}
|
|
710
716
|
eventPolicy = event:attrs{"eventPolicy"}
|
|
711
717
|
queryPolicy = event:attrs{"queryPolicy"}
|
|
718
|
+
mcpPolicy = event:attrs{"mcpPolicy"}
|
|
719
|
+
rawBody = event:attrs{"rawBody"}
|
|
712
720
|
}
|
|
713
721
|
if tags && eventPolicy && queryPolicy then
|
|
714
|
-
createChannel(tags,eventPolicy,queryPolicy) setting(channel)
|
|
722
|
+
createChannel(tags,eventPolicy,queryPolicy,mcpPolicy,rawBody) setting(channel)
|
|
715
723
|
fired {
|
|
716
724
|
raise wrangler event "channel_created"
|
|
717
725
|
attributes event:attrs.put({"channel":channel})
|
|
@@ -739,6 +747,8 @@ ruleset io.picolabs.wrangler {
|
|
|
739
747
|
* @attr tags Array "new tags"
|
|
740
748
|
* @attr eventPolicy Map "new event policy"
|
|
741
749
|
* @attr queryPolicy Map "new query policy"
|
|
750
|
+
* @attr mcpPolicy Map "optional { allow: [ { surface } ], deny: [ … ] }. Omit to leave MCP exposure unchanged."
|
|
751
|
+
* @attr rawBody Boolean "optional. true or false. Omit to leave the raw-body setting unchanged."
|
|
742
752
|
*/
|
|
743
753
|
rule updateChannel {
|
|
744
754
|
select when wrangler channel_update_request
|
|
@@ -747,9 +757,11 @@ ruleset io.picolabs.wrangler {
|
|
|
747
757
|
tags = event:attrs{"tags"}
|
|
748
758
|
eventPolicy = event:attrs{"eventPolicy"}
|
|
749
759
|
queryPolicy = event:attrs{"queryPolicy"}
|
|
760
|
+
mcpPolicy = event:attrs{"mcpPolicy"}
|
|
761
|
+
rawBody = event:attrs{"rawBody"}
|
|
750
762
|
}
|
|
751
763
|
if eci && tags && eventPolicy && queryPolicy then
|
|
752
|
-
updateChannel(eci, tags, eventPolicy, queryPolicy) setting(channel)
|
|
764
|
+
updateChannel(eci, tags, eventPolicy, queryPolicy, mcpPolicy, rawBody) setting(channel)
|
|
753
765
|
fired {
|
|
754
766
|
raise wrangler event "channel_updated"
|
|
755
767
|
attributes event:attrs.put({"channel": channel})
|
package/mcp/devResources.js
CHANGED
|
@@ -19,11 +19,63 @@ function readFile(filePath) {
|
|
|
19
19
|
function readDoc(relativeFromRepoRoot) {
|
|
20
20
|
return (
|
|
21
21
|
readFile(path.join(repoRoot, relativeFromRepoRoot)) ||
|
|
22
|
+
readFile(path.join(bundledDir, relativeFromRepoRoot.replace(/^docs\//, ""))) ||
|
|
22
23
|
readFile(path.join(bundledDir, path.basename(relativeFromRepoRoot)))
|
|
23
24
|
);
|
|
24
25
|
}
|
|
25
26
|
|
|
27
|
+
/** Markdown pages under docs/<dir>, as paths relative to it ("echo/README.md"). */
|
|
28
|
+
function listPages(dir) {
|
|
29
|
+
const root = fs.existsSync(path.join(repoRoot, "docs", dir))
|
|
30
|
+
? path.join(repoRoot, "docs", dir)
|
|
31
|
+
: path.join(bundledDir, dir);
|
|
32
|
+
const out = [];
|
|
33
|
+
const walk = (sub) => {
|
|
34
|
+
let entries = [];
|
|
35
|
+
try {
|
|
36
|
+
entries = fs.readdirSync(path.join(root, sub), { withFileTypes: true });
|
|
37
|
+
} catch (_e) {
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
for (const entry of entries) {
|
|
41
|
+
const rel = sub ? `${sub}/${entry.name}` : entry.name;
|
|
42
|
+
if (entry.isDirectory()) walk(rel);
|
|
43
|
+
else if (entry.name.endsWith(".md")) out.push(rel);
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
walk("");
|
|
47
|
+
return out.sort();
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function firstHeading(text, fallback) {
|
|
51
|
+
const m = /^# (.+)$/m.exec(text);
|
|
52
|
+
return m ? m[1].trim() : fallback;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// Every page of the cookbook (demo overviews and instructions) and of Patterns
|
|
56
|
+
// and tips, at pico://docs/<dir>/<page without .md>.
|
|
57
|
+
function registerDocPages(server, dir, label) {
|
|
58
|
+
for (const rel of listPages(dir)) {
|
|
59
|
+
const page = rel.replace(/\.md$/, "");
|
|
60
|
+
const uri = `pico://docs/${dir}/${page}`;
|
|
61
|
+
const docPath = `docs/${dir}/${rel}`;
|
|
62
|
+
const title = firstHeading(readDoc(docPath), page);
|
|
63
|
+
server.resource(
|
|
64
|
+
`${dir}/${page}`,
|
|
65
|
+
uri,
|
|
66
|
+
{ description: `${label}: ${title}`, mimeType: "text/markdown" },
|
|
67
|
+
async () => ({
|
|
68
|
+
contents: [{ uri, mimeType: "text/markdown", text: readDoc(docPath) }],
|
|
69
|
+
})
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
26
74
|
function registerDevResources(server, client) {
|
|
75
|
+
registerDocPages(server, "cookbook", "Cookbook");
|
|
76
|
+
registerDocPages(server, "developing", "Developing with Picos");
|
|
77
|
+
registerDocPages(server, "wrangler", "Wrangler");
|
|
78
|
+
|
|
27
79
|
server.resource(
|
|
28
80
|
"krl-conventions",
|
|
29
81
|
"pico://docs/krl-conventions",
|
package/mcp/devTools.js
CHANGED
|
@@ -13,6 +13,35 @@ function textResult(text, isError = false) {
|
|
|
13
13
|
|
|
14
14
|
const emptySchema = {};
|
|
15
15
|
|
|
16
|
+
/** The attrs of a wrangler:<name> event anywhere in an event-wait body, or null. */
|
|
17
|
+
function findWranglerEvent(node, name) {
|
|
18
|
+
if (!node || typeof node !== "object") return null;
|
|
19
|
+
if (node.domain === "wrangler" && node.name === name) {
|
|
20
|
+
return (node.data && node.data.attrs) || {};
|
|
21
|
+
}
|
|
22
|
+
for (const value of Object.values(node)) {
|
|
23
|
+
const hit = findWranglerEvent(value, name);
|
|
24
|
+
if (hit) return hit;
|
|
25
|
+
}
|
|
26
|
+
return null;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* An event-wait body as a tool result. The engine answers some failures with
|
|
31
|
+
* HTTP 200 and an error in the body (a channel policy refusal), and install or
|
|
32
|
+
* flush failures as a raised wrangler event; both are reported as errors.
|
|
33
|
+
*/
|
|
34
|
+
function eventResult(data, failureEvent) {
|
|
35
|
+
if (data && typeof data === "object" && data.error != null) {
|
|
36
|
+
return textResult(jsonText(data), true);
|
|
37
|
+
}
|
|
38
|
+
const failed = failureEvent ? findWranglerEvent(data, failureEvent) : null;
|
|
39
|
+
if (failed) {
|
|
40
|
+
return textResult(jsonText({ error: `wrangler:${failureEvent}`, details: failed, response: data }), true);
|
|
41
|
+
}
|
|
42
|
+
return textResult(jsonText(data));
|
|
43
|
+
}
|
|
44
|
+
|
|
16
45
|
function registerDevTools(server, client) {
|
|
17
46
|
server.tool(
|
|
18
47
|
"engine_status",
|
|
@@ -111,7 +140,7 @@ function registerDevTools(server, client) {
|
|
|
111
140
|
name,
|
|
112
141
|
attrs || {}
|
|
113
142
|
);
|
|
114
|
-
return
|
|
143
|
+
return eventResult(data);
|
|
115
144
|
} catch (err) {
|
|
116
145
|
return textResult(String(err), true);
|
|
117
146
|
}
|
|
@@ -258,7 +287,7 @@ function registerDevTools(server, client) {
|
|
|
258
287
|
const data = await client.channelEventWait(ui, "engine_ui", "install", {
|
|
259
288
|
url,
|
|
260
289
|
});
|
|
261
|
-
return
|
|
290
|
+
return eventResult(data, "ruleset_install_failed");
|
|
262
291
|
} catch (err) {
|
|
263
292
|
return textResult(String(err), true);
|
|
264
293
|
}
|
|
@@ -278,7 +307,7 @@ function registerDevTools(server, client) {
|
|
|
278
307
|
const data = await client.channelEventWait(ui, "engine_ui", "flush", {
|
|
279
308
|
url,
|
|
280
309
|
});
|
|
281
|
-
return
|
|
310
|
+
return eventResult(data, "ruleset_flush_failed");
|
|
282
311
|
} catch (err) {
|
|
283
312
|
return textResult(String(err), true);
|
|
284
313
|
}
|
|
@@ -295,7 +324,7 @@ function registerDevTools(server, client) {
|
|
|
295
324
|
async (attrs) => {
|
|
296
325
|
try {
|
|
297
326
|
const data = await client.engineUiEvent("new", attrs);
|
|
298
|
-
return
|
|
327
|
+
return eventResult(data);
|
|
299
328
|
} catch (err) {
|
|
300
329
|
return textResult(String(err), true);
|
|
301
330
|
}
|
|
@@ -309,7 +338,7 @@ function registerDevTools(server, client) {
|
|
|
309
338
|
async ({ eci }) => {
|
|
310
339
|
try {
|
|
311
340
|
const data = await client.engineUiEvent("del", { eci });
|
|
312
|
-
return
|
|
341
|
+
return eventResult(data);
|
|
313
342
|
} catch (err) {
|
|
314
343
|
return textResult(String(err), true);
|
|
315
344
|
}
|
|
@@ -318,14 +347,15 @@ function registerDevTools(server, client) {
|
|
|
318
347
|
|
|
319
348
|
server.tool(
|
|
320
349
|
"create_channel",
|
|
321
|
-
"Create a channel on the root pico (engine_ui new_channel)",
|
|
350
|
+
"Create a channel on the root pico (engine_ui new_channel). Omit mcpPolicy and the channel is not exposed to MCP.",
|
|
322
351
|
{
|
|
323
352
|
tags: z.union([z.string(), z.array(z.string())]),
|
|
324
353
|
id: z.string().optional(),
|
|
325
354
|
eventPolicy: z.record(z.any()).optional(),
|
|
326
355
|
queryPolicy: z.record(z.any()).optional(),
|
|
356
|
+
mcpPolicy: z.record(z.any()).optional(),
|
|
327
357
|
},
|
|
328
|
-
async ({ tags, id, eventPolicy, queryPolicy }) => {
|
|
358
|
+
async ({ tags, id, eventPolicy, queryPolicy, mcpPolicy }) => {
|
|
329
359
|
try {
|
|
330
360
|
const tagList =
|
|
331
361
|
typeof tags === "string"
|
|
@@ -339,8 +369,9 @@ function registerDevTools(server, client) {
|
|
|
339
369
|
id,
|
|
340
370
|
eventPolicy,
|
|
341
371
|
queryPolicy,
|
|
372
|
+
mcpPolicy,
|
|
342
373
|
});
|
|
343
|
-
return
|
|
374
|
+
return eventResult(data);
|
|
344
375
|
} catch (err) {
|
|
345
376
|
return textResult(String(err), true);
|
|
346
377
|
}
|
|
@@ -348,4 +379,4 @@ function registerDevTools(server, client) {
|
|
|
348
379
|
);
|
|
349
380
|
}
|
|
350
381
|
|
|
351
|
-
module.exports = { registerDevTools };
|
|
382
|
+
module.exports = { registerDevTools, findWranglerEvent };
|
package/mcp/docs/CLAUDE.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This is the **pico engine**: an open-source Node.js runtime for **picos** (persistent compute objects) — small, always-on actors with persistent identity, state, and availability that talk by events and queries. Behavior is written in **KRL** (the pico rules language), compiled to JavaScript. Read `docs/design/pico-overview.md` first if the model isn't in your head yet.
|
|
4
4
|
|
|
5
|
-
Lerna mono-repo. Current release line: 1.
|
|
5
|
+
Lerna mono-repo. Current release line: 1.10.0 (`docs/release/1.10.0.md`).
|
|
6
6
|
|
|
7
7
|
## The one rule that governs all design: strict layering
|
|
8
8
|
|
|
@@ -20,6 +20,7 @@ Engine and wrangler stay **domain-agnostic**. If a change needs the words "owner
|
|
|
20
20
|
| Path | What |
|
|
21
21
|
|------|------|
|
|
22
22
|
| `packages/pico-engine` | The npm package people install; HTTP server, CLI, auth/OAuth, identity, UI host |
|
|
23
|
+
| `packages/pico-framework` | Pico runtime without KRL: picos, channels, policy, persistence. Versioned with the engine |
|
|
23
24
|
| `packages/pico-engine-core` | Executes compiled KRL; event lifecycle |
|
|
24
25
|
| `packages/krl-parser` → `krl-compiler` → `krl-generator` | KRL → AST → JS; AST → KRL |
|
|
25
26
|
| `packages/krl-stdlib` | KRL standard library |
|
|
@@ -30,7 +31,7 @@ Engine and wrangler stay **domain-agnostic**. If a change needs the words "owner
|
|
|
30
31
|
| `MEMORY.md` | Long-running working log: roadmap, decisions, gotchas. Source of truth for *why*; skim the TOC |
|
|
31
32
|
| `test-rulesets/`, `demos/` | KRL used by tests and demos. Each `demos/<name>/` has a README; its overview and instructions are in `docs/cookbook/<name>/` |
|
|
32
33
|
|
|
33
|
-
Sibling repos (same org, not in this tree): `manifold-api` (Manifold KRL), `sensor-network`, `MCPforEXP
|
|
34
|
+
Sibling repos (same org, not in this tree): `manifold-api` (Manifold KRL), `sensor-network`, `MCPforEXP`. `pico-framework` is `packages/pico-framework` in this repo.
|
|
34
35
|
|
|
35
36
|
## Commands
|
|
36
37
|
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Cookbook
|
|
2
|
+
|
|
3
|
+
Worked examples you can install and run. Each recipe has an overview and step-by-step instructions. The KRL lives in the pico-engine repository under [`demos/`](https://github.com/Picolab/pico-engine/tree/master/demos), and the engine ships a copy.
|
|
4
|
+
|
|
5
|
+
The quickest start is the **Try It!** tab on the root pico in the developer UI (engine config `show_tryit_menu` can show it on every pico, or hide it). It lists the demos that have a bootstrap ruleset. Open one and **Run** it: the tab creates a child pico and installs that ruleset, which sets up the whole demo. The same window shows each ruleset's code and its path on disk. Edit a file, **Flush**, and watch the demo change. Agents can do the same with the dev MCP server (`pico-engine mcp --stdio`): `list_try_it_demos`, `run_try_it_demo`, and `try_it_status`. It also serves these pages as `pico://docs/cookbook/...` resources.
|
|
6
|
+
|
|
7
|
+
The demos are meant for an engine without [OAuth](/pico-views?id=oauth-protected-meshes), such as one on your own machine. On a mesh with OAuth turned on they still install, but their pages and `curl` examples call the pico without an access token, so they may not load their data. The Try It! tab says so when that's the case.
|
|
8
|
+
|
|
9
|
+
| Recipe | What it shows | KRL |
|
|
10
|
+
|--------|---------------|-----|
|
|
11
|
+
| [Echo](/cookbook/echo/) | The hello world of events: a rule answers an event with a directive, from a page or from `curl` | [`demos/echo/`](https://github.com/Picolab/pico-engine/tree/master/demos/echo) |
|
|
12
|
+
| [Score tracker](/cookbook/score_tracker/) | A contest pico with a leaderboard, and an app channel whose policy lets contestants play without changing the pico | [`demos/score_tracker/`](https://github.com/Picolab/pico-engine/tree/master/demos/score_tracker) |
|
|
13
|
+
| [Pico views](/cookbook/xmlui/) | XMLUI pages served from a pico: queries, events, app channels, detail routes, components (the Thermostat demo), and a view over another pico's data | [`demos/xmlui/`](https://github.com/Picolab/pico-engine/tree/master/demos/xmlui) |
|
|
14
|
+
| [Two picos talking](/cookbook/two_picos/) | Two picos form a relationship, and one queries the other over it | [`demos/two_picos/`](https://github.com/Picolab/pico-engine/tree/master/demos/two_picos) |
|
|
15
|
+
| [Child pico tasks](/cookbook/child_tasks/) | Running each task in a new child pico that reports back and deletes itself, so the parent never waits | [`demos/child_tasks/`](https://github.com/Picolab/pico-engine/tree/master/demos/child_tasks) |
|
|
16
|
+
| [Guard rules](/cookbook/guard_rules/) | Making a request idempotent with a guard rule, and refusing work with a gate rule and `last` until it can be done | [`demos/guard_rules/`](https://github.com/Picolab/pico-engine/tree/master/demos/guard_rules) |
|
|
17
|
+
| [Layered rulesets](/cookbook/layered_rulesets/) | Rules that each do one thing and raise an event, and add-on rulesets that change what a pico does without editing the base | [`demos/layered_rulesets/`](https://github.com/Picolab/pico-engine/tree/master/demos/layered_rulesets) |
|
|
18
|
+
| [Collection](/cookbook/collection/) | A pico that keeps a collection of other picos over relationships, accepts members by role, and reports on all of them | [`demos/collection/`](https://github.com/Picolab/pico-engine/tree/master/demos/collection) |
|
|
19
|
+
| [Configuration and secrets](/cookbook/secrets/) | Getting a secret into a ruleset with install configuration or an event, keeping a ruleset idle until it has one, and where secrets stay visible | [`demos/secrets/`](https://github.com/Picolab/pico-engine/tree/master/demos/secrets) |
|
|
20
|
+
| [Bootstrap and channels](/cookbook/bootstrap/) | A bootstrap ruleset installing an app in dependency order with configuration, and an app that creates or updates its own channel on install, with a policy built from its schema | [`demos/bootstrap/`](https://github.com/Picolab/pico-engine/tree/master/demos/bootstrap) |
|
|
21
|
+
| [KBlog](/cookbook/kblog/) | A blog written in KRL: four rulesets that work together through an event hierarchy, with a reader channel and an author channel | [`demos/kblog/`](https://github.com/Picolab/pico-engine/tree/master/demos/kblog) |
|
|
22
|
+
| [Querying JSON](/cookbook/json_query/) | Finding values in nested JSON with the `query()` operator and JSONPath: four canned queries over a fleet's data, or your own | [`demos/json_query/`](https://github.com/Picolab/pico-engine/tree/master/demos/json_query) |
|
|
23
|
+
| [Moving picos](/cookbook/moving_picos/) | Exporting a pico and its children from one engine and importing them on another, keeping its did:webvh identity and relationships | [`demos/moving_picos/`](https://github.com/Picolab/pico-engine/tree/master/demos/moving_picos) |
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Bootstrap and channels
|
|
2
|
+
|
|
3
|
+
Two habits make a KRL app easy to install:
|
|
4
|
+
|
|
5
|
+
- **A bootstrap ruleset.** An app of several rulesets has an install order: a ruleset that uses another as a module can't be installed before it. A bootstrap ruleset knows the order. Installed on a pico, it installs the others one at a time, each when the `wrangler:ruleset_installed` event for the one before arrives, and gives each its configuration. Every Try It! demo starts this way.
|
|
6
|
+
- **A channel made on install.** An app ruleset creates the channel its users need from a rule that selects its own `wrangler:ruleset_installed`. That rule updates the channel if it already exists, so reinstalling doesn't pile up channels or change the channel id people are using.
|
|
7
|
+
|
|
8
|
+
This demo is a small visitor log. The bootstrap installs a formatting module and then the app, with a greeting in its install configuration. The app creates its channel with a policy built from its own schema. The schema lists only documented rules and functions, so the channel allows exactly the ruleset's documented API.
|
|
9
|
+
|
|
10
|
+
To run it, follow the [instructions](/cookbook/bootstrap/instructions).
|
|
11
|
+
|
|
12
|
+
## The rulesets
|
|
13
|
+
|
|
14
|
+
| Ruleset | File | What it shows |
|
|
15
|
+
|---------|------|---------------|
|
|
16
|
+
| Bootstrap | [`com.example.visitors.bootstrap.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/bootstrap/com.example.visitors.bootstrap.krl) | Installing in dependency order with `install_ruleset_request` and `absoluteURL: meta:rulesetURI`, and passing `config` |
|
|
17
|
+
| Formatting | [`com.example.visitors.format.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/bootstrap/com.example.visitors.format.krl) | A module the app needs, so it goes first |
|
|
18
|
+
| Visitor log | [`com.example.visitors.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/bootstrap/com.example.visitors.krl) | `meta:rulesetConfig`; a channel created on install, with a policy built from `wrangler:rulesetSchema`; updated in place with `wrangler:updateChannel`; and duplicates cleaned up with `wrangler:deleteChannel` |
|
|
19
|
+
|
|
20
|
+
## What you need
|
|
21
|
+
|
|
22
|
+
- A running pico engine (1.9.4 or later for the page, which uses the shared `PicoTheme` component).
|
|
23
|
+
- `io.picolabs.xmlui` on the pico for the page. The bootstrap installs it.
|