@fungi.computer/shed 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# Shed (`@fungi.computer/shed`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shed opens a terminal on your Computer, with its open ports and running
+processes one click away.
+
+![Shed's terminal on the Computer: the Fungi banner, the light shell prompt in /workspace, and the Ports, Processes and Access controls in the footer](docs/media/terminal.png)
+
+Shed is one of the starter Apps of
+[Oyster](https://github.com/fungi-computer/oyster), the open App host that runs
+on your own Cloudflare account. On Oyster, the Computer is a Linux workspace in
+a Cloudflare Container; Shed runs commands there, not on your laptop.
+
+## What you can do
+
+- Type commands at an instant light prompt (`ls`, `rg TODO`, `jq . package.json`
+  and the like). A command that needs a real Linux process, such as `npm`,
+  `node` or an interactive program, opens the full terminal in its place.
+- Search and recall your last 500 prompt commands while Shed is open.
+- Open **Processes** to see what is running, what has exited and what is
+  uncertain, and stop a running process.
+- Open **Ports**, expose the port your dev server listens on, and preview it
+  beside the terminal.
+- Open **Access** to see which Computer permissions Shed holds.
+
+The Computer is always there as a durable workspace. Its container may be
+stopped; running a command starts it again. Processes end when the container
+stops and do not come back when it starts. Closing Shed does not stop a process.
+
+<img alt="Shed on a phone in the light theme: the light shell prompt in /workspace with the footer controls below" src="docs/media/terminal-phone.png" width="300">
+
+## Get it
+
+Shed installs with the other starter Apps. On a deployed Oyster (see the
+[Oyster quick start](https://github.com/fungi-computer/oyster#quick-start-deploy-your-own-oyster)),
+run:
+
+```sh
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+export OYSTER_OWNER_KEY=<your owner key>
+npx oyster install-apps
+```
+
+The installer clones this repository and the six others, seeds each on your
+Oyster with `git push`, builds them on your Computer and installs them. Sign in
+at `$OYSTER_URL/login` with the owner key and open Shed from the Tourtois
+desktop. Run `install-apps` again to update; each App keeps its data.
+
+Port previews open on a second origin that never carries your sign-in. Oyster
+turns them on when its host sets `OYSTER_PREVIEW_ORIGIN`; without it, **Ports**
+still exposes and removes ports and says that previews are off.
+
+## Change it
+
+Every installed App is also a template you can fork on your own Oyster. Fork
+Shed into a Bonsai repository and clone it with ordinary `git`:
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"appId":"app_shed","name":"my-shed"}' \
+  $OYSTER_URL/apps/bonsai/methods/apps.fork
+git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
+  clone $OYSTER_URL/git/bonsai/my-shed.git
+```
+
+The reply names your fork's App id and repository. Push your edits, open the
+repository in Bonsai and choose **Settings**, then **Build & install** with that
+App id and your commit as `git:<sha>`. Install the Release at `shed` to replace
+the running Shed, or at a new id to keep both.
+
+To work from GitHub instead, fork this repository and point the installer at
+your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
+installer reads all seven starter Apps from that base, so fork them under one
+account.
+
+## Agent tools
+
+Agents call Shed through Oyster's MCP endpoint, or at
+`POST $OYSTER_URL/apps/shed/methods/<name>` with a key; see
+[Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
+
+| Method                                    | What it does                                                                                          |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `runCommand({command, cwd?, timeoutMs?})` | Runs a shell command for up to 45 seconds and returns its exit status and output (64 KiB per stream). |
+| `listProcesses({})`                       | Lists up to 64 processes on the Computer. Starts nothing.                                             |
+| `listPorts({})`                           | Lists up to 64 forwarded ports. Starts nothing.                                                       |
+
+Workflows (see [Trellis](https://github.com/fungi-computer/trellis)) use a
+second set for longer work:
+
+| Method                        | What it does                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `run({command, cwd})`         | Starts one process, logs its output under `/workspace/.fungi/runs/`, and waits until it exits. A retry reuses the same process. |
+| `start` / `stop`              | Start a process without waiting for it, or stop one.                                                                            |
+| `logs({run, offset, length})` | Reads up to 128 KiB of a run's log.                                                                                             |
+| `expose({port})`              | Returns a preview URL for a port that is already exposed.                                                                       |
+
+A workflow step can be given push or read access to one repository. Its command
+then finds a credential-free remote in `$FUNGI_GIT_REMOTE`, for example
+`git push "$FUNGI_GIT_REMOTE" HEAD:refs/heads/main`. Arguments never choose the
+Computer; the host does.
+
+## Build and check
+
+Shed is a React App built with Vite. Its terminal renders with Ghostty and its
+controls come from [Caps](https://github.com/fungi-computer/caps).
+
+```sh
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+[src/shed-app.tsx](src/shed-app.tsx) owns the selected Computer, permissions and
+the process and port lists. [src/light-shell/](src/light-shell/) is the light
+prompt, [src/terminal-panel.tsx](src/terminal-panel.tsx) the full terminal, and
+[src/shed-trays.tsx](src/shed-trays.tsx) the Ports and Processes trays. The
+agent tools are in [backend/methods.ts](backend/methods.ts), and
+[package.json](package.json) declares the permissions the App asks for.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/backend/gills.ts

@@ -0,0 +1,74 @@
+import * as z from "zod";
+import { defineAppGill, type AppBackendGill } from "@fungi.computer/agar/gills";
+import { relativeTime } from "@fungi.computer/gills/presentation";
+import { processPageInputSchema, processPageSchema } from "./process-page.js";
+
+const refused = z.object({ error: z.string() });
+type GillRow = ReturnType<AppBackendGill["rows"]>["rows"][number];
+
+/** Inventory only: this read never starts or stops a process. */
+export const processesGill = defineAppGill({
+  id: "processes",
+  title: "Processes",
+  source: "listProcesses",
+  limit: 20,
+  sizes: ["M", "L"],
+  params: [
+    { key: "computer", label: "Computer", kind: "computer", required: true },
+  ],
+  input: ({ limit, after }): ReturnType<AppBackendGill["input"]> => {
+    const cursor: unknown = after === undefined ? undefined : JSON.parse(after);
+    const input = processPageInputSchema.parse(
+      cursor === undefined ? { limit } : { limit, after: cursor },
+    );
+    return input.after === undefined
+      ? { limit: input.limit }
+      : { limit: input.limit, after: input.after };
+  },
+  rows: (output) => {
+    const identity = { viewId: "processes", title: "Processes" };
+    const refusal = refused.safeParse(output);
+    if (refusal.success)
+      return refusal.data.error === "not_granted"
+        ? {
+            ...identity,
+            state: "error",
+            rows: [],
+            error: "Choose a Computer and allow Shed to run commands.",
+            recovery: { kind: "configure", param: "computer" },
+          }
+        : {
+            ...identity,
+            state: "error",
+            rows: [],
+            error:
+              "The process inventory couldn't be read. Open Shed to check access and refresh.",
+            recovery: { kind: "open" },
+          };
+    const page = processPageSchema.parse(output);
+    if (page.processes.length === 0)
+      return { ...identity, state: "empty", rows: [] };
+    const rows = page.processes.map((process): GillRow => ({
+      id: process.id,
+      title: (process.command || "Process").slice(0, 4096),
+      detail:
+        `${process.cwd ?? "Unknown directory"} · ${relativeTime(process.startedAt)}${process.state === "exited" && process.exitCode !== null ? ` · Exit ${String(process.exitCode)}` : ""}`.slice(
+          0,
+          1024,
+        ),
+      status: {
+        label: process.state,
+        tone:
+          process.state === "running"
+            ? "success"
+            : process.state === "uncertain"
+              ? "warning"
+              : "neutral",
+      },
+      open: { params: [{ key: "process", value: process.id }] },
+    }));
+    return page.next === undefined
+      ? { ...identity, state: "full", rows }
+      : { ...identity, state: "full", rows, next: JSON.stringify(page.next) };
+  },
+});

package/backend/index.ts

@@ -0,0 +1,15 @@
+import { DurableObject } from "cloudflare:workers";
+import { appBackend, type ShedMethodContext } from "./methods.js";
+import { createShedRuns } from "./runs.js";
+class ShedFacet extends DurableObject<ShedMethodContext["env"]> {
+  declare public readonly env: ShedMethodContext["env"];
+  readonly runs;
+  constructor(ctx: DurableObjectState, env: ShedMethodContext["env"]) {
+    super(ctx, env);
+    this.runs = createShedRuns(ctx.storage.sql);
+  }
+  override fetch(): Promise<Response> {
+    return Promise.resolve(new Response(null, { status: 405 }));
+  }
+}
+export const Shed = appBackend.implement(ShedFacet);

package/backend/methods.ts

@@ -0,0 +1,278 @@
+import { processesGill } from "./gills.js";
+import {
+  processPageInputSchema,
+  processPageSchema,
+  pageProcesses,
+} from "./process-page.js";
+import * as z from "zod";
+import { Base64 } from "effect/encoding";
+import { computerPortInputSchema } from "@fungi.computer/computer/operations";
+import {
+  runShedCommand,
+  shedRunCommandInputSchema,
+  shedRunInputSchema,
+  shedStartInputSchema,
+  type ShedComputer,
+  type ShedRuns,
+} from "./runs.js";
+import {
+  runCommandInputSchema,
+  runCommandResultSchema,
+  shedComputerRefusalSchema,
+} from "../src/light-shell/run-command-contract.js";
+import {
+  defineAppBackend,
+  defineAppMethod,
+} from "@fungi.computer/agar/backend-definition";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import {
+  computerPortsOutputSchema,
+  computerProcessSchema,
+  processIdInputSchema,
+  processKillOutputSchema,
+} from "@fungi.computer/computer/operations";
+const empty = z.strictObject({});
+const command = runCommandInputSchema;
+const refusal = shedComputerRefusalSchema;
+const portsReply = z.union([computerPortsOutputSchema, refusal]);
+const processesReply = z.union([processPageSchema, refusal]);
+const commandReply = runCommandResultSchema;
+/** Only scoped inventory and execution bindings enter this runtime-neutral definition. */
+export type ShedMethodContext = Readonly<{
+  runs?: ShedRuns;
+  env: Readonly<{
+    COMPUTER?: Partial<ShedComputer> &
+      Readonly<{
+        ports?(input: Record<string, never>): Promise<WhistleJsonValue>;
+        preview?(input: { port: number }): Promise<z.core.util.JSONType>;
+        processKill?(
+          input: z.output<typeof processIdInputSchema>,
+        ): Promise<z.core.util.JSONType>;
+        read?(input: {
+          path: string;
+          byteOffset: number;
+          byteLength: number;
+        }): Promise<z.core.util.JSONType>;
+        exec?(input: z.output<typeof command>): Promise<WhistleJsonValue>;
+      }>;
+  }>;
+}>;
+const preview = z.strictObject({
+  previewUrl: z.url(),
+  expiresAt: z.number().int().positive(),
+});
+const bytes = z.strictObject({
+  path: z.string(),
+  byteOffset: z.number().int().nonnegative(),
+  content: z.string(),
+  encoding: z.literal("base64"),
+  truncated: z.boolean(),
+});
+export const appBackend = defineAppBackend<ShedMethodContext>({
+  gills: [processesGill],
+  methods: {
+    expose: defineAppMethod({
+      description:
+        "Get an admitted preview URL for a port already exposed on the pinned Computer.",
+      effect: "write",
+      requires: ["computer.execute"],
+      input: computerPortInputSchema,
+      output: preview,
+      handler: async (input, context: ShedMethodContext, caller) => {
+        if (!caller.computerId || !context.env.COMPUTER?.preview)
+          throw new Error("Computer preview access is not granted");
+        // Project the issued URL; preview-row presentation policy stays with the host.
+        return z
+          .object(preview.shape)
+          .parse(await context.env.COMPUTER.preview(input));
+      },
+    }),
+    logs: defineAppMethod({
+      description:
+        "Read up to 128 KiB from a run log, identified by its host call key; offsets and lengths are bytes.",
+      effect: "read",
+      requires: ["computer.readFile"],
+      input: z.strictObject({
+        run: z.string().min(1).max(128),
+        offset: z.number().int().nonnegative().default(0),
+        length: z.number().int().min(1).max(131072).default(131072),
+      }),
+      output: z.union([
+        bytes.extend({ run: z.string() }),
+        z.strictObject({ error: z.enum(["not_found", "ambiguous"]) }),
+      ]),
+      handler: async (input, context: ShedMethodContext, caller) => {
+        if (!caller.computerId || !context.env.COMPUTER?.read || !context.runs)
+          throw new Error("Computer file access is not granted");
+        const log = context.runs.logPath(
+          input.run,
+          caller.computerId,
+          caller.actor,
+        );
+        if ("error" in log) return log;
+        const path = log.path;
+        const reply = bytes.parse(
+          await context.env.COMPUTER.read({
+            path,
+            byteOffset: input.offset,
+            byteLength: input.length,
+          }),
+        );
+        const decoded = Base64.decode(reply.content);
+        if (
+          reply.path !== path ||
+          reply.byteOffset !== input.offset ||
+          decoded._tag === "Failure" ||
+          decoded.success.byteLength > input.length
+        )
+          throw new Error("Invalid Computer log reply");
+        return { ...reply, run: input.run };
+      },
+    }),
+    start: defineAppMethod({
+      description:
+        "Start one process on the pinned Computer and return its process and log path without waiting for exit.",
+      effect: "write",
+      requires: ["computer.execute", "computer.writeFile"],
+      pending: true,
+      input: shedStartInputSchema,
+      output: z.union([
+        z.strictObject({
+          process: computerProcessSchema,
+          logPath: z.string(),
+          port: computerPortInputSchema.shape.port.optional(),
+        }),
+        refusal,
+      ]),
+      handler: (input, context: ShedMethodContext, caller) => {
+        const computer = context.env.COMPUTER;
+        if (
+          !caller.computerId ||
+          !computer?.processStart ||
+          !computer.processes ||
+          !context.runs
+        )
+          throw new Error("Computer access is not granted");
+        if (!caller.idempotencyKey)
+          throw new Error(
+            "A host idempotency key is required to start a process",
+          );
+        const { processStart, processes, workflowGitPass, write } = computer;
+        return context.runs.start(
+          input,
+          caller.computerId,
+          caller.idempotencyKey,
+          caller.actor,
+          {
+            processStart,
+            processes,
+            workflowGitPass,
+            write,
+          },
+        );
+      },
+    }),
+    stop: defineAppMethod({
+      description: "Signal a retained process on the pinned Computer to stop.",
+      effect: "write",
+      requires: ["computer.execute"],
+      input: processIdInputSchema,
+      output: z.union([processKillOutputSchema, refusal]),
+      handler: async (input, context: ShedMethodContext, caller) => {
+        if (!caller.computerId || !context.env.COMPUTER?.processKill)
+          throw new Error("Computer access is not granted");
+        if (!context.runs?.owns(input.id, caller.computerId, caller.actor))
+          return refusal.parse({ error: "not_found" });
+        return z
+          .union([processKillOutputSchema, refusal])
+          .parse(await context.env.COMPUTER.processKill(input));
+      },
+    }),
+    run: defineAppMethod({
+      description:
+        "Run one command on the pinned Computer, retaining a log and polling until it exits.",
+      effect: "write",
+      requires: ["computer.execute", "computer.writeFile"],
+      pending: true,
+      input: shedRunInputSchema,
+      output: z.union([
+        z.strictObject({
+          exitCode: z.number().int(),
+          logPath: z.string(),
+        }),
+        refusal,
+      ]),
+      handler: (input, context: ShedMethodContext, caller) => {
+        const computer = context.env.COMPUTER;
+        if (
+          !caller.computerId ||
+          !computer?.processStart ||
+          !computer.processes ||
+          !context.runs
+        )
+          throw new Error("Computer access is not granted");
+        const { processStart, processes, workflowGitPass, write } = computer;
+        if (!caller.idempotencyKey)
+          throw new Error("A host idempotency key is required to start a run");
+        return context.runs.run(
+          input,
+          caller.computerId,
+          caller.idempotencyKey,
+          caller.actor,
+          { processStart, processes, workflowGitPass, write },
+        );
+      },
+    }),
+
+    listPorts: defineAppMethod({
+      description:
+        "List up to 64 forwarded ports on the attached Computer. This read-only inventory requires computer.execute and starts nothing.",
+      effect: "read",
+      requires: ["computer.execute"],
+      input: empty,
+      output: portsReply,
+      handler: async (input, context, caller) =>
+        caller.computerId === null || !context.env.COMPUTER?.ports
+          ? refusal.parse({ error: "not_granted" })
+          : portsReply.parse(await context.env.COMPUTER.ports(input)),
+    }),
+    listProcesses: defineAppMethod({
+      description:
+        "List up to 64 retained processes on the attached Computer. This read-only inventory requires computer.execute and starts nothing.",
+      effect: "read",
+      requires: ["computer.execute"],
+      input: processPageInputSchema,
+      output: processesReply,
+      handler: async (input, context, caller) => {
+        if (caller.computerId === null || !context.env.COMPUTER?.processes)
+          return refusal.parse({ error: "not_granted" });
+        if (
+          input.after !== undefined &&
+          input.after.computerId !== caller.computerId
+        )
+          return refusal.parse({ error: "invalid" });
+        const inventory = processesReply.parse(
+          await context.env.COMPUTER.processes({}),
+        );
+        return "error" in inventory
+          ? inventory
+          : pageProcesses(inventory, input, caller.computerId);
+      },
+    }),
+    runCommand: defineAppMethod({
+      description:
+        "Execute a shell command on the attached Computer, with an optional absolute cwd and a timeout up to 45 seconds. A Workflow step's admitted gitAccess reaches the command as $FUNGI_GIT_REMOTE with command-local Git credentials. The host mints request identity, owns the per-attachment execution budget and attribution. Each output stream is bounded to the Computer’s 64 KiB byte slice, with up to two extra UTF-8 bytes from a replacement character, and may be truncated.",
+      effect: "write",
+      requires: ["computer.execute", "computer.writeFile"],
+      input: shedRunCommandInputSchema,
+      output: commandReply,
+      handler: async (input, context, caller) => {
+        const computer = context.env.COMPUTER;
+        if (caller.computerId === null || !computer?.exec)
+          return refusal.parse({ error: "not_granted" });
+        const { exec, workflowGitPass, write } = computer;
+        return runShedCommand(input, { exec, workflowGitPass, write });
+      },
+    }),
+  },
+});

package/backend/process-page.ts

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import { processListOutputSchema } from "@fungi.computer/computer/operations";
+
+const process = processListOutputSchema.shape.processes.element;
+const processCursorSchema = z.strictObject({
+  computerId: z.string().min(1).max(256),
+  startedAt: process.shape.startedAt,
+  id: process.shape.id,
+});
+export const processPageInputSchema = z.strictObject({
+  limit: z.number().int().min(1).max(64).default(64),
+  after: processCursorSchema.optional(),
+});
+export const processPageSchema = processListOutputSchema.extend({
+  processes: z
+    .array(process.extend({ command: z.string().max(16384) }))
+    .max(64),
+  next: processCursorSchema.optional(),
+});
+
+/** Keyset pages preserve the Computer inventory's newest-first ordering. */
+export function pageProcesses(
+  inventory: z.output<typeof processPageSchema>,
+  input: z.output<typeof processPageInputSchema>,
+  computerId: string,
+): z.output<typeof processPageSchema> {
+  const after = input.after;
+  const remaining =
+    after === undefined
+      ? inventory.processes
+      : inventory.processes.filter(
+          (item) =>
+            item.startedAt < after.startedAt ||
+            (item.startedAt === after.startedAt && item.id < after.id),
+        );
+  const processes = remaining.slice(0, input.limit);
+  const last = processes.at(-1);
+  return remaining.length > input.limit && last !== undefined
+    ? {
+        processes,
+        next: { computerId, startedAt: last.startedAt, id: last.id },
+      }
+    : { processes };
+}