orcheo-studio 0.23.1 → 0.24.0

package/src/features/workflow/data/templates/candidate-badges.ts

@@ -1,6 +1,9 @@
 import { seededAvatarId } from "@/assets/avatars";
 import type { Workflow } from "../workflow-types";
-import type { StoredWorkflow } from "../../lib/workflow-storage.types";
+import type {
+  CandidateUpdateNote,
+  StoredWorkflow,
+} from "../../lib/workflow-storage.types";
 import type {
   WorkflowTemplateDefinition,
   WorkflowTemplateMetadata,
@@ -18,6 +21,8 @@ export interface CandidateBadgeSpec {
   avatar?: string;
   notes?: string | null;
   mermaid?: string | null;
+  version?: string | null;
+  updates?: CandidateUpdateNote[];
   /** Raw snake_case metadata dict from the colleague-candidates frontmatter. */
   rawMetadata?: Record<string, unknown> | null;
 }
@@ -165,6 +170,11 @@ export const getCandidateBadgeByHandle = (
 ): CandidateBadgeDefinition | undefined =>
   candidateBadges.find((badge) => badge.handle === handle);
 
+export const getCandidateBadgeByCandidateId = (
+  candidateId: string,
+): CandidateBadgeDefinition | undefined =>
+  candidateBadges.find((badge) => badge.candidateId === candidateId);
+
 export const getCandidateTemplateDefinition = (
   templateId: string,
 ): WorkflowTemplateDefinition | undefined =>

package/src/features/workflow/data/workflow-types.ts

@@ -1,3 +1,5 @@
+import type { WorkflowCandidateSource } from "@features/workflow/lib/workflow-storage.types";
+
 export interface WorkflowNode {
   id: string;
   type: string;
@@ -28,6 +30,7 @@ export interface WorkflowMermaidPreviewVersion {
   id: string;
   mermaid?: string | null;
   templateId?: string;
+  candidateSource?: WorkflowCandidateSource;
 }
 
 export interface Workflow {

package/src/features/workflow/lib/workflow-storage-api.ts

@@ -14,6 +14,7 @@ import type {
   WorkflowListenerMetricsResponse,
   WorkflowCredentialReadinessResponse,
   WorkflowPublishResponse,
+  CandidateUpdateNote,
 } from "./workflow-storage.types";
 
 export const API_BASE = "/api/workflows";
@@ -179,6 +180,8 @@ export interface ApiCandidate {
   notes: string | null;
   metadata: Record<string, unknown> | null;
   mermaid: string | null;
+  version: string | null;
+  updates: CandidateUpdateNote[];
 }
 
 export const fetchCandidates = async (): Promise<ApiCandidate[]> =>
@@ -214,6 +217,18 @@ export const onboardCandidate = async (
     }),
   });
 
+export const updateCandidateWorkflow = async (
+  workflowId: string,
+  candidateId: string,
+): Promise<ApiWorkflow> =>
+  request<ApiWorkflow>("/api/candidates/update", {
+    method: "POST",
+    body: JSON.stringify({
+      workflow_id: workflowId,
+      candidate_id: candidateId,
+    }),
+  });
+
 export const fetchWorkflowListeners = async (
   workflowId: string,
 ): Promise<WorkflowListenerHealth[]> => {

package/src/features/workflow/lib/workflow-storage-helpers.ts

@@ -20,6 +20,7 @@ import type {
   ApiWorkflow,
   ApiWorkflowVersion,
   ApiWorkflowVersionSummary,
+  WorkflowCandidateSource,
   WorkflowVersionMetadata,
   StoredWorkflow,
   WorkflowVersionRecord,
@@ -97,6 +98,45 @@ const extractAvatarEmoji = (metadata: unknown): string | undefined => {
   return undefined;
 };
 
+const extractCandidateSource = (
+  metadata: unknown,
+): WorkflowCandidateSource | undefined => {
+  if (!isRecord(metadata)) {
+    return undefined;
+  }
+
+  const source =
+    typeof metadata.source === "string" ? metadata.source : undefined;
+  const candidateId =
+    typeof metadata.candidate_id === "string"
+      ? metadata.candidate_id
+      : undefined;
+  const candidateHandle =
+    typeof metadata.candidate_handle === "string"
+      ? metadata.candidate_handle
+      : undefined;
+  const candidateVersion =
+    typeof metadata.candidate_version === "string"
+      ? metadata.candidate_version
+      : undefined;
+  const candidateSourceRef =
+    typeof metadata.candidate_source_ref === "string"
+      ? metadata.candidate_source_ref
+      : undefined;
+
+  if (!source && !candidateId && !candidateHandle && !candidateVersion) {
+    return undefined;
+  }
+
+  return {
+    source,
+    candidateId,
+    candidateHandle,
+    candidateVersion,
+    candidateSourceRef,
+  };
+};
+
 const toAuthor = (id: string | undefined): Workflow["owner"] => {
   if (!id) {
     return { ...DEFAULT_OWNER };
@@ -178,6 +218,7 @@ const parseWorkflowMetadata = (
     isRecord(metadata) ? metadata.configurable_schema : undefined,
   );
   const avatarEmoji = extractAvatarEmoji(metadata);
+  const candidateSource = extractCandidateSource(metadata);
   const resolveTemplateFallback = (): WorkflowVersionMetadata | undefined => {
     if (!metadata || typeof metadata !== "object") {
       return undefined;
@@ -204,6 +245,7 @@ const parseWorkflowMetadata = (
       templateId,
       configurableSchemas,
       avatarEmoji,
+      candidateSource,
     };
   };
 
@@ -214,6 +256,7 @@ const parseWorkflowMetadata = (
       templateId: undefined,
       configurableSchemas: undefined,
       avatarEmoji: undefined,
+      candidateSource,
     };
   }
 
@@ -226,6 +269,7 @@ const parseWorkflowMetadata = (
         summary: { ...DEFAULT_SUMMARY },
         configurableSchemas,
         avatarEmoji,
+        candidateSource,
       }
     );
   }
@@ -280,6 +324,7 @@ const parseWorkflowMetadata = (
     templateId,
     configurableSchemas,
     avatarEmoji,
+    candidateSource,
   };
 };
 
@@ -337,6 +382,7 @@ const toVersionRecord = (
     graphToWorkflow: metadata.graphToWorkflow,
     templateId: metadata.templateId,
     avatarEmoji: metadata.avatarEmoji,
+    candidateSource: metadata.candidateSource,
   };
 };
 

