@morscherlab/mint-sdk 1.0.56 → 1.0.57

package/src/composables/useAnalysisArtifacts.ts

@@ -0,0 +1,305 @@
+import {
+  computed,
+  ref,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import { useApi } from './useApi'
+import { useRequestSyncState } from './useRequestSyncState'
+import {
+  getInjectedPlatformContext,
+  resolveCurrentExperimentId,
+} from './platformContextHelpers'
+import type {
+  AnalysisArtifactDetail,
+  AnalysisArtifactListResponse,
+  AnalysisArtifactMetadataUpdate,
+  AnalysisArtifactStatusFilter,
+  AnalysisArtifactSummary,
+} from '../types/analysisArtifactTypes'
+
+export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes'
+
+export interface UseAnalysisArtifactsOptions {
+  /** Experiment id; defaults to platform injection or URL. Refetches when it changes. */
+  experimentId?: MaybeRefOrGetter<number | undefined>
+  /** Override API base URL. */
+  apiBaseUrl?: string
+  /** Scope to a single owning plugin; omit or null to keep all plugins. */
+  pluginId?: MaybeRefOrGetter<string | null | undefined>
+  /** Always request archived artifacts alongside active ones. */
+  includeArchived?: MaybeRefOrGetter<boolean | undefined>
+  /** Fetch as soon as an experiment id is available. */
+  immediate?: boolean
+}
+
+export interface UseAnalysisArtifactsReturn {
+  /** Fetched artifacts, scoped to pluginId when set. */
+  artifacts: ComputedRef<AnalysisArtifactSummary[]>
+  /** Artifacts after applying statusFilter, pluginFilter, and search. */
+  visibleArtifacts: ComputedRef<AnalysisArtifactSummary[]>
+  /** Detail loaded by the last successful getDetail call, or null. */
+  selectedDetail: Ref<AnalysisArtifactDetail | null>
+  /** Resolved experiment id from options, platform injection, or URL. */
+  currentExperimentId: ComputedRef<number | undefined>
+  /** Whether an experiment id is available. */
+  hasCurrentExperiment: ComputedRef<boolean>
+  /** Whether any list or detail fetch is in progress. */
+  isLoading: ComputedRef<boolean>
+  /** Whether any archive/restore/metadata mutation is in progress. */
+  isMutating: ComputedRef<boolean>
+  /** Error message from the last failed operation, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful load, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Case-insensitive filter over display_name and artifact_key. */
+  search: Ref<string>
+  /** Lifecycle filter; widening past "active" refetches with include_archived. */
+  statusFilter: Ref<AnalysisArtifactStatusFilter>
+  /** Plugin filter applied to visibleArtifacts, or null for all plugins. */
+  pluginFilter: Ref<string | null>
+  /** Fetch the artifact list for the current experiment. */
+  list: () => Promise<AnalysisArtifactSummary[]>
+  /** Alias of list. */
+  refresh: () => Promise<AnalysisArtifactSummary[]>
+  /** Fetch one artifact with its result payload; null when it fails or is superseded. */
+  getDetail: (artifactId: number) => Promise<AnalysisArtifactDetail | null>
+  /** Update display_name and/or note; resolves to the updated summary or null. */
+  updateMetadata: (
+    artifactId: number,
+    updates: AnalysisArtifactMetadataUpdate,
+  ) => Promise<AnalysisArtifactSummary | null>
+  /** Archive an artifact; resolves to the updated summary or null. */
+  archive: (artifactId: number) => Promise<AnalysisArtifactSummary | null>
+  /** Restore an archived artifact; resolves to the updated summary or null. */
+  restore: (artifactId: number) => Promise<AnalysisArtifactSummary | null>
+  /** Whether a key exists in the loaded artifacts (no network call). */
+  hasArtifactKey: (artifactKey: string) => boolean
+  /** Reset artifacts, selection, and error. */
+  clear: () => void
+}
+
+/** Lists and manages analysis artifacts through the user-facing platform API. */
+export function useAnalysisArtifacts(
+  options: UseAnalysisArtifactsOptions = {},
+): UseAnalysisArtifactsReturn {
+  const injectedContext = getInjectedPlatformContext()
+  const api = useApi({ baseUrl: options.apiBaseUrl ?? injectedContext?.platformApiUrl })
+
+  const currentExperimentId = computed<number | undefined>(
+    () => toValue(options.experimentId) ?? resolveCurrentExperimentId(injectedContext),
+  )
+  const hasCurrentExperiment = computed(() => currentExperimentId.value !== undefined)
+  const scopePluginId = computed(() => toValue(options.pluginId) ?? null)
+
+  const request = useRequestSyncState('Analysis artifact request failed.')
+  const fetchedArtifacts = ref<AnalysisArtifactSummary[]>([])
+  const selectedDetail = ref<AnalysisArtifactDetail | null>(null)
+
+  // Counters, not booleans: overlapping requests must not clear each other's flag.
+  const loadingCount = ref(0)
+  const mutatingCount = ref(0)
+  const isLoading = computed(() => loadingCount.value > 0)
+  const isMutating = computed(() => mutatingCount.value > 0)
+
+  const search = ref('')
+  const statusFilter = ref<AnalysisArtifactStatusFilter>('active')
+  const pluginFilter = ref<string | null>(null)
+
+  const needsArchived = computed(
+    () => Boolean(toValue(options.includeArchived)) || statusFilter.value !== 'active',
+  )
+
+  const artifacts = computed(() => (
+    scopePluginId.value
+      ? fetchedArtifacts.value.filter((artifact) => artifact.plugin_id === scopePluginId.value)
+      : fetchedArtifacts.value
+  ))
+
+  const visibleArtifacts = computed(() => {
+    const query = search.value.trim().toLowerCase()
+    return artifacts.value.filter((artifact) => {
+      if (statusFilter.value !== 'all' && artifact.status !== statusFilter.value) return false
+      if (pluginFilter.value && artifact.plugin_id !== pluginFilter.value) return false
+      if (!query) return true
+      return (
+        artifact.display_name.toLowerCase().includes(query)
+        || artifact.artifact_key.toLowerCase().includes(query)
+      )
+    })
+  })
+
+  // Generation tokens: a superseded response must commit nothing — not rows, not the
+  // shared error, not lastLoadedAt — or a late failure would bury fresh results.
+  let listToken = 0
+  let detailToken = 0
+  const hasRequestedList = ref(false)
+
+  function currentExperimentIdOrError(action: string): number | undefined {
+    const id = currentExperimentId.value
+    if (id === undefined) {
+      request.setError(`No current experiment is selected for ${action}`)
+      return undefined
+    }
+    return id
+  }
+
+  function replaceArtifact(summary: AnalysisArtifactSummary): void {
+    const index = fetchedArtifacts.value.findIndex((artifact) => artifact.id === summary.id)
+    if (index >= 0) {
+      fetchedArtifacts.value.splice(index, 1, summary)
+    }
+  }
+
+  async function list(): Promise<AnalysisArtifactSummary[]> {
+    const experimentId = currentExperimentIdOrError('listing analysis artifacts')
+    if (experimentId === undefined) {
+      fetchedArtifacts.value = []
+      return []
+    }
+    const token = ++listToken
+    hasRequestedList.value = true
+    loadingCount.value += 1
+    request.clearError()
+    try {
+      const data = await api.get<AnalysisArtifactListResponse>(
+        `/experiments/${experimentId}/analysis-artifacts?include_archived=${needsArchived.value}`,
+      )
+      if (token !== listToken) return artifacts.value
+      // Copy: replaceArtifact splices in place, and the response array is not ours.
+      fetchedArtifacts.value = [...(data?.artifacts ?? [])]
+      request.markLoaded()
+      return artifacts.value
+    } catch (err) {
+      if (token !== listToken) return []
+      request.setError(err)
+      fetchedArtifacts.value = []
+      return []
+    } finally {
+      loadingCount.value -= 1
+    }
+  }
+
+  async function getDetail(artifactId: number): Promise<AnalysisArtifactDetail | null> {
+    const experimentId = currentExperimentIdOrError('loading an analysis artifact')
+    if (experimentId === undefined) return null
+    const token = ++detailToken
+    loadingCount.value += 1
+    request.clearError()
+    try {
+      const detail = await api.get<AnalysisArtifactDetail>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}`,
+      )
+      if (token !== detailToken) return null
+      selectedDetail.value = detail
+      request.markLoaded()
+      return detail
+    } catch (err) {
+      if (token !== detailToken) return null
+      request.setError(err)
+      return null
+    } finally {
+      loadingCount.value -= 1
+    }
+  }
+
+  async function mutate(
+    action: string,
+    operation: (experimentId: number) => Promise<AnalysisArtifactSummary>,
+  ): Promise<AnalysisArtifactSummary | null> {
+    const experimentId = currentExperimentIdOrError(action)
+    if (experimentId === undefined) return null
+    mutatingCount.value += 1
+    request.clearError()
+    try {
+      const summary = await operation(experimentId)
+      replaceArtifact(summary)
+      request.markSaved()
+      return summary
+    } catch (err) {
+      request.setError(err)
+      return null
+    } finally {
+      mutatingCount.value -= 1
+    }
+  }
+
+  async function updateMetadata(
+    artifactId: number,
+    updates: AnalysisArtifactMetadataUpdate,
+  ): Promise<AnalysisArtifactSummary | null> {
+    return mutate('updating artifact metadata', (experimentId) =>
+      api.patch<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}`,
+        updates,
+      ))
+  }
+
+  async function archive(artifactId: number): Promise<AnalysisArtifactSummary | null> {
+    return mutate('archiving an analysis artifact', (experimentId) =>
+      api.post<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}/archive`,
+      ))
+  }
+
+  async function restore(artifactId: number): Promise<AnalysisArtifactSummary | null> {
+    return mutate('restoring an analysis artifact', (experimentId) =>
+      api.post<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}/restore`,
+      ))
+  }
+
+  function hasArtifactKey(artifactKey: string): boolean {
+    return artifacts.value.some((artifact) => artifact.artifact_key === artifactKey)
+  }
+
+  /** Drop experiment-scoped state and orphan every in-flight response. */
+  function clear(): void {
+    listToken += 1
+    detailToken += 1
+    fetchedArtifacts.value = []
+    selectedDetail.value = null
+    request.clearError()
+  }
+
+  // Refetch when the scope changes or archived rows are newly needed. `immediate`
+  // covers a late-resolving experiment id; otherwise stay quiet until something
+  // has asked for a list at least once.
+  watch([currentExperimentId, needsArchived], ([experimentId], [previousExperimentId]) => {
+    if (experimentId !== previousExperimentId) {
+      // Scope changed: the previous experiment's rows and any in-flight reply for
+      // them must not survive into the new one.
+      clear()
+    }
+    if (experimentId === undefined) return
+    if (options.immediate || hasRequestedList.value) {
+      void list()
+    }
+  }, { immediate: options.immediate })
+
+  return {
+    artifacts,
+    visibleArtifacts,
+    selectedDetail,
+    currentExperimentId,
+    hasCurrentExperiment,
+    isLoading,
+    isMutating,
+    error: request.error,
+    lastLoadedAt: request.lastLoadedAt,
+    search,
+    statusFilter,
+    pluginFilter,
+    list,
+    refresh: list,
+    getDetail,
+    updateMetadata,
+    archive,
+    restore,
+    hasArtifactKey,
+    clear,
+  }
+}

