@fungi.computer/trellis 0.0.0-stage → 0.0.1

package/backend/push.ts

@@ -0,0 +1,287 @@
+import {
+  countingGit,
+  ReadCopyBudgetExceeded,
+} from "@fungi.computer/agar/read-copy";
+import { validate, type Catalog } from "@fungi.computer/braid";
+import {
+  dispatchAppGitPush,
+  type AppGitPushFact,
+  type GitBinding,
+} from "@fungi.computer/agar/git";
+import {
+  changedWorkflowIds,
+  listingGit,
+  versionRefs,
+  inspectWorkflowFile,
+} from "@fungi.computer/workflows-wire";
+import { definitionAppIds } from "./catalog.js";
+import type { WorkflowIndexes, WorkflowPushIssue } from "./indexes.js";
+
+/** Accepted push facts invalidate the list and refresh validation; they cannot start runs. */
+export async function onWorkflowGitPush(
+  {
+    git,
+    indexes,
+    catalog,
+  }: {
+    git: GitBinding;
+    indexes: WorkflowIndexes;
+    catalog: (appIds: readonly string[]) => Promise<Catalog | null>;
+  },
+  raw: AppGitPushFact,
+): Promise<void> {
+  await dispatchAppGitPush(
+    {
+      onGitPush: async (fact) => {
+        if (fact.repository !== "trellis") return;
+        const updates = fact.updates.filter(
+          (update) =>
+            update.ref === "refs/heads/main" ||
+            update.ref.startsWith("refs/tags/"),
+        );
+        if (updates.length === 0 && !fact.unexplained?.length) return;
+        const snapshot = indexes.librarySnapshot();
+        if (
+          snapshot.snapshot &&
+          updates.every(
+            (update) => snapshot.snapshot?.refs[update.ref] === update.after,
+          ) &&
+          !fact.unexplained?.length
+        )
+          return;
+        indexes.invalidateLibrary();
+        const revision = indexes.librarySnapshot().revision;
+        const controller = new AbortController();
+        const counted = countingGit(git, {
+          limit: 40,
+          signal: controller.signal,
+        });
+        const source = listingGit(counted.git);
+        // Accumulates only the App ids this push's own files actually name;
+        // a later file in the same push extends it instead of refetching.
+        let known: Catalog | null = null;
+        const catalogFor = async (appIds: readonly string[]) => {
+          const current = known;
+          if (current === null) {
+            known = await catalog(appIds);
+            return known;
+          }
+          const missing = appIds.filter((id) => !(id in current));
+          if (missing.length === 0) return current;
+          const fetched = await catalog(missing);
+          if (fetched === null) {
+            known = null;
+            return null;
+          }
+          known = { ...current, ...fetched };
+          return known;
+        };
+        const zero = "0".repeat(40);
+        const nextRefs = new Map(Object.entries(snapshot.snapshot?.refs ?? {}));
+        const items = [...(snapshot.snapshot?.items ?? [])];
+        const invalidate = () => {
+          for (const item of snapshot.snapshot?.items ?? []) {
+            indexes.documents.stale(`main:${item.workflowId}`);
+            indexes.versionCopies.stale(item.workflowId);
+          }
+          indexes.invalidateLibrary();
+        };
+        try {
+          if (fact.unexplained?.length) {
+            invalidate();
+            return;
+          }
+          const recorded = new Set(
+            indexes
+              .issues(fact.eventId)
+              .map((row) => `${row.commit}:${row.workflowId}`),
+          );
+          for (const update of updates) {
+            if (update.ref !== "refs/heads/main") continue;
+            for (const workflowId of await changedWorkflowIds(
+              source,
+              update.before,
+              update.after,
+            )) {
+              const key = `${update.after}:${workflowId}`;
+              if (recorded.has(key)) continue;
+              const file = await inspectWorkflowFile(
+                source,
+                workflowId,
+                update.after,
+              );
+              const issues: WorkflowPushIssue[] =
+                file.kind === "invalid" ? [...file.issues] : [];
+              if (file.kind !== "missing") {
+                const needed =
+                  file.kind === "valid"
+                    ? definitionAppIds(file.draft.definition)
+                    : [];
+                const resolved = await catalogFor(needed);
+                if (resolved === null)
+                  issues.push({
+                    code: "catalog_unavailable",
+                    message:
+                      "App-method validation requires the lifecycle installation catalog",
+                  });
+                else if (file.kind === "valid")
+                  issues.push(...validate(file.draft.definition, resolved));
+              }
+              if (indexes.librarySnapshot().revision !== revision) return;
+              indexes.recordIssues(
+                fact.eventId,
+                update.after,
+                workflowId,
+                issues,
+              );
+              recorded.add(key);
+              const scope = "main";
+              const copied = indexes.documents.read(`${scope}:${workflowId}`);
+              const known =
+                (snapshot.snapshot?.refs[update.ref] ?? zero) ===
+                  update.before ||
+                (copied.kind === "ready" && copied.head === update.after);
+              if (!known) {
+                invalidate();
+                return;
+              }
+              if (update.after === zero) {
+                indexes.documents.stale(`${scope}:${workflowId}`);
+                const remaining = indexes.drafts.read(workflowId);
+                const position = items.findIndex(
+                  (item) => item.workflowId === workflowId,
+                );
+                if (remaining) {
+                  const row = {
+                    workflowId,
+                    title: remaining.definition.title,
+                    draftRevision: remaining.revision,
+                    published: null,
+                  };
+                  if (position < 0) items.push(row);
+                  else items[position] = row;
+                } else if (position >= 0) items.splice(position, 1);
+                continue;
+              }
+              const doc =
+                file.kind === "valid"
+                  ? { ...file.draft, commit: update.after }
+                  : null;
+              indexes.documents.write(
+                `${scope}:${workflowId}`,
+                update.after,
+                doc,
+              );
+              if (doc)
+                indexes.documents.write(
+                  `at:${workflowId}:${update.after}`,
+                  update.after,
+                  doc,
+                );
+              const position = items.findIndex(
+                (item) => item.workflowId === workflowId,
+              );
+              const draft = indexes.drafts.read(workflowId);
+              const title =
+                draft?.definition.title ?? doc?.definition.title ?? null;
+              if (title !== null) {
+                const row = {
+                  workflowId,
+                  title,
+                  draftRevision: draft?.revision ?? null,
+                  published: doc
+                    ? { commit: update.after, version: null }
+                    : null,
+                };
+                if (position < 0) items.push(row);
+                else items[position] = row;
+              } else if (position >= 0) items.splice(position, 1);
+            }
+            if (update.after === zero) nextRefs.delete(update.ref);
+            else nextRefs.set(update.ref, update.after);
+          }
+          for (const update of updates) {
+            if (!update.ref.startsWith("refs/tags/")) continue;
+            const candidateIds = items.map((item) => item.workflowId);
+            const selected = candidateIds.flatMap((workflowId) =>
+              versionRefs(workflowId, [
+                { name: update.ref, hash: update.after },
+              ]).map((tag) => ({ workflowId, ...tag })),
+            )[0];
+            if (!selected) continue;
+            const { workflowId, version } = selected;
+            const copied = indexes.versionCopies.read(workflowId);
+            if (copied.kind !== "ready") {
+              indexes.versionCopies.stale(workflowId);
+              continue;
+            }
+            if (update.after === zero) {
+              indexes.versionCopies.stale(workflowId);
+              nextRefs.delete(update.ref);
+              const row = items.find((item) => item.workflowId === workflowId);
+              if (row?.published?.version === version)
+                row.published.version = null;
+              continue;
+            }
+            if (
+              copied.value.some(
+                (item) =>
+                  item.version === version && item.commit === update.after,
+              )
+            )
+              continue;
+            if (
+              update.before !== zero &&
+              !copied.value.some(
+                (item) =>
+                  item.version === version && item.commit === update.before,
+              )
+            ) {
+              indexes.versionCopies.stale(workflowId);
+              continue;
+            }
+            const metadata = await source.readCommit(
+              fact.repository,
+              update.after,
+            );
+            if (indexes.librarySnapshot().revision !== revision) return;
+            if (!metadata) {
+              indexes.versionCopies.stale(workflowId);
+              continue;
+            }
+            indexes.versionCopies.write(
+              workflowId,
+              update.after,
+              [
+                ...copied.value.filter((item) => item.version !== version),
+                {
+                  version,
+                  commit: update.after,
+                  committedAt: metadata.committedAt,
+                  message: metadata.message,
+                },
+              ].sort((a, b) => b.version - a.version),
+            );
+            const row = items.find((item) => item.workflowId === workflowId);
+            if (row?.published?.commit === update.after)
+              row.published.version = version;
+            nextRefs.set(update.ref, update.after);
+          }
+          if (snapshot.snapshot)
+            indexes.recordLibrary(revision, {
+              refs: Object.fromEntries(nextRefs),
+              items: items
+                .sort((a, b) => a.workflowId.localeCompare(b.workflowId))
+                .slice(0, 100),
+            });
+        } catch (error) {
+          if (!(error instanceof ReadCopyBudgetExceeded)) throw error;
+          invalidate();
+        } finally {
+          controller.abort();
+        }
+      },
+    },
+    raw,
+  );
+}

