@fungi.computer/trellis 0.2.2 → 0.2.3

package/src/runs/timeline-items.ts

@@ -0,0 +1,196 @@
+import {
+  fillReviewText,
+  type LoopPosition,
+  type Node,
+  type WorkflowDefinition,
+} from "@fungi.computer/braid";
+import {
+  stepPosition,
+  stepRow,
+  type NodeState,
+  type RunStep,
+} from "./run-state.js";
+
+/** What the timeline needs to know about one installed App. */
+export type AppDisplay = Readonly<
+  Partial<Record<string, Readonly<{ displayName: string; icon?: string }>>>
+>;
+
+/** One thing that happened in a run, in words a person reads. */
+export type TimelineItem = Readonly<{
+  key: string;
+  state: NodeState;
+  title: string;
+  detail?: string | undefined;
+  /** The installed App that did it, when an App did. */
+  app?: Readonly<{ appId: string; displayName: string; icon?: string }>;
+  durationMs?: number | undefined;
+  media?: Readonly<{ path: string; format: "fungi:image" | "fungi:video" }>;
+  /** Where "Open in <App>" goes. */
+  open?: Readonly<{
+    appId: string;
+    params: readonly Readonly<{ key: string; value: string }>[];
+  }>;
+  /** The recorded step, for the raw ▸ view. */
+  step: RunStep;
+}>;
+
+function scopeOf(definition: WorkflowDefinition, step: RunStep) {
+  if (step.graphId === undefined) return definition;
+  const body = new Map(Object.entries(definition.subgraphs ?? {})).get(
+    step.graphId,
+  );
+  return body ? { ...definition, ...body } : undefined;
+}
+
+/** "18s", "4m", "6m 12s": the same short durations the tool timeline uses. */
+export function formatDuration(ms: number) {
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 1) return "under 1s";
+  if (seconds < 60) return `${String(seconds)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  if (minutes < 60)
+    return rest === 0
+      ? `${String(minutes)}m`
+      : `${String(minutes)}m ${String(rest)}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${String(hours)}h ${String(minutes % 60)}m`;
+}
+
+/** "item 2 · try 3": which Map item and Repeat try a step ran in, when it ran in one. */
+function placeWords(position: LoopPosition) {
+  return position.flatMap((place) =>
+    place.loop === "map"
+      ? [`item ${String(place.index + 1)}`]
+      : place.count > 1
+        ? [`try ${String(place.index + 1)}`]
+        : [],
+  );
+}
+
+/** Join the parts of a muted detail line, leaving out the missing ones. */
+function detailLine(...parts: readonly (string | undefined)[]) {
+  const present = parts.filter(
+    (part): part is string => part !== undefined && part.length > 0,
+  );
+  return present.length > 0 ? present.join(" · ") : undefined;
+}
+
+function decision(node: Extract<Node, { kind: "review" }>, step: RunStep) {
+  const output = "reviewOutput" in step ? step.reviewOutput : undefined;
+  if (output === undefined) return { title: "You answered the review" };
+  const choice = node.choices?.find((item) => item.id === output.choice);
+  const label =
+    choice?.label ??
+    (output.choice === "approved"
+      ? "Approve"
+      : output.choice === "rejected"
+        ? "Reject"
+        : output.choice);
+  const note = output.note.length > 0 ? `“${output.note}”` : undefined;
+  const consequence =
+    choice?.description === undefined
+      ? undefined
+      : fillReviewText(choice.description, stepPosition(step));
+  return { title: `You chose ${label}`, detail: detailLine(consequence, note) };
+}
+
+/**
+ * Turn recorded steps into what a person reads: each App step says what the
+ * App did (its own row when it declared one), each answered review says what
+ * you chose. Plumbing that went well, and steps that never ran, stay out.
+ */
+export function timelineItems(
+  steps: readonly RunStep[],
+  definition: WorkflowDefinition,
+  appDisplay: AppDisplay,
+): TimelineItem[] {
+  const items: TimelineItem[] = [];
+  for (const step of steps) {
+    if (step.state === "queued" || step.state === "skipped") continue;
+    const scope = scopeOf(definition, step);
+    const node = scope?.nodes.find((candidate) => candidate.id === step.nodeId);
+    if (node === undefined) continue;
+    const key = JSON.stringify([
+      step.graphId ?? null,
+      step.nodeId,
+      step.iteration,
+    ]);
+    const base = { key, state: step.state, durationMs: step.durationMs, step };
+    if (node.kind === "review") {
+      // A waiting review is the docked question, not a timeline entry.
+      if (step.state === "complete")
+        items.push({ ...base, ...decision(node, step) });
+      continue;
+    }
+    if (node.kind !== "app") {
+      if (step.state === "failed")
+        items.push({
+          ...base,
+          title: `${node.id} failed`,
+          detail: step.errorMessage ?? step.refusal,
+        });
+      continue;
+    }
+    const appId = new Map(Object.entries(definition.apps)).get(node.app)?.appId;
+    const display = appId === undefined ? undefined : appDisplay[appId];
+    const name = display?.displayName ?? node.app;
+    const app =
+      appId === undefined
+        ? undefined
+        : display?.icon === undefined
+          ? { appId, displayName: name }
+          : { appId, displayName: name, icon: display.icon };
+    const withApp = app === undefined ? base : { ...base, app };
+    if (step.state === "failed") {
+      items.push({
+        ...withApp,
+        title: `${name} could not run ${node.method}`,
+        detail: step.errorMessage ?? step.refusal,
+      });
+      continue;
+    }
+    if (step.state !== "complete") {
+      items.push({ ...withApp, title: `${name} is running ${node.method}` });
+      continue;
+    }
+    const row = stepRow(step);
+    if (row === undefined) {
+      items.push({ ...withApp, title: `${name} ran ${node.method}` });
+      continue;
+    }
+    let item: TimelineItem = {
+      ...withApp,
+      title: row.title,
+      detail: detailLine(...placeWords(stepPosition(step)), row.detail),
+    };
+    if (row.media !== undefined) item = { ...item, media: row.media };
+    if (row.open !== undefined && appId !== undefined)
+      item = { ...item, open: { appId, params: row.open.params } };
+    items.push(item);
+  }
+  return items;
+}
+
+/** Facts for the closing line of a finished run. */
+export function runFinish(
+  steps: readonly RunStep[],
+  items: readonly TimelineItem[],
+  costMilliunits: number | null,
+) {
+  const times = steps.flatMap((step) =>
+    step.recordedAt === undefined ? [] : [step.recordedAt],
+  );
+  const elapsed =
+    times.length > 1 ? Math.max(...times) - Math.min(...times) : undefined;
+  const apps = new Set(
+    items.flatMap((item) => (item.app ? [item.app.appId] : [])),
+  );
+  return {
+    elapsed,
+    apps: apps.size,
+    // Only a recorded, non-zero cost is worth a line.
+    cost: costMilliunits !== null && costMilliunits > 0 ? costMilliunits : null,
+  };
+}

package/src/runs/use-run-summaries.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { WorkflowRunListItem } from "@fungi.computer/workflows-wire";
+import type { WorkflowClient } from "../workflow-client.js";
+import { terminal, type RunStatus } from "./run-state.js";
+
+const READS_AT_ONCE = 4;
+const POLL_MS = 3000;
+
+/**
+ * The status of every listed run, so the list can say which ones need you.
+ * Finished runs are read once; active ones are read again until they end.
+ * A run that cannot be read stays unsorted, with its read error for the list.
+ */
+export function useRunSummaries(
+  client: WorkflowClient,
+  items: readonly WorkflowRunListItem[] | null,
+) {
+  const [runs, setRuns] = useState<Readonly<Record<string, RunStatus>>>({});
+  // A run whose status could not be read says so in the list, not silently unsorted.
+  const [readErrors, setReadErrors] = useState<ReadonlyMap<string, Error>>(
+    new Map(),
+  );
+  const setReadError = useCallback((runId: string, error: Error | null) => {
+    setReadErrors((previous) => {
+      if (error === null && !previous.has(runId)) return previous;
+      const next = new Map(previous);
+      if (error === null) next.delete(runId);
+      else next.set(runId, error);
+      return next;
+    });
+  }, []);
+  // The open run reports its own reads here too, so a run that ended there is not read again.
+  const known = useRef(new Map<string, RunStatus>());
+  const record = useCallback((run: RunStatus) => {
+    known.current.set(run.runId, run);
+    setRuns((previous) => ({ ...previous, [run.runId]: run }));
+  }, []);
+  // A refreshed list of the same runs keeps its reads, so depend on the ids.
+  const ids = items?.map((item) => item.runId).join("\n") ?? "";
+  useEffect(() => {
+    const listed = ids === "" ? [] : ids.split("\n");
+    let active = true;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    async function readAll(due: readonly string[]) {
+      const queue = [...due];
+      await Promise.all(
+        Array.from({ length: READS_AT_ONCE }, async () => {
+          for (let id = queue.shift(); id !== undefined; id = queue.shift()) {
+            try {
+              const run = await client.runStatus(id);
+              if (!active) return;
+              record(run);
+              setReadError(id, null);
+            } catch (cause) {
+              if (active)
+                setReadError(
+                  id,
+                  new Error("This run could not be read.", { cause }),
+                );
+            }
+          }
+        }),
+      );
+    }
+    async function cycle() {
+      const due = listed.filter((runId) => {
+        const run = known.current.get(runId);
+        return (
+          run === undefined ||
+          (run.outcome === "active" && !terminal(run.status))
+        );
+      });
+      if (due.length === 0) return;
+      await readAll(due);
+      if (active) timer = setTimeout(() => void cycle(), POLL_MS);
+    }
+    void cycle();
+    return () => {
+      active = false;
+      clearTimeout(timer);
+    };
+  }, [client, ids, record, setReadError]);
+  return { runs, record, readErrors };
+}

package/src/runs/use-run.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import type { WorkflowClient } from "../workflow-client.js";
+import { terminal, type RunStatus } from "./run-state.js";
+/** Schedule the next read after this one settles; never overlap reads. */
+export function useRun(client: WorkflowClient, runId: string) {
+  const [run, setRun] = useState<RunStatus | null>(null);
+  const [error, setError] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  useEffect(() => {
+    let active = true;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    setRun(null);
+    setError(false);
+    async function read() {
+      try {
+        const next = await client.runStatus(runId);
+        if (!active) return;
+        setRun(next);
+        setError(false);
+        if (next.outcome === "active" && !terminal(next.status))
+          timer = setTimeout(() => void read(), 2000);
+      } catch {
+        if (active) setError(true);
+      }
+    }
+    void read();
+    return () => {
+      active = false;
+      clearTimeout(timer);
+    };
+  }, [client, runId, attempt]);
+  return {
+    run,
+    error,
+    refresh: () => {
+      setAttempt((value) => value + 1);
+    },
+  };
+}

package/templates/bonsai-build-on-merge.json

@@ -0,0 +1,134 @@
+{
+  "id": "bonsai-build-on-merge",
+  "definition": {
+    "format": "fungi.workflow/v1",
+    "title": "Build on merge",
+    "description": "An accepted main push for a registered App starts this Workflow through the Workflows capability. Build the exact accepted commit, verify its completed build and Release provenance, then install with Workflow-owned authority. Every step records its result. A failed build or verification never installs; new permissions preserve the running Release and require owner consent.",
+    "apps": {
+      "bonsai": {
+        "appId": "app_bonsai"
+      }
+    },
+    "input": {
+      "type": "object",
+      "properties": {
+        "appId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "sourceRevision": {
+          "type": "string",
+          "pattern": "^git:[0-9a-f]{40}$",
+          "minLength": 44,
+          "maxLength": 44
+        },
+        "installationId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      },
+      "required": ["appId", "sourceRevision", "installationId"],
+      "additionalProperties": false
+    },
+    "nodes": [
+      {
+        "id": "build",
+        "kind": "app",
+        "app": "bonsai",
+        "method": "apps.build",
+        "methodDigest": "sha256:9be16b868eec164c504a30d37dd3739461fc33bf721699e49566ac2126f0a7fb",
+        "values": {
+          "appId": {
+            "from": {
+              "node": "$input",
+              "port": "appId"
+            }
+          },
+          "sourceRevision": {
+            "from": {
+              "node": "$input",
+              "port": "sourceRevision"
+            }
+          },
+          "installationId": {
+            "from": {
+              "node": "$input",
+              "port": "installationId"
+            }
+          }
+        }
+      },
+      {
+        "id": "verify",
+        "kind": "app",
+        "app": "bonsai",
+        "method": "apps.verifyBuild",
+        "methodDigest": "sha256:0ca6e1984a98c75ff18788dc1997c00496ae84a3723b74004ac325a095f72fb5",
+        "values": {
+          "jobId": {
+            "from": {
+              "node": "build",
+              "port": "jobId"
+            }
+          },
+          "sourceRevision": {
+            "from": {
+              "node": "$input",
+              "port": "sourceRevision"
+            }
+          }
+        }
+      },
+      {
+        "id": "install",
+        "kind": "app",
+        "app": "bonsai",
+        "method": "apps.install",
+        "methodDigest": "sha256:3dcf4113653bf8427bbeb4351fc79649108d4624e3c5aa8a5148d0d323501fc6",
+        "values": {
+          "installationId": {
+            "from": {
+              "node": "$input",
+              "port": "installationId"
+            }
+          },
+          "release": {
+            "from": {
+              "node": "verify",
+              "port": "release"
+            }
+          },
+          "jobId": {
+            "from": {
+              "node": "build",
+              "port": "jobId"
+            }
+          }
+        }
+      }
+    ],
+    "edges": [],
+    "output": {
+      "installation": {
+        "node": "install",
+        "port": "value"
+      }
+    }
+  },
+  "layout": {
+    "build": {
+      "x": 40,
+      "y": 100
+    },
+    "verify": {
+      "x": 340,
+      "y": 100
+    },
+    "install": {
+      "x": 640,
+      "y": 100
+    }
+  }
+}