package/src/styles/components/artifact-save-dialog.css

@@ -0,0 +1,17 @@
+.mint-artifact-save-dialog {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.mint-artifact-save-dialog__immutable {
+  margin: 0;
+  font-size: 0.8125rem;
+  color: var(--text-muted);
+}
+
+.mint-artifact-save-dialog__immutable code {
+  font-family: var(--font-mono, 'Fira Code', monospace);
+  font-size: 0.75rem;
+  color: var(--text-secondary);
+}

package/src/styles/components/artifact-selector-modal.css

@@ -0,0 +1,216 @@
+/* ArtifactSelectorModal Component Styles */
+
+.mint-artifact-selector {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  min-height: 0;
+}
+
+/* Filter row */
+.mint-artifact-selector__filters-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.mint-artifact-selector__search {
+  flex: 1;
+  min-width: 10rem;
+}
+
+.mint-artifact-selector__filter-select {
+  flex-shrink: 0;
+  width: 10rem;
+}
+
+/* Loading skeleton */
+.mint-artifact-selector__skeleton {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+
+.mint-artifact-selector__skeleton-row {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  background-color: var(--bg-primary);
+}
+
+.mint-artifact-selector__skeleton-content {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+/* Error */
+.mint-artifact-selector__error {
+  padding: 0.75rem;
+  border: 1px solid color-mix(in srgb, var(--mint-error) 30%, transparent);
+  border-radius: var(--radius-md);
+  background-color: var(--mint-error-bg);
+  color: var(--mint-error);
+  font-size: 0.875rem;
+}
+
+/* Scrollable list */
+.mint-artifact-selector__list {
+  max-height: min(28rem, calc(100vh - 16rem));
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  background-color: var(--bg-primary);
+  scrollbar-width: thin;
+  overscroll-behavior: contain;
+}
+
+.mint-artifact-selector__list::-webkit-scrollbar {
+  width: 0.5rem;
+}
+
+.mint-artifact-selector__list::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.mint-artifact-selector__list::-webkit-scrollbar-thumb {
+  background-color: color-mix(in srgb, var(--text-muted) 30%, transparent);
+  border: 2px solid transparent;
+  border-radius: 9999px;
+  background-clip: content-box;
+}
+
+/* Row */
+.mint-artifact-selector__row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-height: 4.125rem;
+  padding: 0.75rem 1rem 0.75rem 1.125rem;
+  cursor: pointer;
+  border-left: 0 solid transparent;
+  border-bottom: 1px solid var(--border-light);
+  background-color: var(--bg-primary);
+  transition:
+    background-color 0.15s ease,
+    box-shadow 0.15s ease;
+}
+
+.mint-artifact-selector__row:hover {
+  background-color: var(--bg-hover);
+}
+
+.mint-artifact-selector__row--active {
+  box-shadow: inset 3px 0 0 var(--color-primary);
+  background-color: var(--color-primary-soft);
+}
+
+.mint-artifact-selector__row--active:hover {
+  background-color: var(--color-primary-soft);
+}
+
+/* Keyboard focused row */
+.mint-artifact-selector__row--focused {
+  background-color: var(--bg-hover);
+  outline: none;
+  box-shadow:
+    inset 0 0 0 2px var(--color-primary),
+    inset 3px 0 0 var(--color-primary);
+}
+
+.mint-artifact-selector__row--active.mint-artifact-selector__row--focused {
+  background-color: var(--color-primary-soft);
+}
+
+.mint-artifact-selector__row--archived .mint-artifact-selector__name,
+.mint-artifact-selector__row--archived .mint-artifact-selector__meta {
+  opacity: var(--mint-disabled-opacity, 0.6);
+}
+
+/* Row content */
+.mint-artifact-selector__row-content {
+  flex: 1;
+  min-width: 0;
+}
+
+.mint-artifact-selector__name {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--text-primary);
+  min-width: 0;
+}
+
+.mint-artifact-selector__key {
+  font-family: var(--font-mono, 'Fira Code', monospace);
+  font-size: 0.6875rem;
+  padding: 0.0625rem 0.375rem;
+  border-radius: var(--radius-sm);
+  background-color: var(--bg-secondary);
+  color: var(--text-secondary);
+  white-space: nowrap;
+}
+
+.mint-artifact-selector__meta {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  font-size: 0.75rem;
+  color: var(--text-muted);
+  margin-top: 0.125rem;
+}
+
+.mint-artifact-selector__plugin {
+  font-family: var(--font-mono, 'Fira Code', monospace);
+  color: var(--text-secondary);
+}
+
+/* Status pill + row actions */
+.mint-artifact-selector__row-side {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-shrink: 0;
+}
+
+.mint-artifact-selector__action {
+  padding: 0.25rem 0.5rem;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+  cursor: pointer;
+  white-space: nowrap;
+  transition:
+    background-color 0.15s ease,
+    border-color 0.15s ease,
+    color 0.15s ease;
+}
+
+.mint-artifact-selector__action:hover:not(:disabled) {
+  border-color: var(--color-primary);
+  color: var(--color-primary);
+  background-color: var(--bg-hover);
+}
+
+.mint-artifact-selector__action:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+
+.mint-artifact-selector__action:disabled {
+  opacity: var(--mint-disabled-opacity, 0.6);
+  cursor: not-allowed;
+}

package/src/styles/index.css

@@ -85,5 +85,7 @@
 @import './components/experiment-data-viewer.css';
 @import './components/experiment-code-badge.css';
 @import './components/experiment-selector-modal.css';
+@import './components/artifact-selector-modal.css';
+@import './components/artifact-save-dialog.css';
 @import './components/experiment-popover.css';
 @import './components/fit-panel.css';

package/src/types/analysisArtifactTypes.ts

@@ -0,0 +1,119 @@
+import type { TreeNode } from './componentLabTypes'
+import type { SummaryData } from './componentWorkflowTypes'
+
+/** Result schema identifier for file-backed analysis artifacts. */
+export const ANALYSIS_FILE_ARTIFACT_SCHEMA = 'mint.analysis_file.v1'
+
+/** Known artifact lifecycle states; kept open for forward compatibility. */
+export type AnalysisArtifactStatus = 'active' | 'archived' | (string & {})
+
+/** Status filter vocabulary for artifact lists. */
+export type AnalysisArtifactStatusFilter = 'active' | 'archived' | 'all'
+
+/** Summary row returned by GET /experiments/{id}/analysis-artifacts. */
+export interface AnalysisArtifactSummary {
+  id: number
+  experiment_id: number
+  plugin_id: string
+  artifact_key: string
+  display_name: string
+  note?: string | null
+  status: AnalysisArtifactStatus
+  result_keys: string[]
+  created_at?: string | null
+  updated_at?: string | null
+  archived_at?: string | null
+  archived_by?: number | null
+}
+
+/** Full artifact returned by GET /experiments/{id}/analysis-artifacts/{artifactId}. */
+export interface AnalysisArtifactDetail extends AnalysisArtifactSummary {
+  result: Record<string, unknown>
+  tree: TreeNode[]
+  summary: SummaryData | null
+}
+
+/** Response of GET /experiments/{id}/analysis-artifacts. */
+export interface AnalysisArtifactListResponse {
+  artifacts: AnalysisArtifactSummary[]
+}
+
+/** Body of PATCH /experiments/{id}/analysis-artifacts/{artifactId}. */
+export interface AnalysisArtifactMetadataUpdate {
+  display_name?: string
+  /** undefined = keep, string = set, null = clear. */
+  note?: string | null
+}
+
+/** How a save payload should be applied by the plugin backend. */
+export type ArtifactSaveMode = 'create' | 'upsert' | 'update'
+
+interface ArtifactSavePayloadBase {
+  experimentId: number
+  artifactKey: string
+}
+
+/**
+ * JSON artifact save — handler maps to save_analysis_artifact, which upserts by key.
+ * That call only assigns display_name/note when they are provided, and cannot clear
+ * either; use the metadata PATCH (useAnalysisArtifacts.updateMetadata) for that.
+ */
+export interface JsonArtifactSavePayload extends ArtifactSavePayloadBase {
+  kind: 'json'
+  mode: 'create' | 'upsert'
+  result: Record<string, unknown>
+  displayName?: string
+  note?: string
+}
+
+/** File artifact create — handler maps to save_analysis_file_artifact (create-only: a reused key conflicts). */
+export interface FileArtifactCreatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'create'
+  file: File
+  /** Maps to the Python `kind=` argument (defaults to "file" backend-side). */
+  fileKind: string
+  filename?: string
+  displayName?: string
+  note?: string
+  contentType?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * File artifact replacement — handler maps to update_analysis_file_artifact
+ * (transactional CAS replace). `kind` and `filename` are immutable backend-side, so
+ * `fileKind` echoes the artifact's existing kind and no filename is carried. `note`
+ * is three-state: omitted preserves, null clears, a string sets. `metadata` REPLACES
+ * the previous result metadata rather than merging, so it always carries the full
+ * intended map — omitting it clears whatever was there.
+ */
+export interface FileArtifactUpdatePayload extends ArtifactSavePayloadBase {
+  kind: 'file'
+  mode: 'update'
+  file: File
+  fileKind: string
+  note?: string | null
+  contentType?: string
+  metadata?: Record<string, unknown>
+}
+
+export type ArtifactSavePayload =
+  | JsonArtifactSavePayload
+  | FileArtifactCreatePayload
+  | FileArtifactUpdatePayload
+
+/** Optional handler result; cleanupPending surfaces AnalysisFileArtifactUpdate.cleanup_pending. */
+export interface ArtifactSaveResult {
+  artifact?: AnalysisArtifactSummary
+  cleanupPending?: boolean
+}
+
+/**
+ * Plugin-supplied save handler. The dialog never writes to the platform;
+ * the handler forwards the payload to the plugin backend, which calls
+ * save_analysis_artifact / save_analysis_file_artifact / update_analysis_file_artifact.
+ */
+export type ArtifactSaveHandler = (
+  payload: ArtifactSavePayload,
+) => Promise<ArtifactSaveResult | void>

package/src/types/index.ts

@@ -176,6 +176,23 @@ export type {
   TreeNode,
 } from './components'
 
+export type {
+  AnalysisArtifactStatus,
+  AnalysisArtifactStatusFilter,
+  AnalysisArtifactSummary,
+  AnalysisArtifactDetail,
+  AnalysisArtifactListResponse,
+  AnalysisArtifactMetadataUpdate,
+  ArtifactSaveMode,
+  JsonArtifactSavePayload,
+  FileArtifactCreatePayload,
+  FileArtifactUpdatePayload,
+  ArtifactSavePayload,
+  ArtifactSaveResult,
+  ArtifactSaveHandler,
+} from './analysisArtifactTypes'
+export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from './analysisArtifactTypes'
+
 export type {
   JobListPayload,
   JobProgress,