package/backend/schedule-methods.ts

@@ -0,0 +1,120 @@
+import {
+  triggerTargetSchema,
+  scheduleArmReplySchema,
+  triggerDisarmReplySchema,
+  schedulesReplySchema,
+  scheduleDisarmInputSchema,
+  eventDisarmInputSchema,
+  triggerListInputSchema,
+  eventArmReplySchema,
+  eventTriggersReplySchema,
+  type WorkflowTriggerTarget,
+} from "@fungi.computer/workflows-wire";
+import { defineAppMethod } from "@fungi.computer/agar/backend-definition";
+import { createWorkflowLibrary } from "./library.js";
+import { readWorkflowCatalog } from "./catalog.js";
+import type { WorkflowMethodContext } from "./methods.js";
+
+const granted = (context: WorkflowMethodContext) => {
+  if (!context.env.WORKFLOWS) throw new Error("Workflow access is not granted");
+  return context.env.WORKFLOWS;
+};
+
+/** Read only this App's immutable publication rows; no Git repair occurs in arming. */
+function publication(
+  context: WorkflowMethodContext,
+  target: WorkflowTriggerTarget,
+) {
+  if (context.indexes === undefined) return null;
+  return createWorkflowLibrary({
+    index: context.indexes,
+    author: { name: "Trellis", email: "trellis@app.local" },
+    catalog: async (appIds) => {
+      const catalog = await readWorkflowCatalog(context.env.WORKFLOWS, appIds);
+      if (catalog === null) throw new Error("Workflow catalog unavailable");
+      return catalog;
+    },
+  }).publishedRow(target.workflowId, { commit: target.commit });
+}
+
+const unavailablePublication = {
+  kind: "refused" as const,
+  reason: "Workflow publication is unavailable; re-arm after publishing",
+};
+
+export const scheduleMethods = {
+  arm: defineAppMethod({
+    description:
+      "Arm a published Workflow schedule as you on the pinned Computer. An optional delivery chat receives every run's ending.",
+    effect: "write",
+    requires: ["workflow.run", "workflow.arm"],
+    input: triggerTargetSchema,
+    output: scheduleArmReplySchema,
+    handler: async (input, context: WorkflowMethodContext) => {
+      const workflows = granted(context);
+      const stored = publication(context, input);
+      if (stored === null) return unavailablePublication;
+      return scheduleArmReplySchema.parse(
+        await workflows.armSchedule({ ...input, digest: stored.digest }),
+      );
+    },
+  }),
+  disarm: defineAppMethod({
+    description: "Cancel an armed Workflow schedule.",
+    effect: "write",
+    requires: ["workflow.run", "workflow.arm"],
+    input: scheduleDisarmInputSchema,
+    output: triggerDisarmReplySchema,
+    handler: async (input, context: WorkflowMethodContext) =>
+      triggerDisarmReplySchema.parse(
+        await granted(context).disarmSchedule(input),
+      ),
+  }),
+  listTriggers: defineAppMethod({
+    description:
+      "List this installation's schedules, next run times and paused reasons.",
+    effect: "read",
+    requires: ["workflow.run"],
+    input: triggerListInputSchema,
+    output: schedulesReplySchema,
+    handler: async (_input, context: WorkflowMethodContext) =>
+      schedulesReplySchema.parse(await granted(context).schedules({})),
+  }),
+  armEventTrigger: defineAppMethod({
+    description:
+      "Arm a published Workflow App-event trigger as you on the pinned Computer. An optional delivery chat receives every run's ending.",
+    effect: "write",
+    requires: ["workflow.run", "workflow.arm"],
+    input: triggerTargetSchema,
+    output: eventArmReplySchema,
+    handler: async (input, context: WorkflowMethodContext) => {
+      const workflows = granted(context);
+      const stored = publication(context, input);
+      if (stored === null) return unavailablePublication;
+      return eventArmReplySchema.parse(
+        await workflows.armEventTrigger({ ...input, digest: stored.digest }),
+      );
+    },
+  }),
+  disarmEventTrigger: defineAppMethod({
+    description: "Disarm this installation's App-event trigger.",
+    effect: "write",
+    requires: ["workflow.run", "workflow.arm"],
+    input: eventDisarmInputSchema,
+    output: triggerDisarmReplySchema,
+    handler: async (input, context: WorkflowMethodContext) =>
+      triggerDisarmReplySchema.parse(
+        await granted(context).disarmEventTrigger(input),
+      ),
+  }),
+  eventTriggers: defineAppMethod({
+    description:
+      "List this installation's App-event triggers and paused reasons.",
+    effect: "read",
+    requires: ["workflow.run"],
+    input: triggerListInputSchema,
+    output: eventTriggersReplySchema,
+    handler: async (_input, context: WorkflowMethodContext) =>
+      eventTriggersReplySchema.parse(await granted(context).eventTriggers({})),
+  }),
+};

