@fungi.computer/trellis 0.0.0-stage → 0.0.1

package/backend/tool-family.ts

@@ -0,0 +1,124 @@
+import * as z from "zod";
+import { defineAppMethod } from "@fungi.computer/agar/backend-definition";
+import { catalogReplySchema } from "@fungi.computer/workflows-wire";
+import { runReply } from "@fungi.computer/workflows-wire";
+import { workflowToolListing } from "../shared/tool-contracts.js";
+import type { WorkflowIndexes } from "./indexes.js";
+import type { WorkflowMethodContext } from "./methods.js";
+
+const output = z.toJSONSchema(runReply, { io: "output" });
+
+// Workflow ids have no underscores or upper-case letters. Preserve dash cases
+// that cannot become camel case, so distinct ids cannot alias the same tool.
+function toolName(workflowId: string): string {
+  const camel = workflowId.replace(
+    /-([a-z])|-/g,
+    (_, letter: string | undefined) =>
+      letter === undefined ? "_" : letter.toUpperCase(),
+  );
+  return /^[0-9]/.test(camel) ? `Workflow_${camel}` : camel;
+}
+
+/** A Workflow's own declared App roles: `{ alias: { appId, role? } }`. */
+const appRoleSchema = z.record(
+  z.string(),
+  z.object({ appId: z.string(), role: z.string().optional() }),
+);
+type InstalledApp = Readonly<{ installationId: string; appId: string }>;
+
+/**
+ * Resolve each declared App role to exactly one installed App: the same
+ * unambiguous match the Run dialog's own default picks for a person. A role
+ * with zero or more than one installed candidate has no single correct
+ * answer without a person choosing, so the caller withholds the whole row
+ * rather than guessing a binding.
+ */
+function resolveBindings(
+  apps: z.output<typeof appRoleSchema>,
+  installed: readonly InstalledApp[],
+): Record<string, string> | null {
+  const bindings: Record<string, string> = {};
+  for (const [alias, spec] of Object.entries(apps)) {
+    const matches = installed.filter((app) => app.appId === spec.appId);
+    const [match] = matches;
+    if (matches.length !== 1 || match === undefined) return null;
+    bindings[alias] = match.installationId;
+  }
+  return bindings;
+}
+
+async function listTools(
+  indexes: WorkflowIndexes | undefined,
+  workflows: WorkflowMethodContext["env"]["WORKFLOWS"],
+): Promise<z.output<typeof workflowToolListing>> {
+  const library = indexes?.libraryList();
+  if (!indexes || library?.kind !== "ready") return { kind: "unindexed" };
+  // Read the Team's installed Apps once for every row, not once per row.
+  const catalog = workflows
+    ? catalogReplySchema.parse(await workflows.catalog({}))
+    : { error: "not_granted" as const };
+  const installed: readonly InstalledApp[] =
+    "apps" in catalog
+      ? catalog.apps.map((app) => ({
+          installationId: app.installationId,
+          appId: app.appId,
+        }))
+      : [];
+  const tools: unknown[] = [];
+  for (const item of [...library.value.items].sort((a, b) =>
+    a.workflowId.localeCompare(b.workflowId),
+  )) {
+    const published = item.published;
+    if (published?.version == null) continue;
+    // The immutable publication row written at publish; no Git is read here.
+    const row = indexes.publications.read(
+      `${item.workflowId}:v${String(published.version)}`,
+    );
+    if (
+      row.kind !== "ready" ||
+      row.value.workflowId !== item.workflowId ||
+      row.value.version !== published.version ||
+      row.value.commit !== published.commit
+    )
+      return { kind: "unindexed" };
+    const definition = row.value.definition;
+    const apps = appRoleSchema.safeParse(definition.apps);
+    if (!apps.success) continue;
+    const bindings = resolveBindings(apps.data, installed);
+    // No single correct binding today (a role is unmet or ambiguous): never
+    // guess one, so withhold this one Workflow's tool, not the whole family.
+    if (bindings === null) continue;
+    tools.push({
+      workflowId: item.workflowId,
+      tool: toolName(item.workflowId),
+      title: definition.title,
+      description: definition.description ?? "",
+      version: published.version,
+      commit: published.commit,
+      input: definition.input,
+      output,
+      // The exact extra arguments a generic tool-family host merges with the
+      // caller's own `input` when it calls `runWorkflow`; see tool-contracts.
+      call: {
+        workflowId: item.workflowId,
+        version: published.version,
+        bindings,
+      },
+    });
+  }
+  return workflowToolListing.parse({ kind: "ready", tools });
+}
+
+export const toolFamilyMethods = {
+  listWorkflowTools: defineAppMethod({
+    description:
+      "List typed tools from saved published Workflow versions; drafts are excluded.",
+    hidden: true,
+    effect: "read",
+    requires: ["workflow.run"],
+    input: z.strictObject({}),
+    output: workflowToolListing,
+    handler: (_input, context: WorkflowMethodContext) =>
+      listTools(context.indexes, context.env.WORKFLOWS),
+  }),
+};

