@fungi.computer/trellis 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,126 @@
-# Temporary Holding Version
+# Trellis (`@fungi.computer/trellis`)
 
-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.
+Trellis builds and runs workflows: typed graphs of your Apps' methods, started
+by hand, on a schedule or by an event.
+
+![The Trellis editor with the Bonsai checks workflow: Workflow input, a Change script node and a Bonsai Checks.report step on the canvas, between the method Palette and the Inspector](docs/media/editor.png)
+
+Trellis 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, each run executes on Cloudflare
+Workflows, and its steps call the same App methods your agents use.
+
+## What you can do
+
+- Drag methods from the **Palette** onto the **Canvas**, wire their typed ports,
+  and set inputs in the **Inspector**. Trellis checks the graph as you edit and
+  marks it **Valid** when it can run.
+- Add review steps, waits, conditions, repeats and maps, or a **Code** node that
+  runs your own JavaScript in a sandbox with a time limit.
+- **Publish** an immutable version, then **Run** it with inputs. Drafts never
+  run.
+- Follow a run in **Runs**: each step's state, outputs, duration and cost, with
+  image and video previews. Approve or reject review steps there; only a person
+  can answer a review.
+- Arm a published version in **Triggers** to start on a schedule, on an App
+  event such as a Bonsai push or merge, or from a webhook, and have it report
+  its ending to one of your chats.
+- Start from **Templates**: Bonsai checks (run `npm test` on each Change and
+  report the result), Build on merge, Review a result, Storyboard (panels from
+  Prints with a review per beat) and Storyboard + Save to git.
+- **Export**, **Import** and **Fork** workflows as JSON.
+
+<img alt="The Trellis editor in the light theme, with a Bonsai Repos.list step and a Workflow input on the canvas" src="docs/media/editor-light.png">
+
+## Get it
+
+Trellis 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 Trellis from the Tourtois
+desktop. Run `install-apps` again to update; each App keeps its data.
+
+## Change it
+
+Every installed App is also a template you can fork on your own Oyster. Fork
+Trellis 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_trellis","name":"my-trellis"}' \
+  $OYSTER_URL/apps/bonsai/methods/apps.fork
+git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
+  clone $OYSTER_URL/git/bonsai/my-trellis.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 `trellis` to
+replace the running Trellis, 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.
+
+## How workflows are stored
+
+Drafts live in Trellis's own SQLite database and save as you edit. Publishing
+writes `workflows/<id>.json` to the installation's `trellis` git repository and
+tags it `<id>@v<n>`, so every version that ever ran stays readable. Pick an old
+version in the version menu and choose **Restore as draft** to edit it again. A
+run records the exact version it started from, and Oyster checks the caller's
+permissions again before each step.
+
+## Agent tools
+
+Agents call Trellis through Oyster's MCP endpoint, or at
+`POST $OYSTER_URL/apps/trellis/methods/<name>` with a key; see
+[Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
+
+| Method                                               | What it does                                                                       |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `catalog`                                            | Lists your installed Apps' methods, or one App's full port types.                  |
+| `listWorkflows` / `loadWorkflow`                     | Lists the library, or reads one workflow.                                          |
+| `saveDraft`                                          | Saves a draft, with a revision check so concurrent edits never clobber each other. |
+| `publishWorkflow` / `listVersions` / `revertDraft`   | Publishes a version, lists versions, or restores one as a draft.                   |
+| `runWorkflow`                                        | Runs a published version, optionally reporting the ending to a chat.               |
+| `listRuns` / `runStatus` / `cancel`                  | Lists runs, reads one run's steps and reviews, or cancels it.                      |
+| `arm` / `armEventTrigger` and their `disarm` pairs   | Arms or disarms a schedule or an App-event trigger.                                |
+| `exportWorkflow` / `importWorkflow` / `forkWorkflow` | Moves workflows in and out as JSON, or copies one.                                 |
+
+`answerReview` exists too, but only a person can answer a review.
+
+## Build and check
+
+Trellis is a React App built with Vite. The canvas uses React Flow, the panes
+[Maosaico](https://github.com/fungi-computer/maosaico) and the controls
+[Caps](https://github.com/fungi-computer/caps).
+
+```sh
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+[src/editor/](src/editor/) is the graph editor, [src/runs/](src/runs/) the run
+view and reviews, and [src/triggers/](src/triggers/) the trigger page.
+[backend/library.ts](backend/library.ts) owns drafts and publication, and
+[templates/](templates/) holds the bundled templates as JSON. The agent tools
+are in [backend/methods.ts](backend/methods.ts) and
+[backend/library-methods.ts](backend/library-methods.ts), and
+[package.json](package.json) declares the permissions the App asks for.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/backend/catalog.ts

@@ -0,0 +1,58 @@
+import * as S from "effect/Schema";
+import { catalogSchema, type Catalog } from "@fungi.computer/braid";
+import type { WorkflowMethodContext } from "./methods.js";
+import { catalogReplySchema } from "@fungi.computer/workflows-wire";
+export { catalogReplySchema } from "@fungi.computer/workflows-wire";
+
+/** The unique App ids a definition's node bindings actually name. */
+export function definitionAppIds(definition: {
+  readonly apps: Readonly<Record<string, { readonly appId: string }>>;
+}): string[] {
+  return [...new Set(Object.values(definition.apps).map((app) => app.appId))];
+}
+
+/**
+ * The host selects member or lifecycle authority; the App never invents
+ * grants. Reads the palette index once to resolve installations, then reads
+ * each named App's full ports only -- never the whole installed set -- so a
+ * large installed-App count never grows this reply with ports no caller asked
+ * for.
+ */
+export async function readWorkflowCatalog(
+  workflows: WorkflowMethodContext["env"]["WORKFLOWS"],
+  appIds: readonly string[],
+): Promise<Catalog | null> {
+  const needed = new Set(appIds);
+  // No App is named: skip the read entirely, not just the port detail --
+  // never requiring the WORKFLOWS binding just to save an App-free draft.
+  if (needed.size === 0) return {};
+  if (!workflows) return null;
+  const index = catalogReplySchema.parse(await workflows.catalog({}));
+  if (!("apps" in index)) return null;
+  const matches = index.apps.filter((app) => needed.has(app.appId));
+  const entries = await Promise.all(
+    matches.map(async (match) => {
+      const full = catalogReplySchema.parse(
+        await workflows.catalog({ installationId: match.installationId }),
+      );
+      return "app" in full ? full.app : null;
+    }),
+  );
+  return S.decodeUnknownSync(catalogSchema)(
+    Object.fromEntries(
+      entries.flatMap((app) =>
+        app === null
+          ? []
+          : [
+              [
+                app.appId,
+                app.events === undefined
+                  ? { methods: app.methods }
+                  : { methods: app.methods, events: app.events },
+              ] as const,
+            ],
+      ),
+    ),
+    { onExcessProperty: "error" },
+  );
+}

package/backend/gills.ts

@@ -0,0 +1,56 @@
+import { defineAppGill, type AppBackendGill } from "@fungi.computer/agar/gills";
+import { libraryListing } from "@fungi.computer/workflows-wire";
+
+type GillRow = ReturnType<AppBackendGill["rows"]>["rows"][number];
+
+/** The installation's saved library supplies one page, without a Git rebuild. */
+export const workflowLibraryGill = defineAppGill({
+  id: "workflow-library",
+  title: "Workflow Library",
+  source: "listWorkflows",
+  limit: 20,
+  sizes: ["M", "L"],
+  input: ({ limit, after }): ReturnType<AppBackendGill["input"]> =>
+    after === undefined ? { limit } : { limit, after },
+  rows: (output) => {
+    const identity = { viewId: "workflow-library", title: "Workflow Library" };
+    const page = libraryListing.parse(output);
+    if ("kind" in page)
+      return {
+        ...identity,
+        state: "error",
+        rows: [],
+        error:
+          "The saved Workflow library isn't ready. Open Trellis to update it.",
+        recovery: { kind: "open" },
+      };
+    if (page.items.length === 0)
+      return { ...identity, state: "empty", rows: [] };
+    const rows = page.items.map((item): GillRow => {
+      const row: GillRow = {
+        id: item.workflowId,
+        title: item.title.trim() || "Untitled Workflow",
+        status:
+          item.published === null
+            ? {
+                label: item.draftRevision === null ? "Not published" : "Draft",
+                tone: "neutral",
+              }
+            : {
+                label:
+                  item.published.version === null
+                    ? "Published"
+                    : `Published v${String(item.published.version)}`,
+                tone: "success",
+              },
+        open: { params: [{ key: "workflow", value: item.workflowId }] },
+      };
+      return item.draftRevision === null
+        ? row
+        : { ...row, detail: "Draft available" };
+    });
+    return page.next === undefined
+      ? { ...identity, state: "full", rows }
+      : { ...identity, state: "full", rows, next: page.next };
+  },
+});

package/backend/index.ts

@@ -0,0 +1,40 @@
+import type { AppGitPushFact } from "@fungi.computer/agar/git";
+import { DurableObject } from "cloudflare:workers";
+import { appBackend, type WorkflowMethodContext } from "./methods.js";
+import { readWorkflowCatalog } from "./catalog.js";
+import { onWorkflowGitPush } from "./push.js";
+import { createWorkflowIndexes } from "./indexes.js";
+import {
+  backgroundSyncRefusalSchema,
+  type BackgroundSyncRefusal,
+} from "@fungi.computer/puffball/background-replay";
+
+class WorkflowFacet extends DurableObject<WorkflowMethodContext["env"]> {
+  declare public readonly env: WorkflowMethodContext["env"];
+  readonly indexes;
+  constructor(ctx: DurableObjectState, env: WorkflowMethodContext["env"]) {
+    super(ctx, env);
+    this.indexes = createWorkflowIndexes(ctx.storage);
+  }
+  async onGitPush(fact: AppGitPushFact): Promise<void> {
+    if (!this.env.GIT) throw new Error("Git access is not granted");
+    await onWorkflowGitPush(
+      {
+        git: this.env.GIT,
+        indexes: this.indexes,
+        catalog: (appIds) => readWorkflowCatalog(this.env.WORKFLOWS, appIds),
+      },
+      fact,
+    );
+  }
+  async syncRefused(input: BackgroundSyncRefusal): Promise<void> {
+    await this.indexes.publicationJobs.refused(
+      backgroundSyncRefusalSchema.parse(input),
+    );
+  }
+  override fetch(): Promise<Response> {
+    return Promise.resolve(new Response(null, { status: 405 }));
+  }
+}
+
+export const Trellis = appBackend.implement(WorkflowFacet);