package/backend/share.ts

@@ -0,0 +1,221 @@
+import { workflowIdSchema } from "@fungi.computer/braid";
+import * as S from "effect/Schema";
+import * as Result from "effect/Result";
+import type * as z from "zod";
+import { gitSha1Schema } from "@fungi.computer/puffball/git-representation";
+import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
+import {
+  workflowDefinitionSchema,
+  validate,
+  type Catalog,
+  type WorkflowDefinition,
+  type Issue,
+} from "@fungi.computer/braid";
+import {
+  provenanceSchema,
+  shareReview,
+  shareCopyReply,
+  shareExportReply,
+} from "@fungi.computer/workflows-wire";
+import type { WorkflowDraft } from "@fungi.computer/workflows-wire";
+import type { createWorkflowLibrary } from "./library.js";
+
+const workflowId = S.declare(
+  (value): value is string => workflowIdSchema.safeParse(value).success,
+);
+const commit = S.declare(
+  (value): value is string => gitSha1Schema.safeParse(value).success,
+);
+export const shareBundleSchema = S.Struct({
+  format: S.Literal("fungi.workflow-share/v1"),
+  definition: workflowDefinitionSchema,
+  layout: S.Record(S.String, S.Struct({ x: S.Finite, y: S.Finite })),
+  source: S.Struct({
+    workflowId,
+    version: S.Number.pipe(S.check(S.isInt()), S.check(S.isGreaterThan(0))),
+    commit,
+    origin: S.optionalKey(S.String.pipe(S.check(S.isMaxLength(256)))),
+  }),
+});
+type Bundle = typeof shareBundleSchema.Type;
+type Provenance = z.output<typeof provenanceSchema>;
+const maxShareBytes = 512 * 1024;
+
+function review(definition: WorkflowDefinition, catalog: Catalog) {
+  const graphs = [
+    { id: "root", graph: definition },
+    ...Object.entries(definition.subgraphs ?? {}).map(([id, graph]) => ({
+      id,
+      graph,
+    })),
+  ];
+  return shareReview.parse({
+    gitAccess: graphs.flatMap(({ id, graph }) =>
+      graph.nodes.flatMap((node) =>
+        node.kind === "app" && node.gitAccess
+          ? [{ graph: id, node: node.id, ...node.gitAccess }]
+          : [],
+      ),
+    ),
+    writeNodes: graphs.flatMap(({ id, graph }) =>
+      graph.nodes.flatMap((node) => {
+        if (node.kind !== "app") return [];
+        const appId = definition.apps[node.app]?.appId;
+        const method =
+          appId === undefined
+            ? undefined
+            : catalog[appId]?.methods[node.method];
+        return method?.effect === "write" || method?.effect === "external"
+          ? [
+              {
+                graph: id,
+                node: node.id,
+                appId,
+                method: node.method,
+                effect: method.effect,
+              },
+            ]
+          : [];
+      }),
+    ),
+    triggers: definition.triggers ?? [],
+  });
+}
+
+/** A copy is named after its source; an over-long title keeps the source's. */
+function copyTitled(definition: WorkflowDefinition): WorkflowDefinition {
+  const named = { ...definition, title: `${definition.title} (copy)` };
+  return S.is(workflowDefinitionSchema)(named) ? named : definition;
+}
+
+async function digest(bytes: Uint8Array) {
+  const hash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)),
+  );
+  return S.decodeUnknownSync(sha256DigestSchema)(
+    `sha256:${Array.from(hash, (byte) => byte.toString(16).padStart(2, "0")).join("")}`,
+  );
+}
+
+/** Copies published content into a new draft; provenance is a claim, never authority. */
+export function createWorkflowShare({
+  library,
+  catalog,
+  origin,
+}: {
+  library: Pick<
+    ReturnType<typeof createWorkflowLibrary>,
+    "published" | "saveDraft"
+  >;
+  catalog: (appIds: readonly string[]) => Promise<Catalog>;
+  origin?: string;
+}) {
+  async function save(
+    workflowId: string,
+    draft: Pick<WorkflowDraft, "definition" | "layout">,
+    provenance: Provenance,
+  ) {
+    const wanted = [
+      ...new Set(Object.values(draft.definition.apps).map((app) => app.appId)),
+    ];
+    const available = await catalog(wanted);
+    const appIds = wanted.filter((appId) => !Object.hasOwn(available, appId));
+    if (appIds.length)
+      return shareCopyReply.parse({ kind: "missing_apps", appIds });
+    const issues: readonly Issue[] = validate(draft.definition, available);
+    if (issues.length) return shareCopyReply.parse({ kind: "invalid", issues });
+    const result = await library.saveDraft(
+      workflowId,
+      { definition: draft.definition, layout: draft.layout, provenance },
+      0,
+    );
+    return shareCopyReply.parse(
+      result.kind === "saved"
+        ? {
+            ...result,
+            title: draft.definition.title,
+            review: review(draft.definition, available),
+          }
+        : result,
+    );
+  }
+  return {
+    async exportWorkflow(input: {
+      workflowId: string;
+      version: number;
+    }): Promise<z.output<typeof shareExportReply>> {
+      const document = await library.published(input.workflowId, {
+        version: input.version,
+      });
+      if (!document) return { kind: "not_found" as const };
+      let source: Bundle["source"] = { ...input, commit: document.commit };
+      if (origin !== undefined) source = { ...source, origin };
+      const bundle: Bundle = S.decodeUnknownSync(shareBundleSchema)(
+        {
+          format: "fungi.workflow-share/v1",
+          definition: document.definition,
+          layout: document.layout,
+          source,
+        },
+        { onExcessProperty: "error" },
+      );
+      const bytes = JSON.stringify(bundle);
+      const encoded = new TextEncoder().encode(bytes);
+      if (encoded.byteLength > maxShareBytes)
+        return { kind: "too_large" as const };
+      return { bytes, sha256: await digest(encoded) };
+    },
+    async importWorkflow(input: {
+      bytes: string;
+      sha256: string;
+      workflowId: string;
+    }) {
+      const bytes = new TextEncoder().encode(input.bytes);
+      if (bytes.byteLength > maxShareBytes)
+        return { kind: "too_large" as const };
+      if (
+        !S.is(sha256DigestSchema)(input.sha256) ||
+        (await digest(bytes)) !== input.sha256
+      )
+        return { kind: "digest_mismatch" as const };
+      const parsed = S.decodeUnknownResult(S.fromJsonString(shareBundleSchema))(
+        input.bytes,
+        { onExcessProperty: "error" },
+      );
+      if (Result.isFailure(parsed)) return { kind: "invalid_bundle" as const };
+      const bundle = parsed.success;
+      return save(
+        input.workflowId,
+        { definition: copyTitled(bundle.definition), layout: bundle.layout },
+        provenanceSchema.parse({
+          kind: "import",
+          ...bundle.source,
+          sha256: input.sha256,
+        }),
+      );
+    },
+    async forkPublishedWorkflow(input: {
+      sourceWorkflowId: string;
+      at: { version: number } | { commit: string };
+      workflowId: string;
+    }) {
+      const document = await library.published(
+        input.sourceWorkflowId,
+        input.at,
+      );
+      if (!document) return { kind: "not_found" as const };
+      return save(
+        input.workflowId,
+        {
+          definition: copyTitled(document.definition),
+          layout: document.layout,
+        },
+        provenanceSchema.parse({
+          kind: "fork",
+          workflowId: input.sourceWorkflowId,
+          commit: document.commit,
+        }),
+      );
+    },
+  };
+}