pico-engine 1.9.4 → 1.9.5

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 (84) hide show
  1. package/README.md +2 -0
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +97 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +85 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +81 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +95 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/kblog/README.md +14 -0
  28. package/demos/kblog/com.example.kblog.bootstrap.krl +132 -0
  29. package/demos/kblog/com.example.kblog.config.krl +50 -0
  30. package/demos/kblog/com.example.kblog.data.krl +75 -0
  31. package/demos/kblog/com.example.kblog.krl +184 -0
  32. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  33. package/demos/kblog/try-it.md +6 -0
  34. package/demos/layered_rulesets/README.md +13 -0
  35. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +84 -0
  36. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  37. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  38. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  39. package/demos/layered_rulesets/try-it.md +5 -0
  40. package/demos/moving_picos/README.md +15 -0
  41. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  42. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  43. package/demos/score_tracker/README.md +11 -0
  44. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +104 -0
  45. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  46. package/demos/score_tracker/try-it.md +5 -0
  47. package/demos/secrets/README.md +12 -0
  48. package/demos/secrets/com.example.hook_service.krl +120 -0
  49. package/demos/secrets/com.example.notifier.bootstrap.krl +127 -0
  50. package/demos/secrets/com.example.notifier.krl +138 -0
  51. package/demos/secrets/try-it.md +5 -0
  52. package/demos/try-it-order.json +1 -0
  53. package/demos/two_picos/README.md +12 -0
  54. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  55. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  56. package/demos/two_picos/com.example.two_picos.bootstrap.krl +131 -0
  57. package/demos/two_picos/try-it.md +5 -0
  58. package/demos/xmlui/README.md +17 -0
  59. package/demos/xmlui/com.example.contacts.krl +132 -0
  60. package/demos/xmlui/com.example.fav_color.krl +39 -0
  61. package/demos/xmlui/com.example.guestbook.krl +61 -0
  62. package/demos/xmlui/com.example.hello.krl +19 -0
  63. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  64. package/demos/xmlui/com.example.thermostat.bootstrap.krl +92 -0
  65. package/demos/xmlui/com.example.thermostat.krl +124 -0
  66. package/demos/xmlui/temperature_sensors.krl +56 -0
  67. package/demos/xmlui/try-it.md +5 -0
  68. package/dist/bundledKrl.js +97 -12
  69. package/dist/cli.js +2 -0
  70. package/dist/engineConfig.js +19 -0
  71. package/dist/index.js +1 -0
  72. package/dist/server.js +14 -0
  73. package/krl/io.picolabs.xmlui.krl +3 -2
  74. package/mcp/docs/CLAUDE.md +3 -2
  75. package/mcp/docs/pico-engine.md +3 -0
  76. package/package.json +6 -3
  77. package/public/.DS_Store +0 -0
  78. package/public/pico-engine-ui.css +1 -1
  79. package/public/pico-engine-ui.js +23 -22
  80. package/src/bundledKrl.ts +118 -12
  81. package/src/cli.ts +2 -0
  82. package/src/engineConfig.ts +28 -0
  83. package/src/index.ts +8 -0
  84. package/src/server.ts +15 -0
