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.
Files changed (126) hide show
  1. package/README.md +11 -5
  2. package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
  3. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
  4. package/demos/echo/com.example.echo.bootstrap.krl +10 -7
  5. package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
  6. package/demos/json_query/README.md +11 -0
  7. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  8. package/demos/json_query/com.example.json_query.krl +162 -0
  9. package/demos/json_query/try-it.md +5 -0
  10. package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
  11. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
  12. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
  13. package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
  14. package/demos/try-it-order.json +1 -1
  15. package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
  16. package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
  17. package/dist/cli.js +5 -1
  18. package/dist/engineConfig.js +1 -1
  19. package/dist/identity/portableMove.js +5 -1
  20. package/dist/index.js +44 -12
  21. package/dist/internalAccess.js +110 -0
  22. package/dist/oauth/OAuthService.js +172 -10
  23. package/dist/oauth/acg.js +194 -24
  24. package/dist/oauth/cimd.js +381 -0
  25. package/dist/oauth/discovery.js +175 -0
  26. package/dist/runMcp.js +1 -1
  27. package/dist/server.js +197 -48
  28. package/dist/subtreeWrangler.js +8 -5
  29. package/dist/uiChannelPolicies.js +2 -0
  30. package/krl/io.picolabs.pds.krl +109 -21
  31. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  32. package/krl/io.picolabs.wrangler.krl +21 -9
  33. package/mcp/devResources.js +52 -0
  34. package/mcp/devTools.js +40 -9
  35. package/mcp/docs/CLAUDE.md +3 -2
  36. package/mcp/docs/cookbook/README.md +23 -0
  37. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  38. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  39. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  40. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  41. package/mcp/docs/cookbook/collection/README.md +21 -0
  42. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  43. package/mcp/docs/cookbook/echo/README.md +19 -0
  44. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  45. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  46. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  47. package/mcp/docs/cookbook/json_query/README.md +26 -0
  48. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  49. package/mcp/docs/cookbook/kblog/README.md +60 -0
  50. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  51. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  52. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  53. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  54. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  55. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  56. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  57. package/mcp/docs/cookbook/secrets/README.md +25 -0
  58. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  59. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  60. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  61. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  62. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  63. package/mcp/docs/developing/README.md +28 -0
  64. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  65. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  66. package/mcp/docs/developing/converting-time-formats.md +28 -0
  67. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  68. package/mcp/docs/developing/decoding-form-data.md +67 -0
  69. package/mcp/docs/developing/engine-log-files.md +34 -0
  70. package/mcp/docs/developing/event-loop.md +77 -0
  71. package/mcp/docs/developing/events-from-email.md +80 -0
  72. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  73. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  74. package/mcp/docs/developing/misconceptions.md +467 -0
  75. package/mcp/docs/developing/names-and-scope.md +44 -0
  76. package/mcp/docs/developing/postman.md +159 -0
  77. package/mcp/docs/developing/querying-another-pico.md +47 -0
  78. package/mcp/docs/developing/singleton-picos.md +36 -0
  79. package/mcp/docs/developing/tabular-data.md +67 -0
  80. package/mcp/docs/developing/tips.md +251 -0
  81. package/mcp/docs/developing/webhook-signatures.md +56 -0
  82. package/mcp/docs/developing/workflow.md +106 -0
  83. package/mcp/docs/exp/README.md +46 -0
  84. package/mcp/docs/exp/event.md +110 -0
  85. package/mcp/docs/exp/query.md +94 -0
  86. package/mcp/docs/lessons/README.md +59 -0
  87. package/mcp/docs/lessons/events-and-queries.md +247 -0
  88. package/mcp/docs/lessons/gossip.md +28 -0
  89. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  90. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  91. package/mcp/docs/lessons/pico-state.md +267 -0
  92. package/mcp/docs/lessons/pico-views.md +290 -0
  93. package/mcp/docs/lessons/quickstart.md +157 -0
  94. package/mcp/docs/lessons/relationships.md +530 -0
  95. package/mcp/docs/lessons/scatter-gather.md +362 -0
  96. package/mcp/docs/pico-engine.md +7 -5
  97. package/mcp/docs/pico-overview.md +3 -3
  98. package/mcp/docs/wrangler/README.md +47 -0
  99. package/mcp/docs/wrangler/channels.md +235 -0
  100. package/mcp/docs/wrangler/oauth.md +56 -0
  101. package/mcp/docs/wrangler/pds.md +423 -0
  102. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  103. package/mcp/docs/wrangler/relationships.md +297 -0
  104. package/mcp/docs/wrangler/wrangler.md +253 -0
  105. package/mcp/docs/wrangler/xmlui.md +60 -0
  106. package/mcp/engineClient.js +57 -5
  107. package/mcp/mcpScopes.js +118 -0
  108. package/mcp/meshHttp.js +151 -45
  109. package/mcp/runStdio.js +2 -0
  110. package/mcp/subtreeTools.js +184 -0
  111. package/mcp/tryItTools.js +202 -0
  112. package/package.json +14 -8
  113. package/public/pico-engine-ui.js +26 -26
  114. package/src/cli.ts +6 -2
  115. package/src/engineConfig.ts +5 -2
  116. package/src/identity/portableMove.ts +6 -1
  117. package/src/index.ts +469 -430
  118. package/src/internalAccess.ts +127 -0
  119. package/src/oauth/OAuthService.ts +243 -11
  120. package/src/oauth/acg.ts +289 -25
  121. package/src/oauth/cimd.ts +508 -0
  122. package/src/oauth/discovery.ts +233 -0
  123. package/src/runMcp.ts +3 -1
  124. package/src/server.ts +252 -52
  125. package/src/subtreeWrangler.ts +17 -5
  126. package/src/uiChannelPolicies.ts +2 -0
