@frockbot/computer-host-runtime 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/computer-host-runtime",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "exports": {

package/src/runtime.test.ts

@@ -13,6 +13,13 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, test } from "bun:test";
 import {
+  APPLET_SDK_VERSION,
+  APPLET_SHIM_PATH,
+  appletShimScript,
+  APPLETS_ROOT,
+  APPLETS_RUNTIME_FILES,
+  APPLETS_SDK_FAILURE_PATH,
+  MINIFLARE_VERSION,
   BIN_ROOT,
   BOTS_ROOT,
   boxDoctorScript,
@@ -424,9 +431,10 @@ state running`);
     );
   });
 
-  test("the update runner contains only the runtime and reference phases", () => {
+  test("the update runner replaces files and installs nothing", () => {
     expect(UPDATE_PHASES.map((phase) => phase.name)).toEqual([
       "runtime",
+      "applets",
       "reference",
     ]);
     for (const phase of UPDATE_PHASES) {
@@ -435,6 +443,85 @@ state running`);
     const updateDocument = UPDATE_PHASES.map((phase) => phase.body).join("\n");
     expect(updateDocument).not.toContain("apt-get");
     expect(updateDocument).not.toContain("playwright-core/cli.js install");
+    // An in-place update swaps names over files it owns and reaches no
+    // network: the `applets` phase installs the shim and leaves the SDK's
+    // dependency tree — which an `applet dev` may be running out of — alone.
+    expect(updateDocument).not.toContain("npm install");
+  });
+});
+
+describe("the applets phase", () => {
+  test("installs the Applets runtime after the browser", () => {
+    const names = PROVISION_PHASES.map((phase) => phase.name);
+    expect(names).toEqual([
+      "layout",
+      "packages",
+      "runtime",
+      "browser",
+      "applets",
+      "reference",
+    ]);
+  });
+
+  test("installs miniflare and the SDK into a prefix of their own", () => {
+    const applets = PROVISION_PHASES.find((phase) => phase.name === "applets")!;
+    // Not the runtime root: the browser driver and the Applets runtime are two
+    // dependency trees, and one resolution over both would let an Applets
+    // upgrade move `playwright-core`.
+    expect(applets.body).toContain(
+      `npm install --prefix ${APPLETS_ROOT} --no-audit --no-fund miniflare@${MINIFLARE_VERSION}`,
+    );
+    expect(applets.body).toContain(
+      `npm install --prefix ${APPLETS_ROOT} --no-audit --no-fund @frockbot/applet-sdk@${APPLET_SDK_VERSION}`,
+    );
+    expect(APPLETS_ROOT.startsWith(`${RUNTIME_ROOT}/`)).toBe(true);
+  });
+
+  test("an SDK that cannot be fetched leaves a record and not a failed run", () => {
+    // `@frockbot/applet-sdk` is not on npm yet. A Computer whose SDK could not
+    // be installed still browses, execs, and syncs, so the phase records the
+    // failure for the doctor rather than failing provisioning.
+    const applets = PROVISION_PHASES.find((phase) => phase.name === "applets")!;
+    expect(applets.body).toContain(`> ${APPLETS_SDK_FAILURE_PATH}`);
+    expect(applets.body).toContain(`rm -f ${APPLETS_SDK_FAILURE_PATH}`);
+    expect(boxDoctorScript).toContain("record applets-sdk fail");
+    expect(boxDoctorScript).toContain("record applets-sdk pass");
+  });
+
+  test("runs again rather than once, because the SDK has not shipped", () => {
+    const applets = PROVISION_PHASES.find((phase) => phase.name === "applets")!;
+    expect(applets.always).toBe(true);
+    expect(provisionScript).not.toContain('[ ! -f "$MARKERS/applets"');
+    // Both installs are guarded, so a second run on a provisioned Computer is
+    // two directory tests.
+    expect(applets.body).toContain(`[ ! -d ${APPLETS_ROOT}/node_modules/`);
+  });
+
+  test("puts `applet` on the tenant's PATH, execing the SDK's own binary", () => {
+    // `bin` leads a tenant's PATH after `shims`, and `shims` holds refusals —
+    // this is a real command, so it belongs in `bin`.
+    expect(APPLET_SHIM_PATH).toBe(`${BIN_ROOT}/applet`);
+    expect(appletShimScript).toContain('exec "$APPLET" "$@"');
+    expect(appletShimScript).toContain(
+      `APPLET=${APPLETS_ROOT}/node_modules/.bin/applet`,
+    );
+    // The node shim on the base image re-execs itself for ever without this.
+    expect(appletShimScript).toContain("/etc/profile.d/languages_paths");
+    expect(APPLETS_RUNTIME_FILES[0]!.mode).toBe(0o755);
+    // Declared, so the digest moves when the shim does and an existing
+    // Computer is actually reached by the change.
+    expect(RUNTIME_DOCUMENT_FILES.map((file) => file.path)).toContain(
+      APPLET_SHIM_PATH,
+    );
+  });
+
+  test("the reference set tells a Bot the command exists and where it is", () => {
+    const layout = REFERENCE_DOCS.find(
+      (document) => document.name === "layout.md",
+    );
+    expect(layout?.content).toContain("applet build");
+    expect(layout?.content).toContain(APPLETS_ROOT);
+    expect(layout?.content).toContain("user-packages/applets/source");
   });
 });
 
