examples/worker, docs: opt shell commands in by import

Update the worker example and the worker-backend docs to the
import-based command selection. The example imports the curl and
sqlite groups and passes them to WorkerBackend's commands option,
demonstrating that opting a command in is a single import and
opting out is deleting it. The package README, the example README,
and docs/12_worker_backend.md describe the always-on core, the
per-command groups published at @cloudflare/computer/shell/*, the
commands option, and the assembleShellModules helper for callers
that build the Loader callback by hand.

Author: aron-cf

docs/12_worker_backend.md

@@ -249,22 +249,58 @@ network-bound `git` subcommands do. See
 - `src/index.ts` holds the DO and the HTTP surface (the
   `/c/<name>/file/...` and `/c/<name>/exec` routes the container
   example also exposes).
-- No Dockerfile, no build script. The shell bundle ships with
-  `@cloudflare/computer/backends/worker-shell` as `SHELL_MODULES`
-  (a record of module name → source covering the entry plus
-  every code-split chunk); the backend hands the whole record
-  to the Loader callback itself.
+- No Dockerfile, no build script. The shell ships with
+  `@cloudflare/computer/backends/worker-shell` as feature groups: an
+  always-on core (`SHELL_CORE_MODULES`) plus one optional group per
+  command at `@cloudflare/computer/shell/<feature>`. The backend
+  assembles core with whatever groups you opt into and hands the
+  result to the Loader callback itself.
 
-The DO's backend wiring fits in three lines:
+The DO's backend wiring:
 
 ```ts
+import curlModules from "@cloudflare/computer/shell/curl";
+import sqliteModules from "@cloudflare/computer/shell/sqlite";
+
 new WorkerShellBackend({
   loader: env.LOADER,
   workspace: { binding: "ContainerExample", id: ctx.id.toString() },
   ctx,
+  commands: [curlModules, sqliteModules],
 })
 ```
 
 Run with `npm run dev --workspace @example/computer-worker`.
-The same `curl` recipes from the container example work without
-changes.
+The same `curl` recipes from the container example work once
+`curlModules` is passed to `commands`.
+
+## Optional shell commands
+
+Core carries the always-on command set (`cat`, `ls`, `grep`, `sed`,
+`awk`, `sort`, …). The heavier commands are split into optional
+groups that are opt-in by import: import a group from
+`@cloudflare/computer/shell/<feature>` and pass it to the
+`commands` option, and only then does its code enter your bundle.
+
+```ts
+import curlModules from "@cloudflare/computer/shell/curl";
+import htmlToMarkdownModules from "@cloudflare/computer/shell/html-to-markdown";
+
+// commands: [curlModules, htmlToMarkdownModules]
+```
+
+A group you never import is unreachable in your module graph, so
+the bundler drops it — there is no build-time flag to set and no
+default-on cost to opt out of. The full set of optional groups is
+`curl`, `html-to-markdown`, `python`, `sqlite`, `js-exec`, `yq`,
+`file`, `xan`, and `jq`.
+
+`curl` runs on a `SecureFetch` adapter over the isolate's global
+`fetch` — `undici` is redirected to a throwing stub at build time
+and never ships. Egress stays governed by the Dynamic Worker's
+`globalOutbound` (left `null`, i.e. closed), not by the shell, so
+enabling `curl` does not by itself open the network.
+
+Consumers that build the Loader callback by hand (the `fetcher`
+path) assemble the modules table themselves with
+`assembleShellModules([...groups])` from the same package.

examples/worker-shell/README.md

@@ -101,14 +101,32 @@ POST /c/<name>/exec                    { command | argv, cwd?, encoding? }
 
 ## Run it locally
 
-No Docker, no extra build step. The shell ships as a record of
-pre-bundled modules (`SHELL_MODULES`) inside
-`@cloudflare/computer/backends/worker-shell`; `WorkerShellBackend` spreads
-the whole record into the Loader callback internally so the DO
-constructor stays a three-line backend invocation. The entry
-module parses on cold start; the dynamic chunks (python, js-exec,
-sqlite, curl, html-to-markdown) stay cold until a script reaches
-for them.
+No Docker, no extra build step. The shell ships as pre-bundled
+feature groups inside `@cloudflare/computer/backends/worker-shell`: an
+always-on core plus one optional group per command at
+`@cloudflare/computer/shell/<feature>`. `WorkerShellBackend` assembles
+core with whatever groups you pass to its `commands` option and
+spreads the result into the Loader callback internally. This
+example opts `curl` and `sqlite` in:
+
+```ts
+import curlModules from "@cloudflare/computer/shell/curl";
+import sqliteModules from "@cloudflare/computer/shell/sqlite";
+
+new WorkerShellBackend({
+  loader: env.LOADER,
+  workspace: { binding: "ContainerExample", id: ctx.id.toString() },
+  ctx,
+  commands: [curlModules, sqliteModules],
+});
+```
+
+A group you never import (`html-to-markdown`, `python`, `js-exec`,
+`yq`, `file`, `xan`, `jq`, or either of the two above) is
+unreachable in the bundle and the bundler drops it — opting a
+command in is a single import, and opting out is deleting it. The
+core entry module parses on cold start; each opted-in group's
+chunks stay cold until a script reaches for them.
 
 ```sh
 npm run dev --workspace @example/computer-worker-shell

examples/worker-shell/src/index.ts

@@ -36,6 +36,14 @@ import {
   withWorkspace,
 } from "@cloudflare/computer";
 import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
+// Opt-in shell commands. Each import pulls one command group into
+// this Worker's bundle; a group you do not import is unreachable
+// and the bundler drops it. Pass the ones you want to the
+// WorkerShellBackend `commands` option below. Other importable groups:
+// @cloudflare/computer/shell/{html-to-markdown,python,js-exec,yq,
+// file,xan,jq}.
+import curlModules from "@cloudflare/computer/shell/curl";
+import sqliteModules from "@cloudflare/computer/shell/sqlite";
 
 // Re-export so the runtime can wrap WorkspaceServiceProxy into a
 // loopback Fetcher binding. The DO reaches the wrapped class
@@ -60,6 +68,10 @@ export class ContainerExample extends withWorkspace(class extends DurableObject<
         loader: env.LOADER,
         workspace: { binding: "ContainerExample", id: ctx.id.toString() },
         ctx,
+        // Only the groups listed here ship. Core (cat, ls, grep,
+        // sed, …) is always included; drop an import above to
+        // shrink the bundle by that command's cost.
+        commands: [curlModules, sqliteModules],
       }),
     ],
     // Mount the Bucket binding at /workspace/r2. Seed it with

packages/computer/README.md

@@ -122,6 +122,7 @@ Worker backend:
 ```ts
 import { Workspace, WorkspaceServiceProxy } from "@cloudflare/computer";
 import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
+import curlModules from "@cloudflare/computer/shell/curl";
 import { DurableObject } from "cloudflare:workers";
 
 export { WorkspaceServiceProxy };
@@ -134,6 +135,7 @@ export class WorkerExample extends DurableObject<Env> {
         loader: this.env.LOADER,
         workspace: { binding: "WorkerExample", id: this.ctx.id.toString() },
         ctx: this.ctx,
+        commands: [curlModules],
       }),
     ],
   });
@@ -145,6 +147,16 @@ export class WorkerExample extends DurableObject<Env> {
 }
 ```
 
+The worker shell ships as feature groups: an always-on core plus
+one optional group per command at
+`@cloudflare/computer/shell/<feature>`. Import the groups you want
+and pass them to `WorkerShellBackend`'s `commands` option; a group you
+never import is unreachable in your bundle and the bundler drops
+it. The optional groups are `curl`, `html-to-markdown`, `python`,
+`sqlite`, `js-exec`, `yq`, `file`, `xan`, and `jq`. `curl` runs on
+the isolate's global `fetch` (no `undici` in the bundle); egress
+stays governed by the Dynamic Worker's `globalOutbound`.
+
 Filesystem only — no execution backend:
 
 ```ts