package/README.md CHANGED
@@ -13,7 +13,7 @@ pico-engine
13
13
 
14
14
  Open `http://localhost:3000` — a root pico and UI channel are created on first run. Operator settings (port, data dir, policy ceiling) live in **`~/.config/pico-engine/config.json`**; copy [`config.example.json`](https://github.com/Picolab/pico-engine/blob/master/packages/pico-engine/config.example.json). See the [engine guide](https://docs.picolabs.io/#/pico-engine).
15
15
 
16
- **AI coding assistants:** `pico-engine mcp --stdio` runs an MCP server against the same engine (status, picos, channels, events, queries, KRL validation). Machine-readable docs: [`llms.txt`](https://docs.picolabs.io/llms.txt) and [`llms-full.txt`](https://docs.picolabs.io/llms-full.txt). Repo conventions for agents: [`CLAUDE.md`](https://github.com/Picolab/pico-engine/blob/master/CLAUDE.md).
16
+ **AI coding assistants:** `pico-engine mcp --stdio` runs an MCP server against the same engine (status, picos, channels, events, queries, KRL validation, and the Try It! demos: `list_try_it_demos`, `run_try_it_demo`, `try_it_status`). It also serves the cookbook and Developing with Picos docs as `pico://docs/...` resources. Machine-readable docs: [`llms.txt`](https://docs.picolabs.io/llms.txt) and [`llms-full.txt`](https://docs.picolabs.io/llms-full.txt). Repo conventions for agents: [`CLAUDE.md`](https://github.com/Picolab/pico-engine/blob/master/CLAUDE.md).
17
17
 
18
18
  ## Getting Started
19
19
 
@@ -132,7 +132,7 @@ The server is configured via some environment variables.
132
132
  - `PICO_ENGINE_HOME` - Where the database and other files should be stored. By default it's `~/.pico-engine/`
133
133
  - `PICO_ENGINE_BASE_URL` - The public url prefix to reach this engine. By default it's `"http://localhost:3000"`
134
134
  - `PICO_ENGINE_ALLOW_SELF_SIGNUP` - Set to `"true"` or `"1"` to allow open registration after bootstrap (default: off; bootstrap and invite still work)
135
- - `PICO_ENGINE_ALLOW_LOCALHOST_C` - Set to `"0"` to require passkey session on `/c/*` even from localhost (default: allow localhost without session for in-engine HTTP loops). Full registry: repo `MEMORY.md` § Engine environment variables.
135
+ - `PICO_ENGINE_ALLOW_LOCALHOST_C` - `"1"` or `"true"` lets a direct loopback connection call `/c/*` without a passkey (default: off). Proxy headers are never treated as local. The dev MCP sends `X-Pico-Internal` from `$PICO_ENGINE_HOME/internal-token`. Full registry: repo `MEMORY.md` § Engine environment variables.
136
136
  - `PICO_ENGINE_LOG_FILE` - Log file path. Set to `stdout`, `-`, or `0` for **stdout only** (recommended on Fargate + EFS; use CloudWatch for retention). Default: `$PICO_ENGINE_HOME/pico-engine.log`.
137
137
  - `PICO_ENGINE_LOG_MIRROR` - When stdout-only: **`true`/`1`** (default) mirrors structured JSON to **`$PICO_ENGINE_HOME/pico-engine.log`** so **`ctx:logs`** and the Developer UI **Logging** tab work; set **`false`/`0`** to skip the mirror file (e.g. avoid EFS log churn). **Config:** `logMirror` in `config.json` (see `config.example.json`).
138
138
  - `PICO_ENGINE_SHOW_TRYIT_MENU` - Where the Developer UI shows the **Try It!** tab: `off`, `root_only` (default), or `all` (config: `show_tryit_menu`).
@@ -232,7 +232,7 @@ The developer UI uses **passkeys** (WebAuthn). On first visit you register a pas
232
232
 
233
233
  When self-signup is disabled, **Settings → Invite someone** can include an optional **bootstrap ruleset URL** (`file://` or `https://`). The engine validates the URL when the invite is created; when the invitee registers, that ruleset is installed on their new root after the base OS rulesets (e.g. a Manifold bootstrap KRL). The invite **label** pre-fills the invitee's mesh name (editable before registering). WebAuthn `user.name` is set to the mesh name so password managers (e.g. 1Password) show it alongside the site hostname.
234
234
 
235
- - **`/c/*`** — internal/UI API; requires a passkey session cookie (localhost bypass is on by default for in-engine KRL HTTP loops; set `PICO_ENGINE_ALLOW_LOCALHOST_C=0` to disable).
235
+ - **`/c/*`** — internal/UI API. Requires a passkey session cookie, or the dev MCP's `X-Pico-Internal` token (`$PICO_ENGINE_HOME/internal-token`, rewritten each startup). A direct loopback bypass exists only when `PICO_ENGINE_ALLOW_LOCALHOST_C=1`.
236
236
  - **`/auth/*`** — registration, login, session management.
237
237
 
238
238
  ## OAuth
@@ -246,6 +246,10 @@ Two grant types can coexist in the same mesh:
246
246
  | **Client Credentials** | Inbound webhooks (Stripe, GitHub, …) | Channel **ECI** | Single channel only |
247
247
  | **Authorization Code + PKCE** | Apps like Home Assistant | `app_…` | Whole mesh (root + descendants) |
248
248
 
249
+ An MCP client discovers this server without a pre-registered app. `GET /.well-known/oauth-authorization-server` describes the authorization server. `GET /.well-known/oauth-protected-resource/mcp/{eci}` describes that channel's MCP URL. `/mcp/{eci}` answers a missing bearer token with `401` and `WWW-Authenticate: Bearer resource_metadata="…"`.
250
+
251
+ A client can use an https URL as its `client_id`. The engine fetches that URL as a Client ID Metadata Document. The document's `client_id` must equal the URL, and its `redirect_uris` must include the request's `redirect_uri`. The approval screen shows the client's name, logo, page, and host, plus the mesh and the scopes requested. These clients are public: S256 PKCE and no client secret. Pre-registered apps still work.
252
+
249
253
  ### Mesh lock
250
254
 
251
255
  Install the optional ruleset **`io.picolabs.oauth`** on the **root pico** to require a Bearer token on most **`/sky/*`** requests for that mesh. Without it, open channels work as before (channel policy only); channels tagged **`oauth-webhook`** always require Bearer.
@@ -322,7 +326,7 @@ Content-Type: application/json
322
326
  }
323
327
  ```
324
328
 
325
- For manual testing with plain PKCE, use `code_challenge_method=plain` and set `code_challenge` and `code_verifier` to the same string.
329
+ PKCE is S256 only: `code_challenge` is the base64url SHA-256 of `code_verifier`. Send the same `resource` on the authorize request and the token request (`{base}/sky` for Sky, `{base}/mcp/{eci}` for that channel's MCP URL, or `{base}/mcp/mesh/{eci}` for the whole-mesh endpoint). A token is accepted only at the resource it names. Tokens issued with no `resource` still work on `/sky/*`. `mesh:read` is required for queries and `mesh:act` for events.
326
330
 
327
331
  **Refresh:**
328
332
 
@@ -337,6 +341,8 @@ Content-Type: application/json
337
341
  }
338
342
  ```
339
343
 
344
+ Each refresh returns a new access token and a new refresh token. The previous refresh token no longer works. Sending it again revokes the replacement as well. A public client (no secret, including a Client ID Metadata Document) gets an access token that lasts one hour. A confidential app's access token lasts 24 hours. The refresh token lasts 90 days, and a successful refresh starts that clock again. Send the same `resource` the grant was issued with.
345
+
340
346
  **Use the access token** on any channel ECI in the mesh:
341
347
 
342
348
  ```http
@@ -394,7 +400,7 @@ Every pico has a portable **did:webvh** identity. **DID-based relationships** (L
394
400
 
395
401
  Full guide: [Layer 2 relationships](https://docs.picolabs.io/#/guides/layer2-subscriptions) · Release notes: [1.6](https://docs.picolabs.io/#/release/1.6) · [CHANGELOG.md](https://github.com/Picolab/pico-engine/blob/master/CHANGELOG.md) (1.6.4 mesh-oauth-exempt + KRL directory UI; 1.6.3 fixes)
396
402
 
397
- **Dependency:** pico-engine 1.6 requires **pico-framework `^0.8.1`** (npm). When developing engine + framework together, use `npm run link-framework` from the repo root.
403
+ **Dependency:** `pico-framework` is `packages/pico-framework` in this repo and is versioned with the engine. `krl-stdlib`, `pico-engine-core`, and `pico-engine` depend on it.
398
404
 
399
405
  ### Layer 2 tests
400
406
 
@@ -53,17 +53,21 @@ ruleset com.example.visitors.bootstrap {
53
53
  pre {
54
54
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
55
55
  }
56
- always {
56
+ if not has_xmlui then noop()
57
+ fired {
57
58
  ent:stage := "installing " + xmlui_rid
59
+ raise wrangler event "install_ruleset_request" attributes
60
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
61
+ }
62
+ else {
63
+ raise bootstrap event "xmlui_ready"
64
+ }
65
+ finally {
58
66
  raise wrangler event "new_channel_request" attributes {
59
67
  "tags": ["try_it"],
60
68
  "eventPolicy": {"allow": [], "deny": []},
61
69
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
62
70
  }
63
- raise wrangler event "install_ruleset_request" attributes
64
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
65
- if not has_xmlui
66
- raise bootstrap event "xmlui_ready" if has_xmlui
67
71
  }
68
72
  }
69
73
 
@@ -50,19 +50,22 @@ ruleset com.example.task_runner.bootstrap {
50
50
  pre {
51
51
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
52
52
  }
53
- always {
53
+ if not has_xmlui then noop()
54
+ fired {
55
+ raise wrangler event "install_ruleset_request" attributes
56
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
57
+ }
58
+ else {
59
+ raise wrangler event "install_ruleset_request" attributes
60
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
61
+ }
62
+ finally {
54
63
  ent:stage := "installing"
55
64
  raise wrangler event "new_channel_request" attributes {
56
65
  "tags": ["try_it"],
57
66
  "eventPolicy": {"allow": [], "deny": []},
58
67
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
59
68
  }
60
- raise wrangler event "install_ruleset_request" attributes
61
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
62
- if not has_xmlui
63
- raise wrangler event "install_ruleset_request" attributes
64
- {"absoluteURL": meta:rulesetURI, "rid": app_rid}
65
- if has_xmlui
66
69
  }
67
70
  }
68
71
 
@@ -48,19 +48,22 @@ ruleset com.example.echo.bootstrap {
48
48
  pre {
49
49
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
50
50
  }
51
- always {
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 {
52
61
  ent:stage := "installing"
53
62
  raise wrangler event "new_channel_request" attributes {
54
63
  "tags": ["try_it"],
55
64
  "eventPolicy": {"allow": [], "deny": []},
56
65
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
57
66
  }
58
- raise wrangler event "install_ruleset_request" attributes
59
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
60
- if not has_xmlui
61
- raise wrangler event "install_ruleset_request" attributes
62
- {"absoluteURL": meta:rulesetURI, "rid": app_rid}
63
- if has_xmlui
64
67
  }
65
68
  }
66
69
 
@@ -51,19 +51,22 @@ ruleset com.example.archive.bootstrap {
51
51
  pre {
52
52
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
53
53
  }
54
- always {
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 {
55
64
  ent:stage := "installing"
56
65
  raise wrangler event "new_channel_request" attributes {
57
66
  "tags": ["try_it"],
58
67
  "eventPolicy": {"allow": [], "deny": []},
59
68
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
60
69
  }
61
- raise wrangler event "install_ruleset_request" attributes
62
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
63
- if not has_xmlui
64
- raise wrangler event "install_ruleset_request" attributes
65
- {"absoluteURL": meta:rulesetURI, "rid": app_rid}
66
- if has_xmlui
67
70
  }
68
71
  }
69
72
 
@@ -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
+ }
@@ -0,0 +1,162 @@
1
+ /**
2
+ * Querying JSON: the query() operator finds values in a map or array with a
3
+ * JSONPath expression. The pico holds a fleet's vehicles, trips, and fill-ups
4
+ * (the kind of data Fuse kept), and the page runs canned queries against it, or
5
+ * one you type.
6
+ */
7
+ ruleset com.example.json_query {
8
+ meta {
9
+ name "Querying JSON"
10
+ description "Finds values in nested JSON with the query() operator and JSONPath."
11
+ author "PICOLABS"
12
+
13
+ use module io.picolabs.xmlui alias ui
14
+
15
+ shares queryPage, fleetData, cannedQueries, runQuery
16
+ }
17
+
18
+ global {
19
+ channel_tags = ["json_query", "app"]
20
+
21
+ fleet = {
22
+ "owner": {"name": "Ada Lovelace", "email": "ada@example.com"},
23
+ "vehicles": [
24
+ {
25
+ "name": "Work truck",
26
+ "make": "Ford", "model": "F-150", "year": 2022, "odometer": 48210,
27
+ "trips": [
28
+ {"date": "2026-11-02", "miles": 42.6, "category": "business", "cost": 9.8},
29
+ {"date": "2026-11-03", "miles": 3.1, "category": "personal", "cost": 0.71},
30
+ {"date": "2026-11-05", "miles": 118.4, "category": "business", "cost": 27.23}
31
+ ],
32
+ "fillups": [
33
+ {"date": "2026-10-28", "gallons": 22.1, "price": 3.39},
34
+ {"date": "2026-11-06", "gallons": 19.8, "price": 3.29}
35
+ ]
36
+ },
37
+ {
38
+ "name": "Family car",
39
+ "make": "Toyota", "model": "Prius", "year": 2019, "odometer": 91877,
40
+ "trips": [
41
+ {"date": "2026-11-01", "miles": 12.0, "category": "personal", "cost": 1.2},
42
+ {"date": "2026-11-04", "miles": 27.5, "category": "business", "cost": 2.75}
43
+ ],
44
+ "fillups": [
45
+ {"date": "2026-11-03", "gallons": 8.4, "price": 3.35}
46
+ ]
47
+ },
48
+ {
49
+ "name": "Commuter",
50
+ "make": "Chevrolet", "model": "Bolt", "year": 2023, "odometer": 15302,
51
+ "trips": [
52
+ {"date": "2026-11-02", "miles": 31.2, "category": "business", "cost": 1.4}
53
+ ],
54
+ "fillups": []
55
+ }
56
+ ]
57
+ }
58
+
59
+ /**
60
+ * The fleet data the queries run against.
61
+ * @returns Map
62
+ */
63
+ fleetData = function() {
64
+ fleet
65
+ }
66
+
67
+ /**
68
+ * Four queries to try, each showing a different part of JSONPath.
69
+ * @returns Array
70
+ */
71
+ cannedQueries = function() {
72
+ [
73
+ {
74
+ "label": "Every vehicle's name",
75
+ "path": "$.vehicles[*].name",
76
+ "explain": "Child selectors (.vehicles, .name) and the wildcard [*], which takes every element of the array."
77
+ },
78
+ {
79
+ "label": "All the miles, at any depth",
80
+ "path": "$..miles",
81
+ "explain": "The descendant selector .. finds a member wherever it is, without spelling out the path to it."
82
+ },
83
+ {
84
+ "label": "Business trips over 25 miles",
85
+ "path": "$.vehicles[*].trips[?@.category == 'business' && @.miles > 25]",
86
+ "explain": "A filter [?...] keeps the trips for which the test is true. @ is the trip being tested."
87
+ },
88
+ {
89
+ "label": "Each vehicle's latest fill-up",
90
+ "path": "$.vehicles[?count(@.fillups[*]) > 0].fillups[-1]",
91
+ "explain": "A filter that calls count() skips the electric car, and [-1] takes the last element of each fillups array."
92
+ }
93
+ ]
94
+ }
95
+
96
+ /**
97
+ * Run a JSONPath query against the fleet data.
98
+ * @param path String "a JSONPath expression, starting with $"
99
+ * @returns Map
100
+ */
101
+ runQuery = function(path) {
102
+ result = fleet.query(path)
103
+ answer = {"path": path, "count": result.length(), "result": result}
104
+ answer
105
+ }
106
+
107
+ /**
108
+ * Show the data, run a canned query, or type your own.
109
+ * @view "Querying JSON"
110
+ */
111
+ queryPage = function() {
112
+ data_url = ui:query_url("fleetData", meta:rid, meta:eci)
113
+ canned_url = ui:query_url("cannedQueries", meta:rid, meta:eci)
114
+ run_url = ui:query_url("runQuery", meta:rid, meta:eci)
115
+ <<
116
+ <Component name="QueryPage" var.showData="{false}" var.path="" var.label="" var.explain="">
117
+ <DataSource id="data" url="#{data_url}" headers="{appGlobals.auth}" />
118
+ <DataSource id="canned" url="#{canned_url}" headers="{appGlobals.auth}" />
119
+ <DataSource id="run" url="#{run_url}" headers="{appGlobals.auth}" queryParams="{{path: path}}" when="{path}" />
120
+ <PicoTheme>
121
+ <Card title="Querying JSON"
122
+ subtitle="This pico holds a fleet's vehicles, trips, and fill-ups. Each button runs fleet.query(path) on the pico and shows what it returns." />
123
+ <Button label="{showData ? 'Hide the JSON' : 'Show the JSON'}" onClick="showData = !showData" />
124
+ <FlowLayout>
125
+ <VStack width="{showData ? '50%' : '100%'}">
126
+ <H3>Try a query</H3>
127
+ <HStack wrapContent="true">
128
+ <Items data="{canned.value}">
129
+ <Button label="{$item.label}" variant="outlined"
130
+ onClick="path = $item.path; label = $item.label; explain = $item.explain" />
131
+ </Items>
132
+ </HStack>
133
+ <Text>Or type your own JSONPath:</Text>
134
+ <HStack>
135
+ <TextBox id="own" initialValue="$.owner.email" width="*" />
136
+ <Button label="Run it" onClick="path = own.value; label = 'Your query'; explain = ''" />
137
+ </HStack>
138
+ <Card when="{path}" title="{label}">
139
+ <Text variant="code">fleet.query("{path}")</Text>
140
+ <Text when="{explain}">{explain}</Text>
141
+ <Text when="{run.value.error}" variant="secondary">{run.value.error}</Text>
142
+ <Text when="{run.value.result}" variant="secondary">{run.value.count} {run.value.count == 1 ? 'value' : 'values'}:</Text>
143
+ <Text when="{run.value.result}" variant="mono" preserveLinebreaks="true" value="{JSON.stringify(run.value.result, null, 2)}" />
144
+ </Card>
145
+ </VStack>
146
+ <Card when="{showData}" width="50%" title="The fleet data">
147
+ <ScrollViewer height="520px">
148
+ <Text variant="mono" preserveLinebreaks="true" value="{JSON.stringify(data.value, null, 2)}" />
149
+ </ScrollViewer>
150
+ </Card>
151
+ </FlowLayout>
152
+ </PicoTheme>
153
+ </Component>
154
+ >>
155
+ }
156
+ }
157
+
158
+ rule create_app_channel {
159
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
160
+ ui:create_app_channel(channel_tags, [], ["queryPage", "fleetData", "cannedQueries", "runQuery"], meta:rid)
161
+ }
162
+ }
@@ -0,0 +1,5 @@
1
+ - Open **Query page** and click **Show the JSON**. The fleet data appears beside the queries, so you can check each answer against it.
2
+ - Click each of the four query buttons. Each shows the JSONPath it ran, what that path uses, and the values `query()` returned, always as an array.
3
+ - Type your own query and click **Run it**. Try `$.vehicles[?@.year > 2020].name`, `$..cost`, or `$.vehicles[0].trips[-1:]`.
4
+ - Type a broken path, such as `$.vehicles[?@.year >`. The pico answers with the parse error instead of a result.
5
+ - In the code, `runQuery` is one line of KRL: `fleet.query(path)`. Edit the `cannedQueries` list, click **Flush**, and reload the page to add your own buttons.
@@ -72,19 +72,22 @@ ruleset com.example.kblog.bootstrap {
72
72
  pre {
73
73
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
74
74
  }
75
- always {
75
+ if not has_xmlui then noop()
76
+ fired {
77
+ raise wrangler event "install_ruleset_request" attributes
78
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
79
+ }
80
+ else {
81
+ raise wrangler event "install_ruleset_request" attributes
82
+ {"absoluteURL": meta:rulesetURI, "rid": config_rid}
83
+ }
84
+ finally {
76
85
  ent:stage := "installing"
77
86
  raise wrangler event "new_channel_request" attributes {
78
87
  "tags": ["try_it"],
79
88
  "eventPolicy": {"allow": [], "deny": []},
80
89
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
81
90
  }
82
- raise wrangler event "install_ruleset_request" attributes
83
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
84
- if not has_xmlui
85
- raise wrangler event "install_ruleset_request" attributes
86
- {"absoluteURL": meta:rulesetURI, "rid": config_rid}
87
- if has_xmlui
88
91
  }
89
92
  }
90
93
 
@@ -50,19 +50,22 @@ ruleset com.example.invitations.bootstrap {
50
50
  pre {
51
51
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
52
52
  }
53
- always {
53
+ if not has_xmlui then noop()
54
+ fired {
55
+ raise wrangler event "install_ruleset_request" attributes
56
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
57
+ }
58
+ else {
59
+ raise wrangler event "install_ruleset_request" attributes
60
+ {"absoluteURL": meta:rulesetURI, "rid": base_rid}
61
+ }
62
+ finally {
54
63
  ent:stage := "installing"
55
64
  raise wrangler event "new_channel_request" attributes {
56
65
  "tags": ["try_it"],
57
66
  "eventPolicy": {"allow": [], "deny": []},
58
67
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
59
68
  }
60
- raise wrangler event "install_ruleset_request" attributes
61
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
62
- if not has_xmlui
63
- raise wrangler event "install_ruleset_request" attributes
64
- {"absoluteURL": meta:rulesetURI, "rid": base_rid}
65
- if has_xmlui
66
69
  }
67
70
  }
68
71
 
@@ -60,19 +60,22 @@ ruleset com.example.score_tracker.bootstrap {
60
60
  pre {
61
61
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
62
62
  }
63
- always {
63
+ if not has_xmlui then noop()
64
+ fired {
65
+ raise wrangler event "install_ruleset_request" attributes
66
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
67
+ }
68
+ else {
69
+ raise wrangler event "install_ruleset_request" attributes
70
+ {"absoluteURL": meta:rulesetURI, "rid": app_rid}
71
+ }
72
+ finally {
64
73
  ent:stage := "installing"
65
74
  raise wrangler event "new_channel_request" attributes {
66
75
  "tags": ["try_it"],
67
76
  "eventPolicy": {"allow": [], "deny": []},
68
77
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
69
78
  }
70
- raise wrangler event "install_ruleset_request" attributes
71
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
72
- if not has_xmlui
73
- raise wrangler event "install_ruleset_request" attributes
74
- {"absoluteURL": meta:rulesetURI, "rid": app_rid}
75
- if has_xmlui
76
79
  }
77
80
  }
78
81
 
@@ -58,19 +58,22 @@ ruleset com.example.notifier.bootstrap {
58
58
  pre {
59
59
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
60
60
  }
61
- always {
61
+ if not has_xmlui then noop()
62
+ fired {
63
+ raise wrangler event "install_ruleset_request" attributes
64
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
65
+ }
66
+ else {
67
+ raise wrangler event "install_ruleset_request" attributes
68
+ {"absoluteURL": meta:rulesetURI, "rid": notifier_rid}
69
+ }
70
+ finally {
62
71
  ent:stage := "installing"
63
72
  raise wrangler event "new_channel_request" attributes {
64
73
  "tags": ["try_it"],
65
74
  "eventPolicy": {"allow": [], "deny": []},
66
75
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
67
76
  }
68
- raise wrangler event "install_ruleset_request" attributes
69
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
70
- if not has_xmlui
71
- raise wrangler event "install_ruleset_request" attributes
72
- {"absoluteURL": meta:rulesetURI, "rid": notifier_rid}
73
- if has_xmlui
74
77
  raise wrangler event "new_child_request" attributes
75
78
  {"name": "Hook service", "secrets_demo": "hook_service", "backgroundColor": "#ffe0b2"}
76
79
  }
@@ -1 +1 @@
1
- ["echo", "score_tracker", "xmlui", "two_picos", "child_tasks", "guard_rules", "layered_rulesets", "collection", "secrets", "bootstrap", "kblog"]
1
+ ["echo", "score_tracker", "xmlui", "two_picos", "child_tasks", "guard_rules", "layered_rulesets", "collection", "secrets", "bootstrap", "kblog", "json_query"]
@@ -99,10 +99,13 @@ ruleset com.example.two_picos.bootstrap {
99
99
  ready = ent:ready.defaultsTo({}).put(role, true)
100
100
  both = (ready{"answerer"} && ready{"asker"}) => true | false
101
101
  }
102
- always {
102
+ if both then noop()
103
+ fired {
104
+ raise two_picos event "both_ready"
105
+ }
106
+ finally {
103
107
  ent:ready{role} := true
104
108
  ent:stage := "installing rulesets"
105
- raise two_picos event "both_ready" if both
106
109
  }
107
110
  }
108
111
 
@@ -57,19 +57,22 @@ ruleset com.example.thermostat.bootstrap {
57
57
  pre {
58
58
  has_xmlui = wrangler:installedRIDs() >< xmlui_rid
59
59
  }
60
- always {
60
+ if not has_xmlui then noop()
61
+ fired {
62
+ raise wrangler event "install_ruleset_request" attributes
63
+ {"url": host() + "/krl/" + xmlui_rid + ".krl"}
64
+ }
65
+ else {
66
+ raise wrangler event "install_ruleset_request" attributes
67
+ {"absoluteURL": meta:rulesetURI, "rid": thermostat_rid}
68
+ }
69
+ finally {
61
70
  ent:stage := "installing"
62
71
  raise wrangler event "new_channel_request" attributes {
63
72
  "tags": ["try_it"],
64
73
  "eventPolicy": {"allow": [], "deny": []},
65
74
  "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
66
75
  }
67
- raise wrangler event "install_ruleset_request" attributes
68
- {"url": host() + "/krl/" + xmlui_rid + ".krl"}
69
- if not has_xmlui
70
- raise wrangler event "install_ruleset_request" attributes
71
- {"absoluteURL": meta:rulesetURI, "rid": thermostat_rid}
72
- if has_xmlui
73
76
  }
74
77
  }
75
78
 
package/dist/cli.js CHANGED
@@ -70,7 +70,7 @@ Environment (optional; Docker/CI when not set in config file):
70
70
  PICO_ENGINE_BASE_URL - Public URL (WebAuthn, did:webvh)
71
71
  PICO_ENGINE_RP_ID / PICO_ENGINE_ORIGIN - WebAuthn (or use webauthn block in config file)
72
72
  PICO_ENGINE_ALLOW_SELF_SIGNUP - "true"/"1" or "false"/"0"
73
- PICO_ENGINE_ALLOW_LOCALHOST_C - "0" disables localhost /c/* bypass (see config allowLocalhostChannelBypass)
73
+ PICO_ENGINE_ALLOW_LOCALHOST_C - "1"/"true" allows direct loopback /c/* without a passkey (default off; config allowLocalhostChannelBypass). Dev MCP uses $PICO_ENGINE_HOME/internal-token
74
74
  PICO_ENGINE_WILDCARD_SKY_REQUIRE_BEARER - "1" enables wildcard /sky/* bearer requirement
75
75
  PICO_ENGINE_LOG_FILE - Log path, or stdout/- / 0 for console-only
76
76
  PICO_ENGINE_LOG_MIRROR - "true"/"1" or "false"/"0" (mirror JSON lines to \$PICO_ENGINE_HOME/pico-engine.log when stdout-only; default on)
@@ -115,6 +115,10 @@ Environment (optional; Docker/CI when not set in config file):
115
115
  installGracefulShutdown(engine);
116
116
  })
117
117
  .catch((err) => {
118
+ if (err && err.code === "EADDRINUSE") {
119
+ console.error(`Port ${err.port} is already in use.`);
120
+ process.exit(1);
121
+ }
118
122
  console.error("Failed to start engine.");
119
123
  console.error(err);
120
124
  process.exit(1);