Class ShellWorker

packages/computer/src/backends/worker-shell/entrypoint.ts:88–262

  | { id: string; seq: number; name: "exit"; value: number };

export class ShellWorker<
  Env extends ShellWorkerEnv = ShellWorkerEnv,
> extends WorkerEntrypoint<Env> {
  // Subclasses override to change the default cwd.
  // ECMAScript module execution uses workspace.runtime; just-bash's Python and JavaScript
  // commands require node:worker_threads and cannot run in workerd.
  protected readonly shellOptions: ShellWorkerOptions = {};
  readonly #executions = new Map<string, AbortController>();

  // Test seam: when set, exec uses this to spawn the command
  // instead of `new Bash({...}).exec(...)`. Real production
  // paths never touch it.
  //
  // The override receives the customCommands list that would
  // have gone into the Bash constructor so tests can assert on
  // it directly — the git command is registered here, and a
  // subclass extraCommands hook would layer onto the same list.
  protected bashFactoryOverride:
    | ((
        command: string,
        options: {
          cwd?: string;
          env?: Record<string, string>;
          stdin?: Uint8Array;
          signal?: AbortSignal;
          customCommands: CustomCommand[];
        },
      ) => Promise<{ stdout: string; stderr: string; exitCode: number }>)
    | undefined;

  /**
   * Subclass hook for registering additional custom commands
   * alongside the built-in `git` command. Symmetric with
   * `shellOptions`: the base class returns an empty list and
   * subclasses override to layer their own commands on top.
   *
   * Called once per `exec` with the live host stub the shell
   * already reached, so subclass commands share that stub's
   * lifetime without needing to refetch.
   */
  protected extraCommands(_ws: HostWorkspaceStub): CustomCommand[] {
    return [];
  }

  override async fetch(_request: Request): Promise<Response> {
    return new Response(
      "ShellWorker is invoked over Workers RPC — dispatch through the Workspace's WorkerShellBackend.",
      { status: 426, headers: { "content-type": "text/plain; charset=utf-8" } },
    );
  }

  async exec(input: ExecInput): Promise<{ id: string; events: ReadableStream<Uint8Array> }> {
    const id = input.id ?? crypto.randomUUID();
    const cwd = input.cwd ?? this.shellOptions.cwd ?? DEFAULT_CWD;
    if (this.#executions.has(id))
      throw createShellError("EEXEC_BUSY", `execution ${id} is running`);
    const controller = new AbortController();
    this.#executions.set(id, controller);