@morscherlab/mint-sdk 1.1.25 → 1.2.0-beta.10

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

@@ -14,7 +14,6 @@ import {
   uploadPluginEndpoint,
   useCurrentExperiment,
   usePluginEventStream,
-  usePluginClient,
   usePluginSettings,
   type PluginContract,
 } from '../../composables/usePluginClient'
@@ -80,7 +79,13 @@ function pendingEventStreamResponse(): {
   })
   return {
     response: new Response(body, { status: 200 }),
-    close: () => streamController.close(),
+    close: () => {
+      try {
+        streamController.close()
+      } catch {
+        // stop() may already have cancelled the reader.
+      }
+    },
   }
 }
 
@@ -843,6 +848,146 @@ describe('usePluginClient', () => {
     })
   })
 
+  describe('secret settings references', () => {
+    const secretRef = { $secret: 'sec_0f2a4c6e8a0c2e4a6c8e0a2c4e6a8c0e', set: true }
+
+    function integratedPluginSettingsHost(): void {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        platformApiUrl: '/api',
+        plugin: {
+          id: 'drp',
+          name: 'drp',
+          version: '1.0.0',
+          route_prefix: '/drp',
+          api_prefix: '/api/drp',
+          settings_api: 'plugin',
+        },
+      }
+      nextGetData = {
+        settings: { apiKey: secretRef, method: 'first' },
+        secret_format: 'ref',
+        mode: 'integrated',
+        revision: 'revision-1',
+      }
+      nextPutData = {
+        settings: { apiKey: secretRef, method: 'second' },
+        secret_format: 'ref',
+        mode: 'integrated',
+        revision: 'revision-2',
+      }
+    }
+
+    it('should round-trip an untouched secret reference unchanged', async () => {
+      integratedPluginSettingsHost()
+
+      const settings = usePluginSettings<{ apiKey?: unknown; method?: string }>({
+        pluginName: 'drp',
+      })
+      await settings.load()
+      const saved = await settings.save({ ...settings.values.value, method: 'second' })
+
+      expect({ saved, body: requestBodies[0] }).toEqual({
+        saved: true,
+        body: { apiKey: secretRef, method: 'second', secret_format: 'ref' },
+      })
+    })
+
+    it('should submit a typed string when the user enters a new secret', async () => {
+      integratedPluginSettingsHost()
+
+      const settings = usePluginSettings<{ apiKey?: unknown; method?: string }>({
+        pluginName: 'drp',
+      })
+      await settings.load()
+      await settings.save({ apiKey: 'typed-secret', method: 'first' })
+
+      expect(requestBodies[0]).toEqual({
+        apiKey: 'typed-secret',
+        method: 'first',
+        secret_format: 'ref',
+      })
+    })
+
+    it('should submit null when the user clears a secret', async () => {
+      integratedPluginSettingsHost()
+
+      const settings = usePluginSettings<{ apiKey?: unknown; method?: string }>({
+        pluginName: 'drp',
+      })
+      await settings.load()
+      await settings.save({ apiKey: null, method: 'first' })
+
+      expect(requestBodies[0]).toEqual({
+        apiKey: null,
+        method: 'first',
+        secret_format: 'ref',
+      })
+    })
+
+    it('should declare the reference format on platform config patches', async () => {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        platformApiUrl: '/api',
+        plugin: {
+          id: 'drp',
+          name: 'drp',
+          version: '1.0.0',
+          route_prefix: '/drp',
+          api_prefix: '/api/drp',
+        },
+      }
+      nextGetData = {
+        plugin_name: 'drp',
+        config: { apiKey: secretRef, method: 'first' },
+        secret_format: 'ref',
+        revision: 'revision-1',
+      }
+      nextPatchData = {
+        plugin_name: 'drp',
+        config: { apiKey: secretRef, method: 'second' },
+        secret_format: 'ref',
+        revision: 'revision-2',
+      }
+
+      const settings = usePluginSettings<{ apiKey?: unknown; method?: string }>({
+        pluginName: 'drp',
+      })
+      await settings.load()
+      await settings.save({ apiKey: secretRef, method: 'second' })
+
+      expect(requestBodies[0]).toEqual({
+        config: { method: 'second', secret_format: 'ref' },
+      })
+    })
+
+    it('should omit the format marker for a host that does not publish one', async () => {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        platformApiUrl: '/api',
+        plugin: {
+          id: 'drp',
+          name: 'drp',
+          version: '1.0.0',
+          route_prefix: '/drp',
+          api_prefix: '/api/drp',
+          settings_api: 'plugin',
+        },
+      }
+      nextGetData = { settings: { method: 'first' }, mode: 'integrated', revision: 'revision-1' }
+      nextPutData = { settings: { method: 'second' }, mode: 'integrated', revision: 'revision-2' }
+
+      const settings = usePluginSettings<{ method?: string }>({ pluginName: 'drp' })
+      await settings.load()
+      await settings.save({ method: 'second' })
+
+      expect(requestBodies[0]).toEqual({ method: 'second' })
+    })
+  })
+
   it('should preserve the contract v2 form schema in settingsConfig', () => {
     const settings = usePluginSettings({
       apiBaseUrl: '/api/drp',
@@ -1396,11 +1541,7 @@ describe('usePluginClient', () => {
 
     try {
       stream.start()
-      await Promise.resolve()
-      await Promise.resolve()
-      await Promise.resolve()
-
-      expect(onOpen).toHaveBeenCalledOnce()
+      await vi.waitFor(() => expect(onOpen).toHaveBeenCalledOnce())
     } finally {
       stopWatching()
       stream.stop()
@@ -1684,12 +1825,6 @@ describe('usePluginClient', () => {
     expect(requestConfigs).toHaveLength(0)
   })
 
-  it('returns the provided client identity from usePluginClient', () => {
-    const client = createPluginClient(contract, { endpoints: {} })
-
-    expect(usePluginClient(client)).toBe(client)
-  })
-
   it('loads the current experiment from URL conventions', async () => {
     window.history.replaceState({}, '', '/analysis?experimentId=42')
     const current = useCurrentExperiment<{ called: string }>({ immediate: false })

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

@@ -89,4 +89,144 @@ describe('useRequestSyncState', () => {
     expect(state.lastSavedAt.value).toBeNull()
     expect(state.lastRunAt.value).toBeNull()
   })
+
+  describe('stale-response guard', () => {
+    function deferred<T>() {
+      let resolve!: (value: T) => void
+      let reject!: (reason: unknown) => void
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res
+        reject = rej
+      })
+      return { promise, resolve, reject }
+    }
+
+    it('lets only the newest run own loading', async () => {
+      const state = useRequestSyncState()
+      const first = deferred<string>()
+      const second = deferred<string>()
+
+      const firstRun = state.run(() => first.promise, { success: 'load' })
+      const secondRun = state.run(() => second.promise, { success: 'load' })
+
+      first.resolve('stale')
+      await expect(firstRun).resolves.toBe('stale')
+      expect(state.loading.value).toBe(true)
+
+      second.resolve('fresh')
+      await expect(secondRun).resolves.toBe('fresh')
+      expect(state.loading.value).toBe(false)
+    })
+
+    it('does not let a stale success move the sync timestamps', async () => {
+      const state = useRequestSyncState()
+      const first = deferred<string>()
+      const second = deferred<string>()
+
+      const firstRun = state.run(() => first.promise, { success: 'save' })
+      const secondRun = state.run(() => second.promise, { success: 'load' })
+
+      first.resolve('stale')
+      await firstRun
+      expect(state.lastSavedAt.value).toBeNull()
+
+      second.resolve('fresh')
+      await secondRun
+      expect(state.lastLoadedAt.value).toBeInstanceOf(Date)
+      expect(state.lastSavedAt.value).toBeNull()
+    })
+
+    it('does not let a stale failure write the error, but still rejects its caller', async () => {
+      const state = useRequestSyncState()
+      const first = deferred<string>()
+      const second = deferred<string>()
+
+      const firstRun = state.run(() => first.promise, { errorMessage: 'first failed' })
+      const secondRun = state.run(() => second.promise, { success: 'load' })
+
+      first.reject(new Error('stale failure'))
+      await expect(firstRun).rejects.toThrow('stale failure')
+      expect(state.error.value).toBeNull()
+
+      second.resolve('fresh')
+      await secondRun
+      expect(state.error.value).toBeNull()
+      expect(state.loading.value).toBe(false)
+    })
+
+    it('aborts the superseded run signal by default', async () => {
+      const state = useRequestSyncState()
+      const first = deferred<string>()
+      const second = deferred<string>()
+      let firstSignal: AbortSignal | undefined
+
+      const firstRun = state.run((signal) => {
+        firstSignal = signal
+        return first.promise
+      })
+      expect(firstSignal?.aborted).toBe(false)
+
+      const secondRun = state.run(() => second.promise)
+      expect(firstSignal?.aborted).toBe(true)
+
+      first.resolve('stale')
+      second.resolve('fresh')
+      await Promise.all([firstRun, secondRun])
+    })
+
+    it('leaves the previous signal alone when abortPrevious is false', async () => {
+      const state = useRequestSyncState()
+      const first = deferred<string>()
+      const second = deferred<string>()
+      let firstSignal: AbortSignal | undefined
+
+      const firstRun = state.run((signal) => {
+        firstSignal = signal
+        return first.promise
+      })
+      const secondRun = state.run(() => second.promise, { abortPrevious: false })
+
+      expect(firstSignal?.aborted).toBe(false)
+      first.resolve('stale')
+      second.resolve('fresh')
+      await Promise.all([firstRun, secondRun])
+    })
+
+    it('forwards a caller signal onto the operation signal', async () => {
+      const state = useRequestSyncState()
+      const caller = new AbortController()
+      const pending = deferred<string>()
+      let operationSignal: AbortSignal | undefined
+
+      const run = state.run((signal) => {
+        operationSignal = signal
+        return pending.promise
+      }, { signal: caller.signal })
+
+      caller.abort()
+      expect(operationSignal?.aborted).toBe(true)
+
+      pending.resolve('done')
+      await run
+    })
+
+    it('cancel() aborts the in-flight run and drops loading', async () => {
+      const state = useRequestSyncState()
+      const pending = deferred<string>()
+      let operationSignal: AbortSignal | undefined
+
+      const run = state.run((signal) => {
+        operationSignal = signal
+        return pending.promise
+      }, { success: 'load' })
+
+      state.cancel()
+      expect(operationSignal?.aborted).toBe(true)
+      expect(state.loading.value).toBe(false)
+
+      pending.resolve('too late')
+      await expect(run).resolves.toBe('too late')
+      expect(state.lastLoadedAt.value).toBeNull()
+    })
+  })
 })

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -22,7 +22,7 @@ interface FrontendManifest {
     }>
     composables: Array<{
       name: string
-      members?: Array<{ name: string }>
+      members?: Array<{ name: string; type?: string }>
       examples?: Array<{ title: string; language: string; code: string }>
     }>
     templateExports: Array<{ name: string }>
@@ -271,6 +271,21 @@ describe('frontend docs catalog coverage', () => {
     })
   })
 
+  it('documents the source and MINT 1.1 JobsStatusTray props', () => {
+    const manifest = extractFrontendManifest()
+    const jobsStatusTray = manifest.categories.components.find(item => item.name === 'JobsStatusTray')
+
+    expect(jobsStatusTray?.props?.map(prop => prop.name).sort()).toEqual([
+      'adapter',
+      'eventStream',
+      'jobs',
+      'loadOnMount',
+      'source',
+      'teleportTo',
+      'title',
+    ])
+  })
+
   it('re-exports every public component from the root SDK entrypoint', () => {
     const publicComponents = parseComponentExports()
     const rootComponents = parseRootComponentExports()
@@ -295,6 +310,7 @@ describe('frontend docs catalog coverage', () => {
     const rootIndex = readFileSync(join(SDK_ROOT, 'src', 'index.ts'), 'utf8')
     const componentsIndex = readFileSync(join(SDK_ROOT, 'src', 'components', 'index.ts'), 'utf8')
     const composablesIndex = readFileSync(join(SDK_ROOT, 'src', 'composables', 'index.ts'), 'utf8')
+    const composableExports = composablesIndex.replace(/from\s+['"][^'"]+['"]/g, '')
 
     const retiredNames = [
       'ToastNotification',
@@ -311,10 +327,26 @@ describe('frontend docs catalog coverage', () => {
     for (const name of retiredNames) {
       expect(rootIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
       expect(componentsIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
-      expect(composablesIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
+      expect(composableExports).not.toMatch(new RegExp(`\\b${name}\\b`))
     }
   })
 
+  it('keeps the MINT 1.1 composable compatibility exports', () => {
+    const composablesIndex = readFileSync(join(SDK_ROOT, 'src', 'composables', 'index.ts'), 'utf8')
+    const expected = [
+      'useJobsStatusTray',
+      'UseJobsStatusTrayOptions',
+      'UseJobsStatusTrayReturn',
+      'JobsStatusTrayAdapter',
+      'JobStreamMessage',
+      'usePluginConfig',
+      'UsePluginConfigReturn',
+      'usePluginClient',
+    ]
+
+    expect(expected.filter(name => !new RegExp(`\\b${name}\\b`).test(composablesIndex))).toEqual([])
+  })
+
   it('documents every public composable/helper export used by docs and doctor', () => {
     const manifest = extractFrontendManifest()
     const publicComposables = parseDocumentedComposableExports()
@@ -401,4 +433,25 @@ describe('frontend docs catalog coverage', () => {
 
     expect(useFormBuilder?.members?.map(member => member.name)).toContain('updateSchema')
   })
+
+  it('extracts inherited return interface members', () => {
+    const manifest = extractFrontendManifest()
+    const workspace = manifest.categories.composables.find(item => item.name === 'useBioTemplateWorkspace')
+
+    expect(workspace?.members?.map(member => member.name)).toContain('componentUsage')
+  })
+
+  it('ignores generic constraints when extracting inherited return members', () => {
+    const manifest = extractFrontendManifest()
+    const history = manifest.categories.composables.find(item => item.name === 'useCommandHistory')
+
+    expect(history?.members?.map(member => member.name)).not.toContain('description')
+  })
+
+  it('extracts exact array return member types while resolving inheritance', () => {
+    const manifest = extractFrontendManifest()
+    const bindings = manifest.categories.composables.find(item => item.name === 'controlValuesToComponentBindings')
+
+    expect(bindings?.members?.find(member => member.name === 'props')?.type).toBe('Record<string, unknown>')
+  })
 })

package/src/__tests__/stores/settings.test.ts

@@ -1,6 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
-import { useSettingsStore } from '../../stores/settings'
+import { nextTick } from 'vue'
+import {
+  paletteCssVariables,
+  tableDensityToSize,
+  tryUseSettingsStore,
+  useSettingsStore,
+} from '../../stores/settings'
 
 function mockMatchMedia(matches = false) {
   Object.defineProperty(window, 'matchMedia', {
@@ -46,6 +52,8 @@ describe('useSettingsStore', () => {
     setActivePinia(createPinia())
     installLocalStorage()
     document.documentElement.classList.remove('dark')
+    document.documentElement.removeAttribute('style')
+    delete document.documentElement.dataset.density
     mockMatchMedia(false)
   })
 
@@ -75,4 +83,66 @@ describe('useSettingsStore', () => {
       tableDensity: 'compact',
     }))
   })
+
+  describe('palette and density DOM sync', () => {
+    it('writes no palette overrides for the default palette', () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      expect(paletteCssVariables('default')).toEqual({})
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('')
+    })
+
+    it('applies the stored palette hues to html on initialize', () => {
+      localStorage.setItem('mint-settings', JSON.stringify({ colorPalette: 'viridis' }))
+
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      const style = document.documentElement.style
+      expect(style.getPropertyValue('--color-primary')).toBe('hsl(280 84% 67%)')
+      expect(style.getPropertyValue('--color-primary-hover')).toBe('hsl(280 75% 59%)')
+      expect(style.getPropertyValue('--color-cta')).toBe('hsl(80 95% 53%)')
+    })
+
+    it('re-applies the overrides when the palette changes and clears them on default', async () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      settings.colorPalette = 'pastel'
+      await nextTick()
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('hsl(200 84% 67%)')
+
+      settings.colorPalette = 'default'
+      await nextTick()
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('')
+      expect(document.documentElement.style.getPropertyValue('--color-primary-soft')).toBe('')
+    })
+
+    it('mirrors the table density onto html[data-density]', async () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+      expect(document.documentElement.dataset.density).toBe('normal')
+
+      settings.tableDensity = 'compact'
+      await nextTick()
+      expect(document.documentElement.dataset.density).toBe('compact')
+    })
+
+    it('maps each density onto a table size', () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      expect(tableDensityToSize('compact')).toBe('sm')
+      expect(tableDensityToSize('normal')).toBe('md')
+      expect(tableDensityToSize('comfortable')).toBe('lg')
+
+      settings.tableDensity = 'comfortable'
+      expect(settings.getTableSize()).toBe('lg')
+    })
+  })
+
+  it('exposes the store through tryUseSettingsStore when Pinia is active', () => {
+    expect(tryUseSettingsStore()).not.toBeNull()
+  })
 })

package/src/__tests__/styles/cssTokens.test.ts

@@ -0,0 +1,131 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const srcRoot = resolve(here, '../..')
+const stylesDir = join(srcRoot, 'styles')
+const variablesCss = readFileSync(join(stylesDir, 'variables.css'), 'utf-8')
+
+/**
+ * Custom properties that are legitimately *not* declared in variables.css:
+ * they are set at runtime (inline `:style` bindings, JS-built names) or are
+ * component-local knobs declared in the same stylesheet that consumes them.
+ * Anything else must be a canonical token from variables.css.
+ */
+const RUNTIME_PROPERTY_ALLOWLIST = new Set<string>([
+  // Names assembled in JS (`--grp-${i}`) — the literal prefix is what the
+  // scanner sees in a template string.
+  '--grp-',
+])
+
+const SOURCE_EXTENSIONS = ['.vue', '.css', '.ts']
+const IGNORED_DIRS = new Set(['__tests__', 'generated-ui', 'node_modules'])
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      if (!IGNORED_DIRS.has(entry)) walk(full, out)
+    } else if (SOURCE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+const sourceFiles = walk(srcRoot)
+
+function declaredIn(text: string): Set<string> {
+  const names = new Set<string>()
+  // `--foo: value` declarations, in CSS blocks and in JS style objects.
+  for (const m of text.matchAll(/(--[A-Za-z0-9_-]+)\s*:/g)) names.add(m[1])
+  // setProperty('--foo', …) / `'--foo'` keys in style bindings.
+  for (const m of text.matchAll(/['"`](--[A-Za-z0-9_-]+)['"`]/g)) names.add(m[1])
+  return names
+}
+
+const canonicalTokens = declaredIn(variablesCss)
+
+// Component-local custom properties: declared in a stylesheet or set from an
+// inline `:style` binding in the SFC that owns it. They are legitimate, they
+// just are not part of the global token set.
+const componentLocalProperties = new Set<string>()
+for (const file of sourceFiles) {
+  for (const name of declaredIn(readFileSync(file, 'utf-8'))) {
+    componentLocalProperties.add(name)
+  }
+}
+
+interface Usage {
+  file: string
+  token: string
+}
+
+const usages: Usage[] = []
+for (const file of sourceFiles) {
+  const text = readFileSync(file, 'utf-8')
+  for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) {
+    usages.push({ file, token: m[1] })
+  }
+}
+
+describe('CSS custom properties', () => {
+  it('scans a meaningful number of var() references', () => {
+    expect(usages.length).toBeGreaterThan(500)
+    expect(canonicalTokens.size).toBeGreaterThan(70)
+  })
+
+  it('only references custom properties that are actually defined', () => {
+    const undefinedUsages = usages.filter(({ token }) => {
+      if (canonicalTokens.has(token)) return false
+      if (RUNTIME_PROPERTY_ALLOWLIST.has(token)) return false
+      return !componentLocalProperties.has(token)
+    })
+
+    const report = [
+      ...new Set(
+        undefinedUsages.map(
+          ({ file, token }) => `${token} (${relative(srcRoot, file)})`,
+        ),
+      ),
+    ].sort()
+
+    expect(report).toEqual([])
+  })
+
+  it('does not use the platform-only --color-bg-*/--color-text-*/--color-border aliases', () => {
+    const platformOnly = /^--color-(bg|text)-|^--color-border$/
+    const offenders = [
+      ...new Set(
+        usages
+          .filter(({ token }) => platformOnly.test(token))
+          .map(({ file, token }) => `${token} (${relative(srcRoot, file)})`),
+      ),
+    ].sort()
+
+    expect(offenders).toEqual([])
+  })
+
+  it('aggregates every component stylesheet in styles/index.css', () => {
+    const index = readFileSync(join(stylesDir, 'index.css'), 'utf-8')
+    const imported = new Set(
+      [...index.matchAll(/@import\s+'\.\/components\/([^']+)'/g)].map((m) => m[1]),
+    )
+    const onDisk = readdirSync(join(stylesDir, 'components')).filter((f) =>
+      f.endsWith('.css'),
+    )
+    expect([...onDisk].filter((f) => !imported.has(f)).sort()).toEqual([])
+  })
+
+  it('does not re-import aggregated stylesheets from SFC <style> blocks', () => {
+    const offenders = sourceFiles
+      .filter((f) => f.endsWith('.vue'))
+      .filter((f) => /@import\s+['"][^'"]*styles\/components\//.test(readFileSync(f, 'utf-8')))
+      .map((f) => relative(srcRoot, f))
+      .sort()
+
+    expect(offenders).toEqual([])
+  })
+})