package/src/features/workflow/lib/workflow-storage.ts

@@ -16,6 +16,7 @@ import {
   fetchWorkflowVersions,
   onboardCandidate,
   request,
+  updateCandidateWorkflow,
   upsertWorkflow,
 } from "./workflow-storage-api";
 import {
@@ -472,6 +473,22 @@ export const onboardCandidateAsWorkflow = async (
   return stored;
 };
 
+export const updateCandidateWorkflowVersion = async (
+  workflowId: string,
+  candidateId: string,
+): Promise<StoredWorkflow> => {
+  const apiWorkflow = await updateCandidateWorkflow(workflowId, candidateId);
+  invalidateWorkflowCache(apiWorkflow.id);
+  const stored = await ensureWorkflow(apiWorkflow.id);
+  if (!stored) {
+    throw new Error("Failed to load updated candidate workflow");
+  }
+  invalidateWorkflowListCache();
+  primeWorkflowCache(stored);
+  emitUpdate();
+  return stored;
+};
+
 export type {
   StoredWorkflow,
   WorkflowVersionRecord,

package/src/features/workflow/lib/workflow-storage.types.ts

@@ -68,6 +68,20 @@ export interface ApiWorkflowVersionSummary {
   updated_at: string;
 }
 
+export interface CandidateUpdateNote {
+  version: string;
+  summary: string;
+  migration?: string | null;
+}
+
+export interface WorkflowCandidateSource {
+  source?: string;
+  candidateId?: string;
+  candidateHandle?: string;
+  candidateVersion?: string;
+  candidateSourceRef?: string;
+}
+
 export interface ApiWorkflowPageData {
   workflow: ApiWorkflow;
   versions?: ApiWorkflowVersionSummary[];
@@ -219,6 +233,7 @@ export interface WorkflowVersionMetadata {
   templateId?: string;
   configurableSchemas?: Record<string, RJSFSchema>;
   avatarEmoji?: string;
+  candidateSource?: WorkflowCandidateSource;
 }
 
 export interface RequestOptions extends RequestInit {
@@ -241,6 +256,7 @@ export interface WorkflowVersionRecord {
   configurableSchemas?: Record<string, RJSFSchema>;
   graphToWorkflow?: Record<string, string>;
   templateId?: string;
+  candidateSource?: WorkflowCandidateSource;
 }
 
 export interface StoredWorkflow extends Workflow {

package/src/features/workflow/pages/workflow/hooks/use-workflow-saver.ts

@@ -63,8 +63,9 @@ export function useWorkflowSaver(
           "studio",
           runnableConfig,
         );
-        // Keep the in-memory versions in sync so reopening the config sheet
-        // shows the saved values without a page refresh.
+        // Keep the in-memory runnable config in sync so reopening the config
+        // sheet shows the saved values without a page refresh. Other persisted
+        // fields will refresh on the next full workflow fetch.
         setWorkflowVersions((versions) =>
           versions.map((version) =>
             version.versionNumber === targetVersion

package/src/features/workflow/pages/workflow-gallery/candidate-updates.ts

@@ -0,0 +1,107 @@
+import type { Workflow } from "@features/workflow/data/workflow-data";
+import type { CandidateBadgeDefinition } from "@features/workflow/data/templates/candidate-badges";
+import type { CandidateUpdateNote } from "@features/workflow/lib/workflow-storage.types";
+
+interface SemVer {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+export interface CandidateUpdateAvailability {
+  candidateId: string;
+  candidateName: string;
+  currentVersion: string;
+  latestVersion: string;
+  latestSummary?: string;
+  firstMigration?: string;
+  crossedUpdates: CandidateUpdateNote[];
+  isMajor: boolean;
+}
+
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export const parseSemVer = (value: string): SemVer | null => {
+  const match = SEMVER_PATTERN.exec(value);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number.parseInt(match[1] ?? "0", 10),
+    minor: Number.parseInt(match[2] ?? "0", 10),
+    patch: Number.parseInt(match[3] ?? "0", 10),
+  };
+};
+
+export const compareSemVer = (left: string, right: string): number | null => {
+  const leftVersion = parseSemVer(left);
+  const rightVersion = parseSemVer(right);
+  if (!leftVersion || !rightVersion) {
+    return null;
+  }
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    const delta = leftVersion[key] - rightVersion[key];
+    if (delta !== 0) {
+      return delta > 0 ? 1 : -1;
+    }
+  }
+
+  return 0;
+};
+
+export const getCandidateUpdateAvailability = (
+  workflow: Workflow,
+  candidate: CandidateBadgeDefinition | undefined,
+): CandidateUpdateAvailability | undefined => {
+  if (!candidate?.version) {
+    return undefined;
+  }
+
+  const candidateSource = workflow.versions?.at(-1)?.candidateSource;
+  if (candidateSource?.source !== "candidate-onboard") {
+    return undefined;
+  }
+
+  const currentVersion = candidateSource.candidateVersion;
+  if (!currentVersion) {
+    return undefined;
+  }
+
+  const latestVersion = candidate.version;
+  if (compareSemVer(latestVersion, currentVersion) !== 1) {
+    return undefined;
+  }
+
+  const currentParsed = parseSemVer(currentVersion);
+  const latestParsed = parseSemVer(latestVersion);
+  if (!currentParsed || !latestParsed) {
+    return undefined;
+  }
+
+  const crossedUpdates = (candidate.updates ?? []).filter((note) => {
+    const newerThanCurrent = compareSemVer(note.version, currentVersion);
+    const notNewerThanLatest = compareSemVer(note.version, latestVersion);
+    return (
+      newerThanCurrent === 1 &&
+      notNewerThanLatest !== null &&
+      notNewerThanLatest <= 0
+    );
+  });
+
+  const firstMigration = crossedUpdates.find(
+    (note) => typeof note.migration === "string" && note.migration.trim(),
+  )?.migration;
+
+  return {
+    candidateId: candidate.candidateId,
+    candidateName: candidate.name,
+    currentVersion,
+    latestVersion,
+    latestSummary: crossedUpdates[0]?.summary,
+    firstMigration,
+    crossedUpdates,
+    isMajor: latestParsed.major > currentParsed.major,
+  };
+};

package/src/features/workflow/pages/workflow-gallery/use-workflow-gallery-actions.ts

@@ -9,6 +9,7 @@ import { getCandidateBadgeDefinition } from "@features/workflow/data/templates/c
 import {
   deleteWorkflow,
   onboardCandidateAsWorkflow,
+  updateCandidateWorkflowVersion,
 } from "@features/workflow/lib/workflow-storage";
 import {
   type ApiTeam,
@@ -104,10 +105,9 @@ export const useWorkflowGalleryActions = (
   const handleOpenWorkflow = useCallback(
     (workflowId: string, teamSlug?: string) => {
       const slug = getSelectedWorkspaceSlug();
-      const path =
-        teamSlug
-          ? getWorkspaceTeamWorkflowPath(slug, teamSlug, workflowId)
-          : getWorkspaceWorkflowPath(slug, workflowId);
+      const path = teamSlug
+        ? getWorkspaceTeamWorkflowPath(slug, teamSlug, workflowId)
+        : getWorkspaceWorkflowPath(slug, workflowId);
       navigate(path);
     },
     [navigate],
@@ -302,6 +302,30 @@ export const useWorkflowGalleryActions = (
     [],
   );
 
+  const handleUpdateCandidateWorkflow = useCallback(
+    async (workflowId: string, candidateId: string) => {
+      try {
+        const workflow = await updateCandidateWorkflowVersion(
+          workflowId,
+          candidateId,
+        );
+        toast({
+          title: "Candidate updated",
+          description: `"${workflow.name}" is now on the latest candidate version.`,
+        });
+      } catch (error) {
+        toast({
+          title: "Failed to update candidate",
+          description:
+            error instanceof Error ? error.message : "Unknown error occurred",
+          variant: "destructive",
+        });
+        throw error;
+      }
+    },
+    [],
+  );
+
   const openCreateTeamDialog = useCallback(() => setIsCreateTeamOpen(true), []);
   const closeCreateTeamDialog = useCallback(
     () => setIsCreateTeamOpen(false),
@@ -314,6 +338,7 @@ export const useWorkflowGalleryActions = (
     handleImportStarterPack,
     handleExportWorkflow,
     handleDeleteWorkflow,
+    handleUpdateCandidateWorkflow,
     onboardTarget,
     confirmOnboardTeam,
     cancelOnboardTeam,

package/src/features/workflow/pages/workflow-gallery/use-workflow-gallery-state.ts

@@ -49,6 +49,8 @@ const toCandidateSpec = (candidate: ApiCandidate): CandidateBadgeSpec => ({
   avatar: candidate.avatar ?? undefined,
   notes: candidate.notes,
   mermaid: candidate.mermaid,
+  version: candidate.version,
+  updates: candidate.updates,
   rawMetadata: candidate.metadata,
 });
 
@@ -75,17 +77,22 @@ export const useWorkflowGalleryState = (): WorkflowGalleryStateSlice => {
   useEffect(() => {
     let isMounted = true;
 
-    const loadCandidates = async () => {
+    const loadCandidates = async (existingWorkflows?: StoredWorkflow[]) => {
       try {
         // Load both candidates and existing workflows to check for handle conflicts
-        const [candidates, existingWorkflows] = await Promise.all([
+        const [candidates, workflowsForConflicts] = await Promise.all([
           fetchCandidates(),
-          listWorkflows(),
+          existingWorkflows
+            ? Promise.resolve(existingWorkflows)
+            : listWorkflows(),
         ]);
         if (!isMounted) {
           return;
         }
-        setCandidateBadges(candidates.map(toCandidateSpec), existingWorkflows);
+        setCandidateBadges(
+          candidates.map(toCandidateSpec),
+          workflowsForConflicts,
+        );
         setCandidateWorkflows(getCandidateWorkflows());
       } catch (error) {
         if (isMounted) {
@@ -94,26 +101,8 @@ export const useWorkflowGalleryState = (): WorkflowGalleryStateSlice => {
       }
     };
 
-    void loadCandidates();
-
-    return () => {
-      isMounted = false;
-    };
-  }, []);
-
-  const refreshTeams = useCallback(async () => {
-    try {
-      const teamList = await fetchTeams();
-      setTeams(teamList);
-    } catch {
-      // non-fatal — teams list will stay stale
-    }
-  }, []);
-
-  useEffect(() => {
-    let isMounted = true;
-
-    const load = async (forceRefresh = false) => {
+    const load = async (forceRefresh = false, refreshCandidates = false) => {
+      let loadedWorkflows: StoredWorkflow[] | undefined;
       if (isMounted) {
         setIsLoadingWorkflows(true);
       }
@@ -122,6 +111,7 @@ export const useWorkflowGalleryState = (): WorkflowGalleryStateSlice => {
           listWorkflows({ forceRefresh }),
           fetchTeams().catch(() => [] as ApiTeam[]),
         ]);
+        loadedWorkflows = items;
         if (isMounted) {
           setWorkflows(items);
           setTeams(teamList);
@@ -143,14 +133,19 @@ export const useWorkflowGalleryState = (): WorkflowGalleryStateSlice => {
           setIsLoadingWorkflows(false);
         }
       }
+
+      if (refreshCandidates && loadedWorkflows) {
+        await loadCandidates(loadedWorkflows);
+      }
     };
 
+    void loadCandidates();
     void load();
 
     const targetWindow = typeof window !== "undefined" ? window : undefined;
     if (targetWindow) {
       const handler = () => {
-        void load(true);
+        void load(true, true);
       };
       targetWindow.addEventListener(WORKFLOW_STORAGE_EVENT, handler);
 
@@ -165,6 +160,15 @@ export const useWorkflowGalleryState = (): WorkflowGalleryStateSlice => {
     };
   }, []);
 
+  const refreshTeams = useCallback(async () => {
+    try {
+      const teamList = await fetchTeams();
+      setTeams(teamList);
+    } catch {
+      // non-fatal — teams list will stay stale
+    }
+  }, []);
+
   const templates = useMemo(
     () => [...GALLERY_TEMPLATE_WORKFLOWS, ...candidateWorkflows],
     [candidateWorkflows],