@morscherlab/mint-sdk 1.2.0-beta.9 → 1.2.0

package/src/__tests__/composables/useFileBrowser.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+const mockGet = vi.fn()
+vi.mock('../../composables/useApi', () => ({
+  useApi: () => ({ get: mockGet }),
+}))
+
+import { effectScope, nextTick, ref } from 'vue'
+
+import { useFileBrowser } from '../../composables/useFileBrowser'
+
+const MOUNTS = {
+  mounts: [
+    { id: 'seq', label: '/mnt/sequencer-01', available: false },
+    { id: 'qe', label: '/mnt/instrument-qe', available: true },
+  ],
+}
+
+const LISTING = {
+  mount_id: 'qe',
+  path: 'raw',
+  parent: '',
+  breadcrumbs: [{ label: '/mnt/instrument-qe', path: '' }, { label: 'raw', path: 'raw' }],
+  entries: [
+    { name: 'blanks', path: 'raw/blanks', kind: 'directory', child_count: 6 },
+    { name: 'a.raw', path: 'raw/a.raw', kind: 'file', size_bytes: 10, extension: '.raw' },
+  ],
+  total_count: 2,
+  match_count: 1,
+}
+
+beforeEach(() => {
+  mockGet.mockReset()
+})
+
+describe('useFileBrowser', () => {
+  it('should load the configured mounts', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.mounts.value.map(m => m.id)).toEqual(['seq', 'qe'])
+  })
+
+  // An offline mount must not be the one we open on.
+  it('should open the first available mount', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=qe')
+  })
+
+  // 'nas' is listed after 'qe', so choosing it proves the preference is honoured
+  // rather than the first-available fallback happening to win.
+  it('should honour an explicit initial mount when it is reachable', async () => {
+    mockGet
+      .mockResolvedValueOnce({ mounts: [...MOUNTS.mounts, { id: 'nas', label: '/mnt/nas', available: true }] })
+      .mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser({ initialMountId: 'nas' })
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=nas')
+  })
+
+  it('should expose the listing entries', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.entries.value.map(e => e.name)).toEqual(['blanks', 'a.raw'])
+  })
+
+  it('should expose the breadcrumb trail', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.breadcrumbs.value.map(c => c.label)).toEqual(['/mnt/instrument-qe', 'raw'])
+  })
+
+  it('should send the configured type rules', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser({ typeRules: ['.raw', '.mzML'] })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(mockGet.mock.calls[0][0]).toContain('type_rules=.raw&type_rules=.mzML')
+  })
+
+  it('should surface a listing failure', async () => {
+    mockGet.mockRejectedValue(new Error('Mount is offline'))
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.error.value).toContain('Mount is offline')
+  })
+
+  it('should empty the listing when a request fails', async () => {
+    mockGet.mockRejectedValue(new Error('nope'))
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.entries.value).toEqual([])
+  })
+
+  // A slow response for the folder you left must not overwrite the one you are in.
+  it('should ignore a superseded listing response', async () => {
+    let resolveSlow: (value: unknown) => void = () => {}
+    const slow = new Promise(resolve => { resolveSlow = resolve })
+    mockGet.mockReturnValueOnce(slow).mockResolvedValueOnce(LISTING)
+
+    const browser = useFileBrowser()
+    const first = browser.navigate({ mount_id: 'qe', path: 'stale' })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    resolveSlow({ ...LISTING, path: 'stale', entries: [] })
+    await first
+
+    expect(browser.path.value).toBe('raw')
+  })
+
+  it('should take the current folder into the selection', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+
+    expect(browser.selected.value).toMatchObject([{ mount_id: 'qe', path: 'raw', kind: 'directory' }])
+  })
+
+  it('should not take the same folder twice', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+    browser.selectCurrentFolder()
+
+    expect(browser.selected.value).toHaveLength(1)
+  })
+
+  it('should clear the selection', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+    browser.clear()
+
+    expect(browser.selected.value).toEqual([])
+  })
+
+  it('should report the unfiltered total count', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.totalCount.value).toBe(2)
+  })
+
+  it('should not be loading once a request settles', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.isLoading.value).toBe(false)
+  })
+})
+
+describe('useFileBrowser review fixes', () => {
+  it('should skip an offline mount even when named as the initial one', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser({ initialMountId: 'seq' })
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=qe')
+  })
+
+  // No configured mounts means the routes are absent, not that browsing failed.
+  it('should treat a 404 mount list as no mounts configured', async () => {
+    mockGet.mockRejectedValue({ response: { status: 404 } })
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.error.value).toBeNull()
+  })
+
+  it('should leave the mount list empty when none are configured', async () => {
+    mockGet.mockRejectedValue({ response: { status: 404 } })
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.mounts.value).toEqual([])
+  })
+
+  it('should surface the API error detail rather than the status code', async () => {
+    mockGet.mockRejectedValue({
+      response: { status: 404, data: { detail: "Mount 'nas' is not available" } },
+      message: 'Request failed with status code 404',
+    })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'nas', path: '' })
+
+    expect(browser.error.value).toBe("Mount 'nas' is not available")
+  })
+
+  it('should refetch when the sort changes', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    const before = mockGet.mock.calls.length
+    browser.sort.value = 'size'
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+  })
+
+  it('should refetch when the search changes', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    const before = mockGet.mock.calls.length
+    browser.search.value = 'hela'
+    await new Promise(resolve => setTimeout(resolve, 400))
+
+    expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+  })
+
+  it('should expose how many rows the listing carries', async () => {
+    mockGet.mockResolvedValue({ ...LISTING, shown_count: 2 })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.shownCount.value).toBe(2)
+  })
+
+  it('should expose a truncated listing', async () => {
+    mockGet.mockResolvedValue({ ...LISTING, truncated: true })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.truncated.value).toBe(true)
+  })
+})
+
+
+describe('useFileBrowser selection and request lifecycle', () => {
+  it('never selects an uninitialized or failed directory', async () => {
+    const browser = useFileBrowser()
+    browser.selectCurrentFolder()
+    expect(browser.selected.value).toEqual([])
+    mockGet.mockRejectedValueOnce(new Error('offline'))
+    await browser.navigate({ mount_id: 'nas', path: 'runs' })
+    browser.selectCurrentFolder()
+    expect(browser.selected.value).toEqual([])
+  })
+
+  it('retries the failed destination rather than returning to the previous folder', async () => {
+    mockGet.mockResolvedValueOnce(LISTING).mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce({ ...LISTING, path: 'new' })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    await browser.navigate({ mount_id: 'qe', path: 'new' })
+    await browser.refresh()
+    expect(mockGet.mock.calls.at(-1)?.[0]).toContain('path=new')
+  })
+
+  it('does not let obsolete requests keep the current directory loading', async () => {
+    let finish!: (value: unknown) => void
+    mockGet.mockReturnValueOnce(new Promise(resolve => { finish = resolve })).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    const old = browser.navigate({ mount_id: 'qe', path: 'old' })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    expect(browser.isLoading.value).toBe(false)
+    finish(LISTING)
+    await old
+  })
+
+  it('refreshes when reactive type rules change', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const typeRules = ref(['.raw'])
+    const scope = effectScope()
+    const browser = scope.run(() => useFileBrowser({ typeRules }))!
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    typeRules.value = ['.mzML']
+    await nextTick()
+    expect(mockGet.mock.calls.at(-1)?.[0]).toContain('type_rules=.mzML')
+    scope.stop()
+  })
+
+  it('disposes a pending search without issuing another request', async () => {
+    vi.useFakeTimers()
+    const scope = effectScope()
+    try {
+      mockGet.mockResolvedValue(LISTING)
+      const browser = scope.run(() => useFileBrowser())!
+      await browser.navigate({ mount_id: 'qe', path: 'raw' })
+      browser.search.value = 'abc'
+      await nextTick()
+      const calls = mockGet.mock.calls.length
+      scope.stop()
+      await vi.advanceTimersByTimeAsync(300)
+      expect(mockGet).toHaveBeenCalledTimes(calls)
+    } finally {
+      scope.stop()
+      vi.useRealTimers()
+    }
+  })
+})

