@morscherlab/mint-sdk 1.0.63 → 1.1.0-beta.2

package/src/composables/useJobsStatusTray.ts

@@ -26,6 +26,127 @@ import type {
 
 export type JobsStatusTrayTab = 'active' | 'history'
 
+/**
+ * The canonical owner of a collection of plugin jobs.
+ *
+ * Sources, rather than job-center UI, own polling, event streams, and all job
+ * mutations. This keeps components and consumers on one reactive job graph.
+ */
+export interface PluginJobCenterSource {
+  jobs: MaybeRefOrGetter<readonly JobStateInput[]>
+  refreshJobs?: () => Promise<JobListPayload | readonly JobStateInput[] | void>
+  cancelJob?: (jobId: string) => Promise<JobStateInput | void>
+  deleteJob?: (jobId: string) => Promise<boolean | void>
+  clearFinishedJobs?: () => Promise<number | void>
+  dispose?: () => void
+}
+
+export interface CombinedPluginJobCenterSource extends PluginJobCenterSource {
+  jobs: ComputedRef<readonly JobStateInput[]>
+}
+
+/**
+ * Combines independent job runtimes without copying their reactive state.
+ *
+ * Job ids must be globally unique across the sources. A duplicate id throws
+ * when jobs are read or an id-routed action is requested, rather than silently
+ * dispatching a mutation to the wrong owner.
+ */
+export function combinePluginJobSources(
+  sources: readonly PluginJobCenterSource[],
+): CombinedPluginJobCenterSource {
+  const jobs = computed<readonly JobStateInput[]>(() => {
+    const combined: JobStateInput[] = []
+    const owners = new Set<string>()
+    for (const source of sources) {
+      for (const job of toValue(source.jobs)) {
+        if (owners.has(job.job_id)) throw duplicatePluginJobId(job.job_id)
+        owners.add(job.job_id)
+        combined.push(job)
+      }
+    }
+    return combined
+  })
+
+  function ownerFor(jobId: string): PluginJobCenterSource {
+    let owner: PluginJobCenterSource | undefined
+    for (const source of sources) {
+      if (!toValue(source.jobs).some(job => job.job_id === jobId)) continue
+      if (owner) throw duplicatePluginJobId(jobId)
+      owner = source
+    }
+    if (!owner) throw new Error(`Unknown plugin job id: ${jobId}`)
+    return owner
+  }
+
+  const combined: CombinedPluginJobCenterSource = { jobs }
+  if (sources.some(source => source.refreshJobs)) {
+    combined.refreshJobs = async () => {
+      await Promise.all(sources.map(source => source.refreshJobs?.()))
+      return jobs.value
+    }
+  }
+  if (sources.some(source => source.cancelJob)) {
+    combined.cancelJob = async (jobId) => {
+      const owner = ownerFor(jobId)
+      if (!owner.cancelJob) throw new Error(`Job ${jobId} cannot be cancelled by its source`)
+      return owner.cancelJob(jobId)
+    }
+  }
+  if (sources.length > 0 && sources.every(source => source.deleteJob)) {
+    combined.deleteJob = async (jobId) => {
+      const owner = ownerFor(jobId)
+      if (!owner.deleteJob) throw new Error(`Job ${jobId} cannot be deleted by its source`)
+      return owner.deleteJob(jobId)
+    }
+  }
+  // Never report a successful combined clear after mutating only a subset.
+  // Without bulk support from every source, the job center can still fall
+  // back to this source's id-routed deleteJob method when all owners expose it.
+  if (sources.length > 0 && sources.every(source => source.clearFinishedJobs)) {
+    combined.clearFinishedJobs = async () => {
+      const results = await Promise.all(
+        sources.map(source => source.clearFinishedJobs!()),
+      )
+      return results.every((result): result is number => typeof result === 'number')
+        ? results.reduce((total, result) => total + result, 0)
+        : undefined
+    }
+  }
+  if (sources.some(source => source.dispose)) {
+    combined.dispose = () => {
+      const errors: unknown[] = []
+      for (const source of sources) {
+        try {
+          source.dispose?.()
+        } catch (cause) {
+          errors.push(cause)
+        }
+      }
+      if (errors.length === 1) throw errors[0]
+      if (errors.length > 1) throw new PluginJobSourceDisposeError(errors)
+    }
+  }
+  return combined
+}
+
+class PluginJobSourceDisposeError extends Error {
+  readonly cause: unknown
+  readonly errors: readonly unknown[]
+
+  constructor(errors: readonly unknown[]) {
+    super('Failed to dispose plugin job sources')
+    this.name = 'PluginJobSourceDisposeError'
+    this.cause = errors[0]
+    this.errors = Object.freeze([...errors])
+  }
+}
+
+function duplicatePluginJobId(jobId: string): Error {
+  return new Error(`Duplicate plugin job id across combined sources: ${jobId}`)
+}
+
+/** @deprecated Prefer a {@link PluginJobCenterSource}. */
 export interface JobsStatusTrayAdapter {
   listJobs?: () => Promise<JobListPayload | readonly JobStateInput[]>
   cancelJob?: (job: JobState) => Promise<JobStateInput | void>
@@ -33,24 +154,34 @@ export interface JobsStatusTrayAdapter {
   clearFinishedJobs?: (jobs: readonly JobState[]) => Promise<number | void>
 }
 
-export interface UseJobsStatusTrayOptions {
+export interface UsePluginJobCenterOptions {
+  source?: MaybeRefOrGetter<PluginJobCenterSource | undefined>
+  /** @deprecated Pass a source with its canonical jobs ref. */
   jobs?: MaybeRefOrGetter<readonly JobStateInput[] | undefined>
+  /** @deprecated Pass source actions instead. */
   adapter?: MaybeRefOrGetter<JobsStatusTrayAdapter | undefined>
+  /** @deprecated Event handling belongs to the source runtime. */
   eventStream?: MaybeRefOrGetter<UsePluginEventStreamReturn<JobStreamData> | undefined>
   loadOnMount?: boolean
 }
 
+export interface UseJobsStatusTrayOptions extends UsePluginJobCenterOptions {}
+
 export interface JobStreamMessage {
   event: string
   data: JobStreamData
 }
 
-export interface UseJobsStatusTrayReturn {
-  jobs: ShallowRef<JobState[]>
+export interface UsePluginJobCenterReturn {
+  jobs: ComputedRef<JobState[]>
   activeJobs: ComputedRef<JobState[]>
   historyJobs: ComputedRef<JobState[]>
   deletableJobs: ComputedRef<JobState[]>
   featuredJob: ComputedRef<JobState | null>
+  canRefresh: ComputedRef<boolean>
+  canCancel: ComputedRef<boolean>
+  canDelete: ComputedRef<boolean>
+  canClearFinished: ComputedRef<boolean>
   isOpen: Ref<boolean>
   activeTab: Ref<JobsStatusTrayTab>
   isLoading: Ref<boolean>
@@ -67,6 +198,13 @@ export interface UseJobsStatusTrayReturn {
   isPending: (job: JobState) => boolean
 }
 
+export type UseJobsStatusTrayReturn = UsePluginJobCenterReturn
+
+interface LegacyJobsOverride {
+  readonly input: readonly JobStateInput[] | undefined
+  readonly jobs: JobState[]
+}
+
 function responseJobs(
   response: JobListPayload | readonly JobStateInput[],
 ): readonly JobStateInput[] {
@@ -81,11 +219,16 @@ function errorMessage(error: unknown, fallback: string): string {
   return error instanceof Error ? error.message : fallback
 }
 
-/** Headless state and action controller for the standard SDK jobs tray. */
-export function useJobsStatusTray(
-  options: UseJobsStatusTrayOptions = {},
-): UseJobsStatusTrayReturn {
-  const jobs = shallowRef<JobState[]>([])
+/**
+ * Headless controller for plugin job presentation and actions.
+ *
+ * When a source is supplied, every job list is derived directly from that
+ * source. The controller never mirrors source jobs into another ref.
+ */
+export function usePluginJobCenter(
+  options: UsePluginJobCenterOptions = {},
+): UsePluginJobCenterReturn {
+  const legacyOverride = shallowRef<LegacyJobsOverride | null>(null)
   const isOpen = ref(false)
   const activeTab = ref<JobsStatusTrayTab>('active')
   const isLoading = ref(false)
@@ -95,44 +238,70 @@ export function useJobsStatusTray(
   let stateRevision = 0
   let requestGeneration = 0
   let active = true
+  const source = computed(() => toValue(options.source))
   const adapter = computed(() => toValue(options.adapter))
 
+  const jobs = computed<JobState[]>(() => {
+    const currentSource = source.value
+    if (currentSource) {
+      return [...toValue(currentSource.jobs)].map(normalizeJobState)
+    }
+    const input = toValue(options.jobs)
+    const override = legacyOverride.value
+    if (override && override.input === input) return override.jobs
+    return input ? [...input].map(normalizeJobState) : []
+  })
   const activeJobs = computed(() => jobs.value.filter(job => isActiveJobStatus(job.status)))
   const historyJobs = computed(() => jobs.value.filter(job => !isActiveJobStatus(job.status)))
   const deletableJobs = computed(() => historyJobs.value.filter(job => job.can_delete))
   const featuredJob = computed(() => activeJobs.value[0] ?? historyJobs.value[0] ?? null)
+  const canRefresh = computed(() => Boolean(source.value?.refreshJobs || adapter.value?.listJobs))
+  const canCancel = computed(() => Boolean(source.value?.cancelJob || adapter.value?.cancelJob))
+  const canDelete = computed(() => Boolean(source.value?.deleteJob || adapter.value?.deleteJob))
+  const canClearFinished = computed(() => Boolean(
+    source.value?.clearFinishedJobs
+    || source.value?.deleteJob
+    || adapter.value?.clearFinishedJobs
+    || adapter.value?.deleteJob,
+  ))
 
   function bumpJobRevision(jobId: string): void {
     jobRevisions.set(jobId, (jobRevisions.get(jobId) ?? 0) + 1)
   }
 
-  function replaceJobs(nextJobs: readonly JobStateInput[]): void {
+  function replaceLegacyJobs(nextJobs: readonly JobStateInput[]): void {
     const normalized = nextJobs.map(normalizeJobState)
     const touchedJobIds = new Set([
       ...jobs.value.map(job => job.job_id),
       ...normalized.map(job => job.job_id),
     ])
     touchedJobIds.forEach(bumpJobRevision)
-    jobs.value = normalized
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: normalized,
+    }
     stateRevision += 1
   }
 
-  function upsertJob(nextJob: JobStateInput): void {
+  function upsertLegacyJob(nextJob: JobStateInput): void {
     const normalized = normalizeJobState(nextJob)
     const existingIndex = jobs.value.findIndex(job => job.job_id === normalized.job_id)
-    if (existingIndex === -1) {
-      jobs.value = [normalized, ...jobs.value]
-    } else {
-      const nextJobs = [...jobs.value]
-      nextJobs[existingIndex] = normalized
-      jobs.value = nextJobs
+    const nextJobs = [...jobs.value]
+    if (existingIndex === -1) nextJobs.unshift(normalized)
+    else nextJobs[existingIndex] = normalized
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: nextJobs,
     }
     bumpJobRevision(normalized.job_id)
     stateRevision += 1
   }
 
-  function removeJobs(jobIds: Set<string>): void {
-    jobs.value = jobs.value.filter(job => !jobIds.has(job.job_id))
+  function removeLegacyJobs(jobIds: Set<string>): void {
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: jobs.value.filter(job => !jobIds.has(job.job_id)),
+    }
     jobIds.forEach(bumpJobRevision)
     stateRevision += 1
   }
@@ -145,21 +314,22 @@ export function useJobsStatusTray(
   }
 
   function applyStreamMessage(message: JobStreamMessage): void {
-    if (!active) return
+    if (!active || source.value) return
     if (message.event === 'snapshot' && isSnapshotPayload(message.data)) {
-      replaceJobs(message.data.jobs)
+      replaceLegacyJobs(message.data.jobs)
       return
     }
     if (
       (message.event === 'job' || message.event === 'terminal')
       && !isSnapshotPayload(message.data)
     ) {
-      upsertJob(message.data)
+      upsertLegacyJob(message.data)
     }
   }
 
   async function refresh(): Promise<boolean> {
-    const listJobs = adapter.value?.listJobs
+    const currentSource = source.value
+    const listJobs = currentSource?.refreshJobs ?? adapter.value?.listJobs
     if (!listJobs) return false
     const generation = ++requestGeneration
     const revision = stateRevision
@@ -170,7 +340,7 @@ export function useJobsStatusTray(
       if (!active || generation !== requestGeneration || revision !== stateRevision) {
         return false
       }
-      replaceJobs(responseJobs(response))
+      if (!currentSource && response) replaceLegacyJobs(responseJobs(response))
       return true
     } catch (cause) {
       if (active && generation === requestGeneration) {
@@ -183,18 +353,21 @@ export function useJobsStatusTray(
   }
 
   async function cancelJob(job: JobState): Promise<boolean> {
-    const cancel = adapter.value?.cancelJob
-    if (!job.can_cancel || !cancel || pendingJobIds.value.has(job.job_id)) {
+    const sourceCancel = source.value?.cancelJob
+    const adapterCancel = adapter.value?.cancelJob
+    if (!job.can_cancel || (!sourceCancel && !adapterCancel) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
     const revision = jobRevisions.get(job.job_id) ?? 0
     setPending(job.job_id, true)
     error.value = null
     try {
-      const updated = await cancel(job)
+      const updated = sourceCancel
+        ? await sourceCancel(job.job_id)
+        : await adapterCancel!(job)
       if (!active) return false
-      if (revision === (jobRevisions.get(job.job_id) ?? 0)) {
-        if (updated) upsertJob(updated)
+      if (!sourceCancel && revision === (jobRevisions.get(job.job_id) ?? 0)) {
+        if (updated) upsertLegacyJob(updated)
         else await refresh()
       }
       return true
@@ -207,17 +380,22 @@ export function useJobsStatusTray(
   }
 
   async function deleteJob(job: JobState): Promise<boolean> {
-    const deleteJobWithAdapter = adapter.value?.deleteJob
-    if (!job.can_delete || !deleteJobWithAdapter || pendingJobIds.value.has(job.job_id)) {
+    const sourceDelete = source.value?.deleteJob
+    const adapterDelete = adapter.value?.deleteJob
+    if (!job.can_delete || (!sourceDelete && !adapterDelete) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
     setPending(job.job_id, true)
     error.value = null
     try {
-      const deleted = await deleteJobWithAdapter(job)
+      const deleted = sourceDelete
+        ? await sourceDelete(job.job_id)
+        : await adapterDelete!(job)
       if (!active) return false
-      if (deleted === false) await refresh()
-      else removeJobs(new Set([job.job_id]))
+      if (!sourceDelete) {
+        if (deleted === false) await refresh()
+        else removeLegacyJobs(new Set([job.job_id]))
+      }
       return deleted !== false
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to delete job')
@@ -232,6 +410,16 @@ export function useJobsStatusTray(
     if (targets.length === 0) return false
     error.value = null
     try {
+      const currentSource = source.value
+      if (currentSource?.clearFinishedJobs) {
+        const deleted = await currentSource.clearFinishedJobs()
+        if (!active) return false
+        return typeof deleted !== 'number' || deleted === targets.length
+      }
+      if (currentSource?.deleteJob) {
+        const results = await Promise.all(targets.map(job => deleteJob(job)))
+        return results.every(Boolean)
+      }
       const currentAdapter = adapter.value
       if (currentAdapter?.clearFinishedJobs) {
         const deleted = await currentAdapter.clearFinishedJobs(targets)
@@ -240,7 +428,7 @@ export function useJobsStatusTray(
           await refresh()
           return false
         }
-        removeJobs(new Set(targets.map(job => job.job_id)))
+        removeLegacyJobs(new Set(targets.map(job => job.job_id)))
         return true
       }
       if (!currentAdapter?.deleteJob) return false
@@ -252,16 +440,6 @@ export function useJobsStatusTray(
     }
   }
 
-  if (options.jobs !== undefined) {
-    watch(
-      () => toValue(options.jobs),
-      value => {
-        if (value) replaceJobs(value)
-      },
-      { immediate: true, deep: true },
-    )
-  }
-
   if (options.eventStream !== undefined) {
     watch(
       () => toValue(options.eventStream)?.lastMessage.value ?? null,
@@ -286,6 +464,10 @@ export function useJobsStatusTray(
     historyJobs,
     deletableJobs,
     featuredJob,
+    canRefresh,
+    canCancel,
+    canDelete,
+    canClearFinished,
     isOpen,
     activeTab,
     isLoading,
@@ -302,3 +484,10 @@ export function useJobsStatusTray(
     isPending: job => pendingJobIds.value.has(job.job_id),
   }
 }
+
+/** Backward-compatible name for the plugin job-center controller. */
+export function useJobsStatusTray(
+  options: UseJobsStatusTrayOptions = {},
+): UseJobsStatusTrayReturn {
+  return usePluginJobCenter(options)
+}