@@ -1046,6 +1133,8 @@ describe("box-doctor", () => {
         "browser-profile",
         "browser-identity",
         "sync-signal",
+        "applets",
+        "applets-sdk",
         "reference-docs",
         "launcher",
         "clock",

package/src/runtime.ts

@@ -112,6 +112,41 @@ export const PLAYWRIGHT_VERSION = "1.55.0";
  */
 export const PLAYWRIGHT_PLATFORM = "ubuntu24.04-x64";
 
+/**
+ * Where the Applets SDK and its runtime are installed (ADR 0022 decision 7).
+ *
+ * A prefix of its own rather than the runtime root's `node_modules`, because
+ * the browser's `playwright-core` and the SDK's `miniflare` are two unrelated
+ * dependency trees on two unrelated release cadences, and one `npm install`
+ * resolving both would let an Applets upgrade move the browser driver.
+ */
+export const APPLETS_ROOT = `${RUNTIME_ROOT}/applets`;
+/**
+ * The `applet` shim on a tenant's PATH.
+ *
+ * In `bin` rather than `shims`: `shims` holds refusals — the sanctioned-surface
+ * shims that decline a GUI command — and this is the opposite, a real command
+ * a Bot is meant to run. `bin` leads a tenant's PATH after `shims`
+ * (`plugin-fly-sprite/src/computer.ts`, `tenantEnvironment`), so `applet` is
+ * reachable by name from the working directory the Bot already has.
+ */
+export const APPLET_SHIM_PATH = `${BIN_ROOT}/applet`;
+/**
+ * Written when the SDK install failed, and read by the doctor.
+ *
+ * `@frockbot/applet-sdk` is not on npm yet. Its install is therefore guarded:
+ * a Computer whose SDK could not be fetched is a Computer that still browses,
+ * execs, and syncs, so the phase leaves this file and succeeds rather than
+ * failing provisioning over a Package that has not shipped. The doctor turns
+ * the file into a named check, which is where an unshipped SDK belongs — a
+ * reported fact, not a Computer nobody can open.
+ */
+export const APPLETS_SDK_FAILURE_PATH = `${APPLETS_ROOT}/.sdk-unavailable`;
+/** The Applets SDK the Computer authors and previews an Applet with. */
+export const APPLET_SDK_VERSION = "0.1.0";
+/** Pinned with the SDK: `applet dev` embeds this Miniflare, never wrangler. */
+export const MINIFLARE_VERSION = "5.20260828.0-alpha";
+
 /**
  * Everything the Computer's desktop needs from the distribution, and nothing
  * that merely recommends itself.
@@ -848,7 +883,7 @@ export const CLOCK_FLOOR_EPOCH = 1_756_684_800;
  * corrected. The version is compared on every adoption instead, and the whole
  * set is rewritten when it moves. Bump it whenever a document below changes.
  */
-export const REFERENCE_DOCS_VERSION = "2026-09-01.1";
+export const REFERENCE_DOCS_VERSION = "2026-09-03.1";
 
 /**
  * What a Bot reads to debug its own Computer.
@@ -919,6 +954,24 @@ on an image rebuild, a Computer reset, and a host migration. Put working files
 here, never the only copy of anything.
 
 \`/tmp\` is the same story with a shorter life: assume a restart empties it.
+
+## Applets — written here, run somewhere else
+
+Applet source is a durable root like any other:
+\`${DATA_ROOT}/user-packages/applets/source/<appletId>/\`. Write it with the
+ordinary file tools, then use \`applet\` — it is on your PATH:
+
+| Command | What |
+|---|---|
+| \`applet check\` | type-check and lint one Applet |
+| \`applet build\` | write \`<appletId>/dist/\` — this is what a publish reads |
+| \`applet dev\` | run it locally on this Computer and print a URL to open in the browser |
+
+The SDK and its runtime live under \`${APPLETS_ROOT}\`, installed when this
+Computer was provisioned. An Applet **never runs for real here**: \`applet dev\`
+is a preview, and publishing hands the built artifact to the kernel, which runs
+it. If \`applet\` says the SDK is not installed, run the self-check and read the
+\`applets-sdk\` line.
 `,
   },
   {
@@ -1160,6 +1213,37 @@ export const provisionPathPreamble = `if [ -r /etc/profile.d/languages_paths ];
   export PATH
 fi`;
 
+/**
+ * `applet` on a tenant's PATH (ADR 0022 decision 7).
+ *
+ * A shim rather than a symlink, for the same reason every other node entry
+ * point here is: `/.sprite/bin/node` is a bash re-exec shim whose last resort
+ * is `command -v node`, which in a non-login shell finds the shim again and
+ * loops for ever. The preamble puts the real toolchain on PATH first, so the
+ * SDK's own `#!/usr/bin/env node` resolves to a binary.
+ *
+ * A missing SDK is a sentence, not a stack trace: the install is guarded (see
+ * {@link APPLETS_SDK_FAILURE_PATH}), so this is the state a Bot will meet
+ * until `@frockbot/applet-sdk` is published, and it says where to look.
+ */
+export const appletShimScript = `#!/usr/bin/env bash
+set -u
+${provisionPathPreamble}
+APPLET=${APPLETS_ROOT}/node_modules/.bin/applet
+if [ ! -x "$APPLET" ]; then
+  echo "the Applets SDK is not installed at ${APPLETS_ROOT}; run computer_doctor and read the applets-sdk check" >&2
+  exit 127
+fi
+exec "$APPLET" "$@"
+`;
+
+/** The files the `applets` phase installs, with their modes. */
+export const APPLETS_RUNTIME_FILES: readonly {
+  readonly path: string;
+  readonly content: string;
+  readonly mode: number;
+}[] = [{ path: APPLET_SHIM_PATH, content: appletShimScript, mode: 0o755 }];
+
 /**
  * The Computer's self-check (parity row 27).
  *
@@ -1324,6 +1408,23 @@ elif [ "$CONFLICTS" -gt 0 ]; then
 else
   record sync-signal pass "signal $(cat "$SIGNAL" 2>/dev/null), last moved $((NOW - $(stat -c %Y "$SIGNAL"))) s ago, no conflicts"
 fi
+if [ -x ${APPLET_SHIM_PATH} ] && [ -d ${APPLETS_ROOT}/node_modules/miniflare ]; then
+  record applets pass "the Applets runtime is installed under ${APPLETS_ROOT} and \\"applet\\" is on your PATH"
+elif [ -x ${APPLET_SHIM_PATH} ]; then
+  record applets fail "\\"applet\\" is on your PATH but no miniflare is installed under ${APPLETS_ROOT}; \\"applet dev\\" cannot run an Applet"
+else
+  record applets fail "no ${APPLET_SHIM_PATH}; provisioning installs it, and no Applet can be checked, built, or previewed without it"
+fi
+# Named and non-fatal on purpose: \`@frockbot/applet-sdk\` is not published
+# yet, so the provisioning phase's guarded install is expected to fail and
+# leave this file rather than fail the whole run. This is where that shows up.
+if [ -d ${APPLETS_ROOT}/node_modules/@frockbot/applet-sdk ]; then
+  record applets-sdk pass "the Applets SDK is installed under ${APPLETS_ROOT}"
+elif [ -f ${APPLETS_SDK_FAILURE_PATH} ]; then
+  record applets-sdk fail "$(head -n 1 ${APPLETS_SDK_FAILURE_PATH} 2>/dev/null); everything else on this Computer is unaffected"
+else
+  record applets-sdk fail "no Applets SDK under ${APPLETS_ROOT} and no record of an attempt; it installs when this Computer is next provisioned"
+fi
 INSTALLED=$(cat ${REFERENCE_ROOT}/.version 2>/dev/null || echo none)
 if [ "$INSTALLED" = "${REFERENCE_DOCS_VERSION}" ]; then
   record reference-docs pass "${REFERENCE_ROOT} holds version ${REFERENCE_DOCS_VERSION}"
@@ -1501,6 +1602,39 @@ if [ ! -x ${CHROMIUM_PATH} ]; then
   # start-desktop.sh and an upgrade is one relink rather than a script change.
   ln -sfn "$CHROMIUM_BUILD" ${CHROMIUM_PATH}
 fi`,
+  },
+  {
+    name: "applets",
+    label: "installing the Applets SDK",
+    // Version-guarded by its own `[ ! -d ]` tests rather than by a marker, for
+    // the same reason the reference phase is: a marker would make this run
+    // exactly once in a Computer's life, and `@frockbot/applet-sdk` is not on
+    // npm yet — the first run on a Computer provisioned today is expected to
+    // fail its guarded step. Once both trees are present this phase is two
+    // directory tests and a file install, so running it again costs nothing.
+    always: true,
+    // ADR 0022 decision 7: an Applet is authored on the Computer and run in
+    // the loader, so this installs what authoring needs and nothing that runs
+    // an Applet for real. Everything is `npm install --prefix` into a prefix
+    // of this phase's own: no `apt`, no distribution package, no daemon, and
+    // nothing that outlives the command.
+    body: `mkdir -p ${APPLETS_ROOT}
+if [ ! -d ${APPLETS_ROOT}/node_modules/miniflare ]; then
+  npm install --prefix ${APPLETS_ROOT} --no-audit --no-fund miniflare@${MINIFLARE_VERSION}
+fi
+# Guarded, and deliberately not fatal. \`@frockbot/applet-sdk\` is not on npm
+# yet, and a Computer that cannot fetch it is still a Computer: it browses,
+# execs, and syncs. The failure is recorded as a file the doctor reports under
+# \`applets-sdk\` rather than as a phase that fails and leaves the whole
+# provisioning run resumable-but-unfinished.
+if [ ! -d ${APPLETS_ROOT}/node_modules/@frockbot/applet-sdk ]; then
+  if npm install --prefix ${APPLETS_ROOT} --no-audit --no-fund @frockbot/applet-sdk@${APPLET_SDK_VERSION}; then
+    rm -f ${APPLETS_SDK_FAILURE_PATH}
+  else
+    printf '%s\\n' "npm could not install @frockbot/applet-sdk@${APPLET_SDK_VERSION}" > ${APPLETS_SDK_FAILURE_PATH}
+  fi
+fi
+${installDeclaredFiles(APPLETS_RUNTIME_FILES)}`,
   },
   {
     name: "reference",
@@ -1533,6 +1667,16 @@ export const UPDATE_PHASES: readonly {
     label: "Updating the Computer runtime",
     body: PROVISION_PHASES.find((phase) => phase.name === "runtime")!.body,
   },
+  {
+    name: "applets",
+    label: "Updating the Applets command",
+    // The shim and nothing else. The provisioning phase beside it also runs
+    // `npm install`, which is a network fetch into a dependency tree an
+    // `applet dev` may be running out of right now; an in-place update
+    // replaces files atomically and must not do that. A Computer picks up a
+    // newly published SDK on its next provisioning adoption, not here.
+    body: installDeclaredFiles(APPLETS_RUNTIME_FILES),
+  },
   {
     name: "reference",
     label: "Updating the Computer reference",
@@ -1687,6 +1831,7 @@ export const RUNTIME_DOCUMENT_FILES: readonly {
 }[] = [
   { path: PROVISION_SCRIPT, content: provisionScript },
   ...COMPUTER_RUNTIME_FILES,
+  ...APPLETS_RUNTIME_FILES,
   ...REFERENCE_RUNTIME_FILES,
 ];