pico-engine 1.9.4 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -5
- package/demos/bootstrap/README.md +12 -0
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
- package/demos/bootstrap/com.example.visitors.format.krl +25 -0
- package/demos/bootstrap/com.example.visitors.krl +228 -0
- package/demos/bootstrap/try-it.md +5 -0
- package/demos/child_tasks/README.md +12 -0
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
- package/demos/child_tasks/com.example.task_runner.krl +139 -0
- package/demos/child_tasks/com.example.task_worker.krl +45 -0
- package/demos/child_tasks/try-it.md +5 -0
- package/demos/collection/README.md +13 -0
- package/demos/collection/com.example.collection.bootstrap.krl +148 -0
- package/demos/collection/com.example.collection.krl +95 -0
- package/demos/collection/com.example.collection.report.krl +93 -0
- package/demos/collection/com.example.collection.room.krl +101 -0
- package/demos/collection/try-it.md +6 -0
- package/demos/echo/README.md +11 -0
- package/demos/echo/com.example.echo.bootstrap.krl +84 -0
- package/demos/echo/com.example.echo.krl +73 -0
- package/demos/echo/try-it.md +5 -0
- package/demos/guard_rules/README.md +12 -0
- package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
- package/demos/guard_rules/com.example.archive.krl +213 -0
- package/demos/guard_rules/com.example.archive_store.krl +36 -0
- package/demos/guard_rules/try-it.md +5 -0
- 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/README.md +14 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
- package/demos/kblog/com.example.kblog.config.krl +50 -0
- package/demos/kblog/com.example.kblog.data.krl +75 -0
- package/demos/kblog/com.example.kblog.krl +184 -0
- package/demos/kblog/com.example.kblog.posting.krl +109 -0
- package/demos/kblog/try-it.md +6 -0
- package/demos/layered_rulesets/README.md +13 -0
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
- package/demos/layered_rulesets/com.example.invitations.krl +164 -0
- package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
- package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
- package/demos/layered_rulesets/try-it.md +5 -0
- package/demos/moving_picos/README.md +15 -0
- package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
- package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
- package/demos/score_tracker/README.md +11 -0
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
- package/demos/score_tracker/com.example.score_tracker.krl +162 -0
- package/demos/score_tracker/try-it.md +5 -0
- package/demos/secrets/README.md +12 -0
- package/demos/secrets/com.example.hook_service.krl +120 -0
- package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
- package/demos/secrets/com.example.notifier.krl +138 -0
- package/demos/secrets/try-it.md +5 -0
- package/demos/try-it-order.json +1 -0
- package/demos/two_picos/README.md +12 -0
- package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
- package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
- package/demos/two_picos/try-it.md +5 -0
- package/demos/xmlui/README.md +17 -0
- package/demos/xmlui/com.example.contacts.krl +132 -0
- package/demos/xmlui/com.example.fav_color.krl +39 -0
- package/demos/xmlui/com.example.guestbook.krl +61 -0
- package/demos/xmlui/com.example.hello.krl +19 -0
- package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
- package/demos/xmlui/com.example.thermostat.krl +124 -0
- package/demos/xmlui/temperature_sensors.krl +56 -0
- package/demos/xmlui/try-it.md +5 -0
- package/dist/bundledKrl.js +97 -12
- package/dist/cli.js +7 -1
- package/dist/engineConfig.js +20 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +45 -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 +210 -47
- 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/krl/io.picolabs.xmlui.krl +3 -2
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +6 -4
- 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 +10 -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 +18 -9
- package/public/.DS_Store +0 -0
- package/public/pico-engine-ui.css +1 -1
- package/public/pico-engine-ui.js +26 -25
- package/src/bundledKrl.ts +118 -12
- package/src/cli.ts +8 -2
- package/src/engineConfig.ts +33 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -422
- 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 +266 -51
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Quickstart
|
|
2
|
+
|
|
3
|
+
Install the pico engine, run it, and make a pico say hello. It takes about ten minutes and it's the starting point for every other lesson.
|
|
4
|
+
|
|
5
|
+
## Objectives
|
|
6
|
+
|
|
7
|
+
When you finish you will have:
|
|
8
|
+
|
|
9
|
+
- installed and started the pico engine
|
|
10
|
+
- registered a passkey and met your root pico
|
|
11
|
+
- written, installed, and run a first ruleset, `io.picolabs.hello_world`
|
|
12
|
+
- changed the ruleset and reloaded it with **Flush**
|
|
13
|
+
|
|
14
|
+
You need [Node.js](https://nodejs.org/) 20 or later and a text editor. You don't need to know KRL yet: this lesson only asks you to copy a short ruleset and read it.
|
|
15
|
+
|
|
16
|
+
## Install and start the engine
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install -g pico-engine
|
|
20
|
+
pico-engine
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The engine listens on port 3000 and keeps its data in `~/.pico-engine`. Leave the terminal open: the engine runs until you stop it with Control-C. Starting it again later picks up where it left off, because picos persist.
|
|
24
|
+
|
|
25
|
+
Port, data directory, public URL, logging, and the other settings are in the [operator guide](/pico-engine). You won't need them for the lessons, except if you open the engine from a different host name than `localhost`: passkeys are tied to the address in the browser (see `webauthn` there).
|
|
26
|
+
|
|
27
|
+
## Open the developer UI
|
|
28
|
+
|
|
29
|
+
Browse to <http://localhost:3000>.
|
|
30
|
+
|
|
31
|
+
The first visit has no users yet, so the page asks you to **register a passkey**. A passkey is a login credential kept by your browser, your operating system, or a password manager, such as Touch ID, Windows Hello, or 1Password. Follow the prompt your browser shows. The engine never stores a password.
|
|
32
|
+
|
|
33
|
+
Registering creates your **root pico**. On later visits you sign in with the same passkey. If you delete `~/.pico-engine`, you get a fresh engine with no picos and no passkeys, and you register again.
|
|
34
|
+
|
|
35
|
+
<img src="/lessons/_media/19791878-root-pico.png" alt="The developer UI showing the root pico as a box" width="50%">
|
|
36
|
+
|
|
37
|
+
*The screenshots in this lesson come from an earlier release. Yours will look a little different, but the layout and the steps are the same.*
|
|
38
|
+
|
|
39
|
+
The page shows your root pico as a box. Click it to open its tabs:
|
|
40
|
+
|
|
41
|
+
| Tab | What it's for |
|
|
42
|
+
|-----|---------------|
|
|
43
|
+
| **About** | The pico's id, its parent and children, and its name |
|
|
44
|
+
| **Rulesets** | Install a ruleset on this pico, flush one after you change it |
|
|
45
|
+
| **Channels** | See, create, and edit the pico's channels and their policies |
|
|
46
|
+
| **Logging** | A trace of everything the pico has done, newest first |
|
|
47
|
+
| **Testing** | Send events and queries to the pico from forms |
|
|
48
|
+
| **Relationships** | Relationships with other picos (a later lesson) |
|
|
49
|
+
| **Try It!** | Demos you can run in a new child pico (root pico only, by default) |
|
|
50
|
+
|
|
51
|
+
<img src="/lessons/_media/19791878-root-pico-about.png" alt="The root pico's About tab, with its id, name, and a form to add a child pico" width="50%">
|
|
52
|
+
|
|
53
|
+
Every pico also gets its own box with a small form to **Add** a child pico, with a name and a color. The lessons use a child pico so your root pico stays clean: type a name such as `hello`, click **Add**, and open the new pico.
|
|
54
|
+
|
|
55
|
+
## The hello_world ruleset
|
|
56
|
+
|
|
57
|
+
A **ruleset** is the program a pico runs. It's written in KRL and has a unique ruleset id (the **rid**). Save this as `hello_world.krl`:
|
|
58
|
+
|
|
59
|
+
```krl
|
|
60
|
+
ruleset io.picolabs.hello_world {
|
|
61
|
+
meta {
|
|
62
|
+
name "Hello World"
|
|
63
|
+
description <<
|
|
64
|
+
A first ruleset for the Quickstart
|
|
65
|
+
>>
|
|
66
|
+
author "Phil Windley"
|
|
67
|
+
shares hello
|
|
68
|
+
}
|
|
69
|
+
global {
|
|
70
|
+
/**
|
|
71
|
+
* Greet someone.
|
|
72
|
+
* @param name String "who to greet"
|
|
73
|
+
* @returns String
|
|
74
|
+
*/
|
|
75
|
+
hello = function(name = "world") {
|
|
76
|
+
"Hello " + name
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Answer with a greeting, as a say directive.
|
|
81
|
+
* @attr name String optional "who to greet"
|
|
82
|
+
* @example "Ada" { "name": "Ada" }
|
|
83
|
+
*/
|
|
84
|
+
rule hello_world {
|
|
85
|
+
select when echo hello
|
|
86
|
+
pre {
|
|
87
|
+
my_name = event:attr("name").defaultsTo("world").uc()
|
|
88
|
+
}
|
|
89
|
+
send_directive("say", {"something": "Hello " + my_name})
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
It has three parts:
|
|
95
|
+
|
|
96
|
+
- **`meta`** names the ruleset and lists what it `shares`. Names in `shares` are functions other parties can call as queries. The `description` uses KRL's `<< … >>` quotes, which span lines.
|
|
97
|
+
- **`global`** holds definitions every rule can use. `hello` is a function with a default for its parameter.
|
|
98
|
+
- **`rule hello_world`** says when to run and what to do. `select when echo hello` means "run for events with domain `echo` and type `hello`". The `pre` block declares `my_name` from the event's `name` attribute: `event:attr("name")` is `null` if the attribute is missing, `defaultsTo("world")` fills it in, and `uc()` upper-cases it. Then `send_directive` adds a directive named `say` to the response. A directive is how a rule answers whoever sent the event.
|
|
99
|
+
|
|
100
|
+
`pre` declares names. It doesn't assign: you can't declare the same name twice in one rule.
|
|
101
|
+
|
|
102
|
+
The `/** … */` comments are doc comments. The compiler turns the `@attr`, `@param`, and `@example` tags into the schema that the **Testing** tab uses to build its forms. They don't change what the ruleset does.
|
|
103
|
+
|
|
104
|
+
## Install it
|
|
105
|
+
|
|
106
|
+
You can install from a file on your machine, or from a URL.
|
|
107
|
+
|
|
108
|
+
1. Open the child pico and click its **Rulesets** tab.
|
|
109
|
+
2. Scroll to **Install Ruleset by URL**.
|
|
110
|
+
3. Either enter a URL, or click **Browse…** and pick `hello_world.krl`. Browse reads the file in your browser and stages a temporary `file://` URL on the engine host. This is for local development. You can also type the URL yourself: `file:///Users/you/lessons/hello_world.krl` (the engine must run on the same machine as the file).
|
|
111
|
+
If the ruleset is on GitHub, use the **raw** URL, such as `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/hello_world.krl`, not the page that shows the file.
|
|
112
|
+
4. Leave **Config** as it is and click **Install**.
|
|
113
|
+
|
|
114
|
+
<img src="/lessons/_media/19791878-root-pico-rulesets.png" alt="The Rulesets tab with the install form filled in with a file URL" width="50%">
|
|
115
|
+
|
|
116
|
+
<img src="/lessons/_media/19791878-root-pico-rulesets2.png" alt="The Rulesets tab listing installed rulesets, including io.picolabs.hello_world" width="50%">
|
|
117
|
+
|
|
118
|
+
`io.picolabs.hello_world` now appears in the list of installed rulesets. More on URLs and hosting rulesets: [Tips](/developing/tips).
|
|
119
|
+
|
|
120
|
+
## Try it
|
|
121
|
+
|
|
122
|
+
Open the pico's **Testing** tab. Pick the pico's channel in the **ECI** menu and `io.picolabs.hello_world` in the **Ruleset** menu. The tab lists what the ruleset offers: the `echo:hello` event with an optional `name` attribute, and the `hello` query. The `Ada` preset comes from the rule's `@example` comment.
|
|
123
|
+
|
|
124
|
+
- Send `echo:hello` with `name` set to `Ada`. The result includes a `say` directive: `{"something": "Hello ADA"}`.
|
|
125
|
+
- Run the `hello` query with `name` set to `Ada`. The result is `"Hello Ada"`.
|
|
126
|
+
- Send `echo:hello` with no `name`. You get `Hello WORLD`.
|
|
127
|
+
|
|
128
|
+
The same operations work from outside the developer UI, over HTTP, once the pico has a channel for the purpose. The next lesson creates one. The [Echo demo](/cookbook/echo/) is a close relative of this ruleset, with a page that sends the events for you. Run it from the **Try It!** tab, or follow its [instructions](/cookbook/echo/instructions).
|
|
129
|
+
|
|
130
|
+
## Change it and flush
|
|
131
|
+
|
|
132
|
+
The engine compiles a ruleset once and remembers it. When you change the source, tell the engine to look again:
|
|
133
|
+
|
|
134
|
+
1. Edit `hello_world.krl`. Change `"Hello "` in the rule to `"Howdy "`.
|
|
135
|
+
2. On the child's **Rulesets** tab, find `io.picolabs.hello_world` in the list and click **flush**. The engine fetches the URL again and recompiles.
|
|
136
|
+
3. In **Testing**, send `echo:hello` again. The greeting now says `Howdy`.
|
|
137
|
+
|
|
138
|
+
<img src="/lessons/_media/19791878-root-pico-rulesets3.png" alt="The Rulesets tab with hello_world installed, showing flush and uninstall buttons, the URL, and the ruleset's hash" width="50%">
|
|
139
|
+
|
|
140
|
+
A flush updates every pico that has the ruleset installed. It rereads the ruleset's URL. If you installed with **Browse…**, that URL is the engine's staged copy, not your file, so flush won't see your edit: browse for the changed file again, or install from a `file://` URL you typed, which flush rereads. [Tips](/developing/tips) covers flushing, and how to check KRL from the command line with `krl-check` before you install it.
|
|
141
|
+
|
|
142
|
+
## Troubleshooting
|
|
143
|
+
|
|
144
|
+
- **The Install button does nothing, or shows an error.** The URL didn't load, or the KRL didn't compile. Check the path, and for GitHub use the raw URL.
|
|
145
|
+
- **The ruleset never seems to run.** Open the **Logging** tab and look for the event. If it's there and no rule was selected, check the domain and type. A stray character after the `meta { }` block can stop a ruleset from registering at all, so check it really shows in the installed list.
|
|
146
|
+
- **`Not allowed by channel policy`.** The channel you used doesn't permit that event or query. The Testing tab's ECI menu lists the pico's channels. Try another, or see [Managing channels](/wrangler/channels).
|
|
147
|
+
|
|
148
|
+
## Next steps
|
|
149
|
+
|
|
150
|
+
- [Events and Queries](/lessons/events-and-queries): give the pico a channel of its own, and call it with `curl`.
|
|
151
|
+
- [Pico State](/lessons/pico-state): make the pico remember things.
|
|
152
|
+
- [Persistent Compute Objects](/pico-overview): what picos are, and why.
|
|
153
|
+
- [Cookbook](/cookbook/): worked examples. The **Try It!** tab runs them for you.
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
<small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/19791878/Pico+Engine+Quickstart), and updated for this engine.</small>
|