package/src/bundledKrl.ts CHANGED
@@ -141,32 +141,138 @@ export function engineKrlRelativeFromUrl(url: string): string | null {
141
141
 
142
142
  if (parsed.protocol === "http:" || parsed.protocol === "https:") {
143
143
  const match = parsed.pathname.match(/^\/krl\/(.+\.krl)$/);
144
- if (match) {
145
- const relativePath = match[1].split("/").join(path.sep);
146
- const candidate = path.join(bundledKrlDir(), relativePath);
147
- if (fs.existsSync(candidate)) {
148
- return match[1];
149
- }
144
+ if (match && resolveEngineKrlFile(match[1])) {
145
+ return match[1];
150
146
  }
151
147
  }
152
148
 
153
149
  return null;
154
150
  }
155
151
 
156
- export function resolveEngineKrlFile(relativePath: string): string | null {
157
- const normalized = relativePath.split("/").join(path.sep);
158
- const candidate = path.resolve(bundledKrlDir(), normalized);
159
- const root = bundledKrlDir();
152
+ /**
153
+ * The demos/ directory: PICO_ENGINE_DEMOS_DIR when set (a copy someone edits
154
+ * and keeps across upgrades), else inside the package when installed from npm
155
+ * (copied at pack time), else the repository root in a checkout.
156
+ */
157
+ export function demosDir(): string | null {
158
+ const override = process.env.PICO_ENGINE_DEMOS_DIR;
159
+ const candidates = [
160
+ ...(override && override.trim() ? [path.resolve(override.trim())] : []),
161
+ path.resolve(__dirname, "..", "demos"),
162
+ path.resolve(__dirname, "..", "..", "..", "demos"),
163
+ ];
164
+ for (const dir of candidates) {
165
+ if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) return dir;
166
+ }
167
+ return null;
168
+ }
169
+
170
+ function fileWithin(root: string, relativePath: string): string | null {
171
+ const candidate = path.resolve(root, relativePath.split("/").join(path.sep));
160
172
  if (
161
173
  candidate.startsWith(root + path.sep) &&
162
- fs.existsSync(candidate) &&
163
- candidate.endsWith(".krl")
174
+ candidate.endsWith(".krl") &&
175
+ fs.existsSync(candidate)
164
176
  ) {
165
177
  return candidate;
166
178
  }
167
179
  return null;
168
180
  }
169
181
 
182
+ /** `relativePath` is under krl/, or under demos/ when it starts with `demos/`. */
183
+ export function resolveEngineKrlFile(relativePath: string): string | null {
184
+ if (relativePath.startsWith("demos/")) {
185
+ const root = demosDir();
186
+ return root ? fileWithin(root, relativePath.slice("demos/".length)) : null;
187
+ }
188
+ return fileWithin(bundledKrlDir(), relativePath);
189
+ }
190
+
191
+ export interface TryItFile {
192
+ rid: string;
193
+ file: string;
194
+ url: string;
195
+ /** Absolute path on the engine's machine, so people can edit it and flush. */
196
+ path: string;
197
+ }
198
+
199
+ export interface TryItDemo {
200
+ rid: string;
201
+ name?: string;
202
+ description?: string;
203
+ /** Folder under demos/, which is also the cookbook page's folder. */
204
+ folder: string;
205
+ url: string;
206
+ path: string;
207
+ docs: string;
208
+ /** demos/<folder>/try-it.md: what to look for and try once the demo runs. */
209
+ notes?: string;
210
+ /** Every .krl in the demo's folder; a running demo's installed rulesets are among them. */
211
+ files: TryItFile[];
212
+ }
213
+
214
+ function readNotes(root: string, folder: string): string | undefined {
215
+ try {
216
+ return fs.readFileSync(path.join(root, folder, "try-it.md"), "utf8");
217
+ } catch {
218
+ return undefined;
219
+ }
220
+ }
221
+
222
+ /** Folder names from demos/try-it-order.json (a JSON array), or none if it is missing or invalid. */
223
+ function tryItOrder(root: string): string[] {
224
+ try {
225
+ const order = JSON.parse(fs.readFileSync(path.join(root, "try-it-order.json"), "utf8"));
226
+ return Array.isArray(order) ? order.filter((f) => typeof f === "string") : [];
227
+ } catch {
228
+ return [];
229
+ }
230
+ }
231
+
232
+ /**
233
+ * Every demos/<folder>/<rid>.bootstrap.krl, for the developer UI's "Try It!" tab.
234
+ * Folders named in demos/try-it-order.json come first, in that order; the rest follow by path.
235
+ */
236
+ export function listTryItDemos(baseUrl: string): TryItDemo[] {
237
+ const root = demosDir();
238
+ if (!root) return [];
239
+ const files: string[] = [];
240
+ for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
241
+ if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
242
+ walkKrlFiles(path.join(root, entry.name), root, files);
243
+ }
244
+ const base = baseUrl.replace(/\/$/, "");
245
+ const fileInfo = (rel: string): TryItFile => ({
246
+ rid: readKrlMeta(path.join(root, rel)).rid,
247
+ file: path.basename(rel),
248
+ url: `${base}/krl/demos/${rel}`,
249
+ path: path.join(root, rel),
250
+ });
251
+ const order = tryItOrder(root);
252
+ const rank = (rel: string) => {
253
+ const i = order.indexOf(rel.split("/")[0]);
254
+ return i < 0 ? order.length : i;
255
+ };
256
+ return files
257
+ .filter((rel) => rel.endsWith(".bootstrap.krl"))
258
+ .sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0))
259
+ .map((rel) => {
260
+ const meta = readKrlMeta(path.join(root, rel));
261
+ const folder = rel.split("/")[0];
262
+ return {
263
+ rid: meta.rid,
264
+ name: meta.name,
265
+ description: meta.description,
266
+ folder,
267
+ url: `${base}/krl/demos/${rel}`,
268
+ path: path.join(root, rel),
269
+ docs: `https://docs.picolabs.io/#/cookbook/${folder}/`,
270
+ notes: readNotes(root, folder),
271
+ files: files.filter((f) => f.split("/")[0] === folder).sort().map(fileInfo),
272
+ };
273
+ });
274
+ }
275
+
170
276
  export function resolveBundledKrlUrl(url: string): string {
171
277
  const relativePath = engineKrlRelativeFromUrl(url);
172
278
  if (!relativePath) {
package/src/cli.ts CHANGED
@@ -81,6 +81,8 @@ Environment (optional; Docker/CI when not set in config file):
81
81
  PICO_ENGINE_LOG_FILE - Log path, or stdout/- / 0 for console-only
82
82
  PICO_ENGINE_LOG_MIRROR - "true"/"1" or "false"/"0" (mirror JSON lines to \$PICO_ENGINE_HOME/pico-engine.log when stdout-only; default on)
83
83
  PICO_ENGINE_LOG_RING - how many recent transactions per pico the Logging tab keeps in memory (default 200; cleared on restart)
84
+ PICO_ENGINE_SHOW_TRYIT_MENU - off, root_only (default), or all: where the Developer UI shows the Try It! tab (config: show_tryit_menu)
85
+ PICO_ENGINE_DEMOS_DIR - directory to serve as demos/ (/krl/demos/) instead of the shipped copy
84
86
  `);
85
87
  process.exit(0);
86
88
  }
@@ -38,6 +38,8 @@ export interface EngineSettings {
38
38
  * Set false on EFS/Fargate to avoid mirror file churn (`PICO_ENGINE_LOG_MIRROR=0`).
39
39
  */
40
40
  logMirror: boolean;
41
+ /** Where the developer UI shows the Try It! tab: on no pico, the root pico only, or every pico. */
42
+ showTryItMenu: ShowTryItMenu;
41
43
  /** Max channel policy for root picos when none stored on the pico (1.8). */
42
44
  defaultRootPolicyCeiling?: PolicyCeiling;
43
45
  /** Deny rules applied on every ECI before per-channel policy (1.8). */
@@ -45,6 +47,20 @@ export interface EngineSettings {
45
47
  globalQueryDeny?: QueryPolicyRule[];
46
48
  }
47
49
 
50
+ export type ShowTryItMenu = "off" | "root_only" | "all";
51
+
52
+ const SHOW_TRY_IT_MENU_VALUES: ShowTryItMenu[] = ["off", "root_only", "all"];
53
+
54
+ function parseShowTryItMenu(val: unknown, source: string): ShowTryItMenu | undefined {
55
+ if (val === undefined) return undefined;
56
+ if (typeof val === "string" && (SHOW_TRY_IT_MENU_VALUES as string[]).includes(val)) {
57
+ return val as ShowTryItMenu;
58
+ }
59
+ throw new Error(
60
+ `${source} must be one of ${SHOW_TRY_IT_MENU_VALUES.join(", ")} (got ${JSON.stringify(val)})`,
61
+ );
62
+ }
63
+
48
64
  export interface EngineSettingsOverrides {
49
65
  home?: string;
50
66
  port?: number;
@@ -59,6 +75,7 @@ export interface EngineSettingsOverrides {
59
75
  logToStdout?: boolean;
60
76
  logFile?: string;
61
77
  logMirror?: boolean;
78
+ showTryItMenu?: ShowTryItMenu;
62
79
  defaultRootPolicyCeiling?: PolicyCeiling;
63
80
  globalEventDeny?: EventPolicyRule[];
64
81
  globalQueryDeny?: QueryPolicyRule[];
@@ -87,6 +104,7 @@ export function defaultEngineSettings(): EngineSettings {
87
104
  wildcardSkyRequireBearer: false,
88
105
  logToStdout: false,
89
106
  logMirror: true,
107
+ showTryItMenu: "root_only",
90
108
  };
91
109
  }
92
110
 
@@ -201,6 +219,8 @@ function parseConfigFile(raw: string): Partial<EngineSettings> {
201
219
  out.logFile = path.resolve(expandHome(o.logFile));
202
220
  }
203
221
  }
222
+ const showTryItMenu = parseShowTryItMenu(o.show_tryit_menu, "show_tryit_menu");
223
+ if (showTryItMenu) out.showTryItMenu = showTryItMenu;
204
224
  const rootCeiling = parsePolicyCeilingFromJson(
205
225
  o.defaultRootPolicyCeiling,
206
226
  "defaultRootPolicyCeiling",
@@ -292,6 +312,11 @@ export function settingsFromEnv(): Partial<EngineSettings> {
292
312
  if (logMirror !== undefined) {
293
313
  out.logMirror = logMirror;
294
314
  }
315
+ const showTryItMenu = parseShowTryItMenu(
316
+ process.env.PICO_ENGINE_SHOW_TRYIT_MENU || undefined,
317
+ "PICO_ENGINE_SHOW_TRYIT_MENU",
318
+ );
319
+ if (showTryItMenu) out.showTryItMenu = showTryItMenu;
295
320
 
296
321
  return out;
297
322
  }
@@ -343,6 +368,9 @@ export function resolveEngineSettings(
343
368
  if (programmatic.logMirror !== undefined) {
344
369
  fromProgrammatic.logMirror = programmatic.logMirror;
345
370
  }
371
+ if (programmatic.showTryItMenu !== undefined) {
372
+ fromProgrammatic.showTryItMenu = programmatic.showTryItMenu;
373
+ }
346
374
  if (programmatic.defaultRootPolicyCeiling !== undefined) {
347
375
  fromProgrammatic.defaultRootPolicyCeiling =
348
376
  programmatic.defaultRootPolicyCeiling;
package/src/index.ts CHANGED
@@ -35,6 +35,7 @@ import { server } from "./server";
35
35
  import {
36
36
  installEngineRuntimeSettings,
37
37
  resolveEngineSettings,
38
+ ShowTryItMenu,
38
39
  } from "./engineConfig";
39
40
  const charwise = require("charwise");
40
41
  const safeJsonCodec = require("level-json-coerce-null");
@@ -104,6 +105,12 @@ export interface PicoEngineConfiguration {
104
105
  */
105
106
  allowSelfSignup?: boolean;
106
107
 
108
+ /**
109
+ * Where the developer UI shows the Try It! tab: "off", "root_only" (default),
110
+ * or "all". Config file key: show_tryit_menu.
111
+ */
112
+ showTryItMenu?: ShowTryItMenu;
113
+
107
114
  /**
108
115
  * Override the WebAuthn ceremony/verification implementation. Intended for
109
116
  * testing with a deterministic authenticator.
@@ -175,6 +182,7 @@ export async function startEngine(
175
182
  rpName: configuration.rpName,
176
183
  origin: configuration.origin,
177
184
  allowSelfSignup: configuration.allowSelfSignup,
185
+ showTryItMenu: configuration.showTryItMenu,
178
186
  defaultRootPolicyCeiling: configuration.defaultRootPolicyCeiling,
179
187
  globalEventDeny: configuration.globalEventDeny,
180
188
  globalQueryDeny: configuration.globalQueryDeny,
package/src/server.ts CHANGED
@@ -8,6 +8,7 @@ import * as path from "path";
8
8
  import {
9
9
  bundledKrlDir,
10
10
  listEngineKrlSources,
11
+ listTryItDemos,
11
12
  resolveEngineKrlFile,
12
13
  } from "./bundledKrl";
13
14
  import {
@@ -383,6 +384,19 @@ export function server(
383
384
  }
384
385
  });
385
386
 
387
+ app.get("/api/try-it", function (req, res, next) {
388
+ try {
389
+ let baseUrl = core.base_url;
390
+ if (!baseUrl) {
391
+ baseUrl = `${req.protocol}://${req.get("host") || "localhost"}`;
392
+ }
393
+ const show = getEngineRuntimeSettings().showTryItMenu;
394
+ res.json({ show, demos: show === "off" ? [] : listTryItDemos(baseUrl) });
395
+ } catch (err) {
396
+ next(err);
397
+ }
398
+ });
399
+
386
400
  app.post("/api/stage-krl", function (req, res, next) {
387
401
  try {
388
402
  const content = req.body?.content;
@@ -426,6 +440,7 @@ export function server(
426
440
  version: engineVersion,
427
441
  hasRoots,
428
442
  allowSelfSignup: auth ? auth.allowSelfSignup() : false,
443
+ showTryItMenu: getEngineRuntimeSettings().showTryItMenu,
429
444
  };
430
445
  if (!auth) {
431
446
  base.eci = uiECI;