package/backend/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": false,
+    "sourceMap": false,
+    "rootDir": "..",
+    "outDir": "../dist"
+  },
+  "include": ["library.ts"]
+}

package/backend/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"],
+    "lib": ["ES2022"],
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["*.ts", "../host"]
+}

package/dist/backend/catalog.js

@@ -0,0 +1,42 @@
+import * as S from "effect/Schema";
+import { catalogSchema } from "@fungi.computer/braid";
+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) {
+    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, appIds) {
+    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 },
+            ],
+        ])), { onExcessProperty: "error" });
+}

package/dist/backend/gills.js

@@ -0,0 +1,49 @@
+import { defineAppGill } from "@fungi.computer/agar/gills";
+import { libraryListing } from "@fungi.computer/workflows-wire";
+/** 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 }) => 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) => {
+            const row = {
+                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/dist/backend/indexes.js

@@ -0,0 +1,294 @@
+import { workflowIdSchema } from "@fungi.computer/braid";
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { workflowDefinitionSchema } from "@fungi.computer/braid";
+import { createReadCopies } from "@fungi.computer/agar/read-copy";
+import { gitSha1Schema } from "@fungi.computer/puffball/git-representation";
+import { createPublicationJobs } from "./publication-job.js";
+import { versionRefs } from "@fungi.computer/workflows-wire";
+import { document, publishedDocument, draftDocument, version, listings, } from "@fungi.computer/workflows-wire";
+const issueSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    graph: z.string().optional(),
+    node: z.string().optional(),
+    trigger: z.string().optional(),
+    port: z.string().optional(),
+    edge: z.number().optional(),
+});
+const pushRowSchema = z.strictObject({
+    eventId: z.string(),
+    commit: z.string(),
+    workflowId: z.string(),
+    issues: z.string(),
+});
+const copiedDocument = document.transform((raw) => ({
+    ...raw,
+    definition: Schema.decodeUnknownSync(workflowDefinitionSchema)(raw.definition),
+}));
+const librarySnapshotSchema = z.strictObject({
+    refs: z.record(z.string(), gitSha1Schema),
+    items: listings,
+});
+export function createWorkflowIndexes(storage) {
+    const { sql } = storage;
+    sql.exec("CREATE TABLE IF NOT EXISTS workflow_drafts (workflow_id TEXT PRIMARY KEY, revision INTEGER NOT NULL, body TEXT NOT NULL, updated_at INTEGER NOT NULL)");
+    const draftRow = z.strictObject({
+        revision: z.number().int().positive(),
+        body: z.string(),
+    });
+    const decodeDraft = (raw) => {
+        const row = draftRow.parse(raw);
+        const value = draftDocument.parse({
+            ...z.record(z.string(), z.json()).parse(JSON.parse(row.body)),
+            revision: row.revision,
+        });
+        return {
+            ...value,
+            definition: Schema.decodeUnknownSync(workflowDefinitionSchema)(value.definition),
+        };
+    };
+    function readDraft(workflowId) {
+        workflowIdSchema.parse(workflowId);
+        const raw = sql
+            .exec("SELECT revision, body FROM workflow_drafts WHERE workflow_id = ?", workflowId)
+            .toArray()[0];
+        return raw === undefined ? null : decodeDraft(raw);
+    }
+    sql.exec('CREATE TABLE IF NOT EXISTS workflow_push_issues (eventId TEXT NOT NULL, "commit" TEXT NOT NULL, workflowId TEXT NOT NULL, issues TEXT NOT NULL, PRIMARY KEY (eventId, "commit", workflowId))');
+    const copies = createReadCopies(sql, {
+        version: 2,
+        maxRows: 4096,
+        maxValueBytes: 1048576,
+        maxBlobBytes: 1048576,
+        maxBlobTotalBytes: 8388608,
+    });
+    const library = copies.open("workflow.library", librarySnapshotSchema);
+    const generation = copies.open("workflow.revision", z.number().int().nonnegative());
+    const documents = copies.open("workflow.document", copiedDocument.nullable());
+    const publications = copies.open("workflow.publication", publishedDocument.transform((raw) => ({
+        ...raw,
+        definition: Schema.decodeUnknownSync(workflowDefinitionSchema)(raw.definition),
+    })));
+    const versionCopies = copies.open("workflow.versions", z.array(version).max(1000));
+    const rebuildingRow = z.strictObject({
+        workflowId: z.string(),
+        main: copiedDocument.nullable(),
+        versions: z.array(version).max(1000),
+        versionOffset: z.number().int().nonnegative(),
+    });
+    const frontier = copies.open("workflow.frontier", z.strictObject({
+        epoch: z.number().int().nonnegative(),
+        refs: z.array(z.strictObject({ name: z.string(), hash: gitSha1Schema })),
+        ids: z.array(z.string()).max(100),
+        offset: z.number().int().nonnegative(),
+        items: listings,
+        current: rebuildingRow.nullable(),
+        queue: z.array(rebuildingRow).max(4),
+    }));
+    function mergeDraftListings(items) {
+        const saved = new Map(items.map((item) => [item.workflowId, item]));
+        for (const raw of sql
+            .exec("SELECT workflow_id, revision, body FROM workflow_drafts ORDER BY workflow_id LIMIT 100")
+            .toArray()) {
+            const row = z
+                .object({
+                workflow_id: workflowIdSchema,
+                revision: z.number().int().positive(),
+                body: z.string(),
+            })
+                .parse(raw);
+            const draft = decodeDraft({ revision: row.revision, body: row.body });
+            const previous = saved.get(row.workflow_id);
+            saved.set(row.workflow_id, {
+                workflowId: row.workflow_id,
+                title: draft.definition.title,
+                draftRevision: row.revision,
+                published: previous?.published ?? null,
+            });
+        }
+        return [...saved.values()]
+            .sort((a, b) => a.workflowId.localeCompare(b.workflowId))
+            .slice(0, 100);
+    }
+    function librarySnapshot() {
+        const saved = library.read("all");
+        const epoch = generation.read("all");
+        return {
+            revision: epoch.kind === "ready" ? epoch.value : 0,
+            snapshot: saved.kind === "ready" ? saved.value : null,
+        };
+    }
+    const indexes = {
+        drafts: {
+            read: readDraft,
+            save(workflowId, body, expectedRevision) {
+                workflowIdSchema.parse(workflowId);
+                return storage.transactionSync(() => {
+                    const current = readDraft(workflowId);
+                    if ((current?.revision ?? 0) !== expectedRevision)
+                        return { kind: "conflict", current };
+                    const revision = expectedRevision + 1;
+                    const saved = draftDocument.parse({ ...body, revision });
+                    const { revision: savedRevision, ...content } = saved;
+                    sql.exec("INSERT INTO workflow_drafts (workflow_id, revision, body, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(workflow_id) DO UPDATE SET revision = excluded.revision, body = excluded.body, updated_at = excluded.updated_at", workflowId, savedRevision, JSON.stringify(content), Date.now());
+                    const currentLibrary = librarySnapshot();
+                    const previous = currentLibrary.snapshot?.items.find((item) => item.workflowId === workflowId);
+                    library.write("all", currentLibrary.snapshot?.refs["refs/heads/main"] ?? null, {
+                        refs: currentLibrary.snapshot?.refs ?? {},
+                        items: [
+                            ...(currentLibrary.snapshot?.items ?? []).filter((item) => item.workflowId !== workflowId),
+                            {
+                                workflowId,
+                                title: Schema.decodeUnknownSync(workflowDefinitionSchema)(content.definition).title,
+                                draftRevision: revision,
+                                published: previous?.published ?? null,
+                            },
+                        ]
+                            .sort((a, b) => a.workflowId.localeCompare(b.workflowId))
+                            .slice(0, 100),
+                    });
+                    return { kind: "saved", revision };
+                });
+            },
+        },
+        libraryList: () => library.read("all"),
+        documents,
+        versionCopies,
+        publications,
+        recordPublication(value, epoch) {
+            storage.transactionSync(() => {
+                const { workflowId, version: number, commit } = value;
+                const saved = {
+                    definition: value.definition,
+                    layout: value.layout,
+                    commit,
+                };
+                if (value.provenance !== undefined)
+                    saved.provenance = value.provenance;
+                publications.write(`${workflowId}:v${String(number)}`, commit, value);
+                publications.write(`${workflowId}:${commit}`, commit, value);
+                documents.write(`main:${workflowId}`, commit, saved);
+                documents.write(`at:${workflowId}:${commit}`, commit, saved);
+                const previous = versionCopies.read(workflowId);
+                versionCopies.write(workflowId, commit, [
+                    {
+                        version: number,
+                        commit,
+                        committedAt: Math.floor(Date.now() / 1000),
+                        message: `Publish ${workflowId}`,
+                    },
+                    ...(previous.kind === "ready" ? previous.value : []),
+                ].slice(0, 1000));
+                const current = librarySnapshot();
+                if (current.revision === epoch && current.snapshot)
+                    library.write("all", commit, {
+                        refs: {
+                            ...current.snapshot.refs,
+                            "refs/heads/main": commit,
+                            [`refs/tags/${workflowId}@v${String(number)}`]: commit,
+                        },
+                        items: current.snapshot.items.map((item) => item.workflowId === workflowId
+                            ? { ...item, published: { commit, version: number } }
+                            : item),
+                    });
+            });
+        },
+        recordBackgroundPublication(value, epoch, references) {
+            storage.transactionSync(() => {
+                const { workflowId, version: number, commit } = value;
+                const saved = { definition: value.definition, layout: value.layout, commit };
+                if (value.provenance !== undefined)
+                    saved.provenance = value.provenance;
+                publications.write(`${workflowId}:v${String(number)}`, commit, value);
+                publications.write(`${workflowId}:${commit}`, commit, value);
+                documents.write(`at:${workflowId}:${commit}`, commit, saved);
+                const previous = versionCopies.read(workflowId);
+                const retained = previous.kind === "ready" ? previous.value : [];
+                const next = [
+                    {
+                        version: number,
+                        commit,
+                        committedAt: Math.floor(Date.now() / 1000),
+                        message: `Publish ${workflowId}`,
+                    },
+                    ...retained.filter((version) => version.version !== number),
+                ]
+                    .sort((a, b) => b.version - a.version)
+                    .slice(0, 1000);
+                versionCopies.write(workflowId, next[0]?.commit ?? commit, next);
+                const main = references.find((ref) => ref.name === "refs/heads/main")?.hash ??
+                    null;
+                const copiedMain = documents.read(`main:${workflowId}`);
+                if (main === commit && (retained[0]?.version ?? 0) <= number)
+                    documents.write(`main:${workflowId}`, commit, saved);
+                else if (copiedMain.kind === "ready" && copiedMain.head !== main)
+                    documents.stale(`main:${workflowId}`);
+                const current = librarySnapshot();
+                if (current.revision === epoch && current.snapshot) {
+                    const latest = versionRefs(workflowId, references)[0];
+                    library.write("all", main, {
+                        refs: Object.fromEntries(references.map((ref) => [ref.name, ref.hash])),
+                        items: current.snapshot.items.map((item) => {
+                            if (item.workflowId !== workflowId ||
+                                !latest ||
+                                (item.published?.version ?? 0) > latest.version)
+                                return item;
+                            return {
+                                ...item,
+                                published: { commit: latest.commit, version: latest.version },
+                            };
+                        }),
+                    });
+                }
+            });
+        },
+        frontier,
+        librarySnapshot,
+        recordLibrary(revision, snapshot) {
+            if (librarySnapshot().revision === revision)
+                library.write("all", snapshot.refs["refs/heads/main"] ?? null, {
+                    ...snapshot,
+                    items: mergeDraftListings(snapshot.items),
+                });
+        },
+        invalidateLibrary(updates) {
+            const current = librarySnapshot();
+            if (updates &&
+                current.snapshot &&
+                updates.every(({ ref, after }) => (current.snapshot?.refs[ref] ?? "0".repeat(40)) === after))
+                return;
+            generation.write("all", null, current.revision + 1);
+            library.stale("all");
+        },
+        recordIssues(eventId, commit, workflowId, issues) {
+            sql.exec('INSERT INTO workflow_push_issues (eventId, "commit", workflowId, issues) VALUES (?, ?, ?, ?) ON CONFLICT(eventId, "commit", workflowId) DO NOTHING', eventId, commit, workflowId, JSON.stringify(issues));
+        },
+        issues(eventId) {
+            return sql
+                .exec('SELECT eventId, "commit", workflowId, issues FROM workflow_push_issues WHERE eventId = ? ORDER BY workflowId, "commit"', eventId)
+                .toArray()
+                .map((raw) => {
+                const row = pushRowSchema.parse(raw);
+                return {
+                    ...row,
+                    issues: z.array(issueSchema).parse(JSON.parse(row.issues)),
+                };
+            });
+        },
+    };
+    const publicationJobs = createPublicationJobs(storage, {
+        readDraft: (workflowId) => {
+            const draft = readDraft(workflowId);
+            return draft === null ? null : draftDocument.parse(draft);
+        },
+        revision: () => librarySnapshot().revision,
+        publish: (value, epoch, refs) => {
+            indexes.recordBackgroundPublication({
+                ...value,
+                definition: Schema.decodeUnknownSync(workflowDefinitionSchema)(value.definition),
+            }, epoch, refs);
+        },
+    });
+    return { ...indexes, publicationJobs };
+}