package/src/__tests__/composables/useGeneratedAnalysis.test.ts

@@ -2,6 +2,7 @@ import { effectScope } from 'vue'
 import { describe, expect, it, vi } from 'vitest'
 
 import { useGeneratedAnalysis } from '../../composables/useGeneratedAnalysis'
+import { MintApiError } from '../../apiErrors'
 import {
   createGeneratedAnalysisTransport,
   type GeneratedAnalysisTransport,
@@ -701,7 +702,10 @@ describe('useGeneratedAnalysis', () => {
     ])
   })
 
-  it('should recreate an expired session and retry one job with the same request id', async () => {
+  it.each([
+    { detail: 'Session not found' },
+    { code: 'resource.not_found', message: 'Session not found', request_id: 'session-request' },
+  ])('should recreate an expired session and retry one job with the same request id (%j)', async (errorBody) => {
     const storage = memoryStorage()
     const createId = vi.fn()
       .mockReturnValueOnce('tab-1')
@@ -713,7 +717,7 @@ describe('useGeneratedAnalysis', () => {
         id: 'session-1', tab_id: 'tab-1', created_at: '', last_seen_at: '', active_job_ids: [],
       }))
       .mockResolvedValueOnce(response({ jobs: [] }))
-      .mockResolvedValueOnce(response({ detail: 'Session not found' }, 404))
+      .mockResolvedValueOnce(response(errorBody, 404))
       .mockResolvedValueOnce(response({ sessions: [] }))
       .mockResolvedValueOnce(response({
         id: 'session-2', tab_id: 'tab-1', created_at: '', last_seen_at: '', active_job_ids: [],
@@ -796,6 +800,7 @@ describe('useGeneratedAnalysis', () => {
       scope.stop()
     }
 
+    expect(caught).toBeInstanceOf(MintApiError)
     expect({
       status: (caught as { status?: number } | undefined)?.status,
       message: caught instanceof Error ? caught.message : null,

package/src/__tests__/composables/usePlatformFilePickerAdapter.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, expect, it, vi } from 'vitest'
+const { get } = vi.hoisted(() => ({ get: vi.fn() }))
+vi.mock('../../composables/useApi', () => ({ useApi: () => ({ get }) }))
+import {
+  decodePlatformPickerPath,
+  encodePlatformPickerPath,
+  usePlatformFilePickerAdapter,
+} from '../../composables/usePlatformFilePickerAdapter'
+
+beforeEach(() => get.mockReset())
+it('preserves mount and relative path identities with punctuation and Unicode', () => {
+  const path = '测试/one, [2] # ?.raw'
+  expect(decodePlatformPickerPath(encodePlatformPickerPath('instrument', path))).toEqual({
+    mountId: 'instrument',
+    path,
+  })
+  expect(() => decodePlatformPickerPath('["mount"]')).toThrow()
+  expect(() => decodePlatformPickerPath('["", "file"]')).toThrow()
+})
+it('passes cancellation, marks offline mounts, and maps compound extensions', async () => {
+  get
+    .mockResolvedValueOnce({
+      mounts: [
+        { id: 'online', label: 'Instrument', available: true },
+        { id: 'offline', label: 'NAS', available: false },
+      ],
+    })
+    .mockResolvedValueOnce({
+      entries: [{ kind: 'file', path: 'run.mzML.gz', name: 'run.mzML.gz', size_bytes: 7 }],
+    })
+  const adapter = usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
+  const signal = new AbortController().signal
+  const roots = await adapter.listRoot({ signal })
+  expect(roots[1]?.unavailableReason).toContain('offline')
+  const files = await adapter.listChildren(roots[0]!.path, { signal })
+  expect(files[0]).toMatchObject({
+    kind: 'file',
+    format: 'mzML.gz',
+    bytes: 7,
+    parentPath: roots[0]!.path,
+  })
+  expect(get.mock.calls.every((call) => call[1].signal === signal)).toBe(true)
+})
+it('refuses truncated listings rather than returning a partial folder selection', async () => {
+  get.mockResolvedValue({ truncated: true, entries: [] })
+  await expect(
+    usePlatformFilePickerAdapter({ apiBaseUrl: '/api' }).listChildren(
+      encodePlatformPickerPath('a'),
+    ),
+  ).rejects.toThrow('listing limit')
+})
+it('scopes shallow search to one level and recursive search skips offline mounts', async () => {
+  get.mockImplementation(async (url: string) =>
+    url === '/filesystem/mounts'
+      ? {
+          mounts: [
+            { id: 'a', label: 'Instrument', available: true },
+            { id: 'b', label: 'NAS', available: false },
+          ],
+        }
+      : { entries: [{ kind: 'file', path: 'run.raw', name: 'run.raw', size_bytes: 1 }] },
+  )
+  const adapter = usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
+  expect(await adapter.search('run', { path: '', recursive: false })).toEqual([])
+  expect(await adapter.search('run', { path: '', recursive: true })).toHaveLength(1)
+  expect(get.mock.calls.filter((call) => call[0].includes('/browse'))).toHaveLength(1)
+})

package/src/__tests__/composables/usePluginClient.test.ts

@@ -184,6 +184,7 @@ describe('usePluginClient', () => {
 
     expect(requestConfigs[0]!.baseURL).toBe('/api/drp')
     expect(requestConfigs[0]!.url).toBe('/health')
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
   })
 
   it('omits MINT auth transport for a public generated endpoint', async () => {
@@ -396,6 +397,7 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.url).toBe('/schedule/import')
     expect(requestConfigs[0]!.params).toEqual({ instrument_id: 'orbitrap', mode: 'replace' })
     expect(requestConfigs[0]!.headers).toEqual({ 'Content-Type': undefined })
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
     expect(requestBodies[0]).toBeInstanceOf(FormData)
     const form = requestBodies[0] as FormData
     expect(form.get('file')).toBeInstanceOf(Blob)
@@ -462,6 +464,7 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.url).toBe('/schedule/export')
     expect(requestConfigs[0]!.params).toEqual({ instrument_id: 'orbitrap', start: '2026-05-27' })
     expect(requestConfigs[0]!.responseType).toBe('blob')
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
   })
 
   it('downloads generated POST endpoint blobs with the contract body and request options', async () => {

package/src/apiErrors.ts

@@ -0,0 +1,85 @@
+export interface MintApiErrorEnvelope {
+  code: string
+  message: string
+  status: number
+  request_id: string | null
+  details: unknown
+  detail?: unknown
+}
+
+const STATUS_MESSAGES: Readonly<Record<number, string>> = {
+  400: 'Bad request',
+  401: 'Authentication required',
+  403: 'Permission denied',
+  404: 'Resource not found',
+  405: 'Method not allowed',
+  409: 'Conflict',
+  413: 'Payload too large',
+  415: 'Unsupported media type',
+  422: 'Validation error',
+  429: 'Rate limit exceeded',
+  500: 'Internal server error',
+  502: 'Bad gateway',
+  503: 'Service unavailable',
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+/** Public error thrown by typed MINT SDK requests. */
+export class MintApiError extends Error {
+  override readonly name: string = 'MintApiError'
+
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly status: number,
+    readonly requestId: string | null,
+    readonly details: unknown,
+    readonly detail: unknown,
+    readonly body: unknown,
+    readonly cause?: unknown,
+  ) {
+    super(message)
+  }
+}
+
+export interface MintApiErrorOptions {
+  requestId?: string | null
+  cause?: unknown
+}
+
+/** Normalize current typed envelopes and the previous FastAPI detail shape. */
+export function mintApiErrorFromResponse(
+  status: number,
+  payload: unknown,
+  options: MintApiErrorOptions = {},
+): MintApiError {
+  const body = asRecord(payload)
+  const legacyDetail = body?.detail
+  const inner = asRecord(legacyDetail) ?? body
+  const text = (value: unknown): string | undefined =>
+    typeof value === 'string' && value ? value : undefined
+  // Complete envelopes own the public code; older wrappers defer to the plugin payload.
+  const canonical = typeof body?.status === 'number' && text(body.code) && text(body.message)
+  const code = (canonical ? text(body.code) : text(inner?.error) ?? text(inner?.code))
+    ?? text(body?.code) ?? 'unknown'
+  const message = (canonical ? text(body.message) : text(inner?.message))
+    ?? text(body?.message) ?? text(legacyDetail)
+    ?? STATUS_MESSAGES[status] ?? `HTTP ${status}`
+  const details = body?.details ?? inner?.details ?? null
+  const requestId = text(body?.request_id) ?? text(inner?.request_id) ?? options.requestId ?? null
+
+  return new MintApiError(
+    message,
+    code,
+    status,
+    requestId,
+    details,
+    legacyDetail,
+    payload,
+    options.cause,
+  )
+}

package/src/components/ExperimentPopover.vue

@@ -63,6 +63,14 @@ const { isOpen, rootRef: popoverRef, triggerRef, close, toggle } = useDropdownSt
 const showSuccess = ref(false)
 const showConfirm = ref(false)
 
+function handleTriggerClick() {
+  if (!hasExperiment.value && !isUnresolved.value) {
+    handleSelect()
+    return
+  }
+  toggle()
+}
+
 function handleSelect() {
   emit('select')
   close()
@@ -115,7 +123,7 @@ onUnmounted(() => {
         { 'mint-experiment-popover__split--with-save': showSave && experimentName },
       ]"
     >
-      <!-- Left: experiment trigger (opens popover). Prefer the human-readable
+      <!-- Left: experiment trigger (selects when empty, otherwise opens popover). Prefer the human-readable
            name; the formal code, when present, stays in the detail panel. -->
       <button
         ref="triggerRef"
@@ -131,7 +139,7 @@ onUnmounted(() => {
         :aria-label="isUnresolved ? triggerLabel : undefined"
         :aria-busy="isResolving || undefined"
         :aria-expanded="isOpen"
-        @click.stop="toggle"
+        @click.stop="handleTriggerClick"
       >
         <!-- Flask icon -->
         <svg class="mint-experiment-popover__trigger-icon" aria-hidden="true" fill="none" stroke="currentColor" viewBox="0 0 24 24">