@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/bridge/react/useDocumentLifecycle.tsx

@@ -0,0 +1,359 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  autosavePlatformDocument,
+  createPlatformDraft,
+  duplicatePlatformDocument,
+  promotePlatformDocument,
+  renamePlatformDocument,
+  touchPlatformRecentDocument,
+  type PlatformDocumentFilePayload,
+} from '../documents.mjs'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+
+export type DocumentLifecycleStatus = 'none' | 'draft' | 'filed'
+
+export interface DocumentLifecycleDoc {
+  path: string | null
+  title: string
+  status: DocumentLifecycleStatus
+  savedAt: string | null
+  saving: boolean
+  error: string | null
+}
+
+export interface UseDocumentLifecycleOptions {
+  appSlug: string
+  /** Document suffix, e.g. `.research`. */
+  suffix: string
+  kind: 'package' | 'file'
+  /** Called at flush time; returns the document's current file contents. */
+  serialize: () => PlatformDocumentFilePayload[]
+  /** Prefill for the naming dialog (e.g. an AI-generated title). */
+  suggestedTitle?: string
+  debounceMs?: number
+}
+
+export interface DocumentLifecycle {
+  doc: DocumentLifecycleDoc
+  /** Create the durable draft if none exists yet; returns the path. */
+  ensureDraft: () => Promise<string | null>
+  /** Note a content change: lazily creates the draft, debounces an autosave. */
+  markDirty: () => void
+  /** Immediate save of the current serialize() output. */
+  flush: () => Promise<void>
+  /** Name + file the document (move out of drafts). */
+  promote: (title: string, targetDir?: string) => Promise<void>
+  rename: (title: string) => Promise<void>
+  duplicate: () => Promise<string | null>
+  revealInFinder: () => Promise<void>
+  openInFiles: () => Promise<void>
+  /** Bind an existing on-disk document (opened from PureFiles/recents). */
+  adopt: (path: string, opts?: { title?: string }) => void
+  /** Detach — back to `none` (⌘N / new document). */
+  reset: () => void
+}
+
+function titleFromPath(path: string, suffix: string): string {
+  const name = path.split('/').pop() ?? path
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name
+}
+
+function statusForPath(path: string): DocumentLifecycleStatus {
+  return path.includes('/PureDrafts/') ? 'draft' : 'filed'
+}
+
+export function useDocumentLifecycle(
+  options: UseDocumentLifecycleOptions,
+): DocumentLifecycle {
+  const { appSlug, suffix, kind, suggestedTitle } = options
+  const debounceMs = options.debounceMs ?? 1500
+  const serializeRef = useRef(options.serialize)
+  serializeRef.current = options.serialize
+
+  const [doc, setDoc] = useState<DocumentLifecycleDoc>({
+    path: null,
+    title: suggestedTitle ?? '',
+    status: 'none',
+    savedAt: null,
+    saving: false,
+    error: null,
+  })
+  const pathRef = useRef<string | null>(null)
+  const timerRef = useRef<number | null>(null)
+  // Serialize all writes for one document through a promise chain — never two
+  // concurrent autosaves, and flush() awaits everything queued before it.
+  const writeChainRef = useRef<Promise<void>>(Promise.resolve())
+  const creatingRef = useRef<Promise<string | null> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) window.clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  const queueWrite = useCallback(
+    (work: () => Promise<void>): Promise<void> => {
+      const next = writeChainRef.current.then(work, work)
+      writeChainRef.current = next.catch(() => undefined)
+      return next
+    },
+    [],
+  )
+
+  const saveNow = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    setDoc(current => ({ ...current, saving: true }))
+    try {
+      const { savedAt } = await autosavePlatformDocument({
+        path,
+        files: serializeRef.current(),
+      })
+      setDoc(current => ({ ...current, saving: false, savedAt, error: null }))
+    } catch (error) {
+      setDoc(current => ({
+        ...current,
+        saving: false,
+        error: error instanceof Error ? error.message : 'Could not save.',
+      }))
+    }
+  }, [])
+
+  const ensureDraft = useCallback(async (): Promise<string | null> => {
+    if (pathRef.current) return pathRef.current
+    if (creatingRef.current) return creatingRef.current
+    creatingRef.current = (async () => {
+      try {
+        const { path } = await createPlatformDraft({
+          appSlug,
+          suffix,
+          kind,
+          files: serializeRef.current(),
+        })
+        pathRef.current = path
+        setDoc(current => ({
+          ...current,
+          path,
+          title: current.title || titleFromPath(path, suffix),
+          status: 'draft',
+          savedAt: new Date().toISOString(),
+          error: null,
+        }))
+        void touchPlatformRecentDocument({
+          appSlug,
+          path,
+          title: titleFromPath(path, suffix),
+        }).catch(() => undefined)
+        return path
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error:
+            error instanceof Error ? error.message : 'Could not create draft.',
+        }))
+        return null
+      } finally {
+        creatingRef.current = null
+      }
+    })()
+    return creatingRef.current
+  }, [appSlug, kind, suffix])
+
+  const markDirty = useCallback((): void => {
+    void (async () => {
+      if (!pathRef.current) {
+        const created = await ensureDraft()
+        if (!created) return
+      }
+      if (timerRef.current !== null) window.clearTimeout(timerRef.current)
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        void queueWrite(saveNow)
+      }, debounceMs)
+    })()
+  }, [debounceMs, ensureDraft, queueWrite, saveNow])
+
+  const flush = useCallback(async (): Promise<void> => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+    if (!pathRef.current) return
+    await queueWrite(saveNow)
+  }, [queueWrite, saveNow])
+
+  // Last-chance flush when the app tab hides or unloads.
+  useEffect(() => {
+    const onHidden = (): void => {
+      if (document.visibilityState === 'hidden') void flush()
+    }
+    window.addEventListener('beforeunload', onHidden)
+    document.addEventListener('visibilitychange', onHidden)
+    return () => {
+      window.removeEventListener('beforeunload', onHidden)
+      document.removeEventListener('visibilitychange', onHidden)
+    }
+  }, [flush])
+
+  const promote = useCallback(
+    async (title: string, targetDir?: string): Promise<void> => {
+      const path = pathRef.current ?? (await ensureDraft())
+      if (!path) return
+      await flush()
+      try {
+        const result = await promotePlatformDocument({
+          path,
+          title,
+          targetDir,
+          suffix,
+          appSlug,
+        })
+        pathRef.current = result.path
+        setDoc(current => ({
+          ...current,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+          status: statusForPath(result.path),
+          error: null,
+        }))
+        void touchPlatformRecentDocument({
+          appSlug,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+        }).catch(() => undefined)
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error: error instanceof Error ? error.message : 'Could not file.',
+        }))
+      }
+    },
+    [appSlug, ensureDraft, flush, suffix],
+  )
+
+  const rename = useCallback(
+    async (title: string): Promise<void> => {
+      const path = pathRef.current
+      if (!path) {
+        setDoc(current => ({ ...current, title }))
+        return
+      }
+      await flush()
+      try {
+        const result = await renamePlatformDocument({
+          path,
+          title,
+          suffix,
+          appSlug,
+        })
+        pathRef.current = result.path
+        setDoc(current => ({
+          ...current,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+          status: statusForPath(result.path),
+          error: null,
+        }))
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error: error instanceof Error ? error.message : 'Could not rename.',
+        }))
+      }
+    },
+    [appSlug, flush, suffix],
+  )
+
+  const duplicate = useCallback(async (): Promise<string | null> => {
+    const path = pathRef.current
+    if (!path) return null
+    await flush()
+    try {
+      const result = await duplicatePlatformDocument({ path, suffix })
+      return result.path
+    } catch {
+      return null
+    }
+  }, [flush, suffix])
+
+  const revealInFinder = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    await bridge.call(PLATFORM_BRIDGE_METHODS.OS_REVEAL, [path])
+  }, [])
+
+  const openInFiles = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    await bridge.call(PLATFORM_BRIDGE_METHODS.CATALOG_OPEN, [
+      { path, appSlug: 'purefiles' },
+    ])
+  }, [])
+
+  const adopt = useCallback(
+    (path: string, opts: { title?: string } = {}): void => {
+      pathRef.current = path
+      setDoc({
+        path,
+        title: opts.title ?? titleFromPath(path, suffix),
+        status: statusForPath(path),
+        savedAt: null,
+        saving: false,
+        error: null,
+      })
+      void touchPlatformRecentDocument({
+        appSlug,
+        path,
+        title: opts.title ?? titleFromPath(path, suffix),
+      }).catch(() => undefined)
+    },
+    [appSlug, suffix],
+  )
+
+  const reset = useCallback((): void => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+    pathRef.current = null
+    setDoc({
+      path: null,
+      title: '',
+      status: 'none',
+      savedAt: null,
+      saving: false,
+      error: null,
+    })
+  }, [])
+
+  return useMemo(
+    () => ({
+      doc,
+      ensureDraft,
+      markDirty,
+      flush,
+      promote,
+      rename,
+      duplicate,
+      revealInFinder,
+      openInFiles,
+      adopt,
+      reset,
+    }),
+    [
+      doc,
+      ensureDraft,
+      markDirty,
+      flush,
+      promote,
+      rename,
+      duplicate,
+      revealInFinder,
+      openInFiles,
+      adopt,
+      reset,
+    ],
+  )
+}

package/src/bridge/react/usePlatformAgentSessionDrive.test.tsx

@@ -104,16 +104,35 @@ describe('usePlatformAgentSessionDrive', () => {
     ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
   })
 
-  beforeEach(() => {
-    latestDrive = null
-    host = document.createElement('div')
-    document.body.appendChild(host)
-    root = createRoot(host)
-    agentsMock.readAgentSession.mockResolvedValue(sessionRecord)
-    agentsMock.advanceAgentSessionPending.mockResolvedValue(null)
-    agentsMock.readAgentLlmMenuOptions.mockResolvedValue([])
-    agentsMock.onAgentRunEvent.mockReturnValue(vi.fn())
-  })
+  beforeEach(() => {
+    latestDrive = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    agentsMock.readAgentSession.mockResolvedValue(sessionRecord)
+    agentsMock.advanceAgentSessionPending.mockResolvedValue({
+      session: sessionRecord,
+      snapshot: {
+        runId: sessionRecord.runId,
+        state: sessionRecord.snapshot.state,
+        turn: sessionRecord.snapshot.turn,
+        messages: sessionRecord.snapshot.messages,
+      },
+      effectiveToolPolicy: {
+        allowedTargetApps: ['book'],
+        defaultRequiresApproval: false,
+        approvalOverrides: {
+          'book.write': true,
+          'book.review': true,
+        },
+      },
+      manualPendingToolCalls: [
+        { id: 'call-manual', name: 'book.review', arguments: {} },
+      ],
+    })
+    agentsMock.readAgentLlmMenuOptions.mockResolvedValue([])
+    agentsMock.onAgentRunEvent.mockReturnValue(vi.fn())
+  })
 
   afterEach(() => {
     act(() => root.unmount())

package/src/bridge/react/usePlatformAgentSessionDrive.tsx

@@ -31,10 +31,7 @@ import {
   isAgentAutoModelId,
   DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID,
 } from '../agentModelTiers.js'
-import {
-  getPlatformPreferences,
-  patchPlatformPreferences,
-} from '../preferences.mjs'
+import { patchAgentSessionScopeDefaults } from '../agentScopeDefaults.js'
 import {
   advanceAgentSessionPending,
   approveAgentSessionTools,
@@ -95,10 +92,6 @@ export interface UsePlatformAgentSessionDrive {
   /** Send the composer value, or an explicit message (programmatic). Returns the final snapshot. */
   sendMessage: (message?: string) => Promise<PlatformAgentRunSnapshot | null>
   approveTools: (toolCallIds?: readonly string[]) => Promise<void>
-  approveToolAlwaysForSession: (
-    qualifiedName: string,
-    toolCallId: string,
-  ) => Promise<void>
   rejectTools: (toolCallIds?: readonly string[]) => Promise<void>
   selectSession: (sessionId: string) => Promise<void>
   createNewSession: () => Promise<void>
@@ -121,9 +114,9 @@ interface DriveResult {
 }
 
 /** Display snapshot from a persisted session record (before any live run this turn). */
-function recordSnapshot(
-  record: PlatformAgentSessionRecord | null,
-): PlatformAgentRunSnapshot | null {
+function recordSnapshot(
+  record: PlatformAgentSessionRecord | null,
+): PlatformAgentRunSnapshot | null {
   if (!record) return null
   return {
     runId: record.runId ?? '',
@@ -132,28 +125,10 @@ function recordSnapshot(
     messages: record.snapshot.messages,
     error: record.snapshot.error,
     interruptedReason: record.snapshot.interruptedReason,
-  }
-}
-
-function mergeScopeDefaultPatch(
-  base: PlatformAgentSessionConfigPatch | undefined,
-  patch: PlatformAgentSessionConfigPatch,
-): PlatformAgentSessionConfigPatch {
-  const toolPolicy =
-    patch.toolPolicy || base?.toolPolicy
-      ? {
-          ...base?.toolPolicy,
-          ...patch.toolPolicy,
-          approvalOverrides: {
-            ...base?.toolPolicy?.approvalOverrides,
-            ...patch.toolPolicy?.approvalOverrides,
-          },
-        }
-      : undefined
-  return { ...base, ...patch, ...(toolPolicy ? { toolPolicy } : {}) }
-}
-
-export function usePlatformAgentSessionDrive({
+  }
+}
+
+export function usePlatformAgentSessionDrive({
   appSlug,
   scope: initialScope = 'app',
   enabled = true,
@@ -404,7 +379,7 @@ export function usePlatformAgentSessionDrive({
       : 'This model is not available. Check API keys or local runtime in Settings.'
   }, [modelOptions, selectedModelId])
 
-  const toolPolicy = policy ?? sessionRecord?.config?.toolPolicy ?? undefined
+  const toolPolicy = policy
   const acceptedPendingToolCallIds = useMemo(
     () =>
       sessionRecord?.runId && sessionRecord.runId === threadSnapshot?.runId
@@ -607,28 +582,7 @@ export function usePlatformAgentSessionDrive({
   const persistScopeDefault = useCallback(
     async (patch: PlatformAgentSessionConfigPatch) => {
       try {
-        const prefs = (await getPlatformPreferences()) as {
-          agentSessionDefaults?: {
-            global?: PlatformAgentSessionConfigPatch
-            apps?: Record<string, PlatformAgentSessionConfigPatch>
-          }
-        }
-        const stored = prefs.agentSessionDefaults ?? {}
-        if (scope === 'global') {
-          await patchPlatformPreferences({
-            agentSessionDefaults: {
-              ...stored,
-              global: mergeScopeDefaultPatch(stored.global, patch),
-            },
-          })
-          return
-        }
-        if (!scopeAppSlug) return
-        const apps = { ...(stored.apps ?? {}) }
-        apps[scopeAppSlug] = mergeScopeDefaultPatch(apps[scopeAppSlug], patch)
-        await patchPlatformPreferences({
-          agentSessionDefaults: { ...stored, apps },
-        })
+        await patchAgentSessionScopeDefaults(scope, scopeAppSlug, patch)
       } catch {
         /* scope defaults are best-effort */
       }
@@ -696,30 +650,6 @@ export function usePlatformAgentSessionDrive({
     [persistScopeDefault, sessionQuery, sessionRecord],
   )
 
-  const approveToolAlwaysForSession = useCallback(
-    async (qualifiedName: string, toolCallId: string) => {
-      if (!sessionRecord) return
-      await drive(async () => {
-        const overrides = {
-          ...sessionRecord.config.toolPolicy?.approvalOverrides,
-          [qualifiedName]: false,
-        }
-        const updated = await updateAgentSession({
-          query: sessionQuery(sessionRecord.sessionId),
-          patch: { config: { toolPolicy: { approvalOverrides: overrides } } },
-        })
-        await persistScopeDefault({
-          toolPolicy: { approvalOverrides: overrides },
-        })
-        return approveAgentSessionTools({
-          session: sessionQuery(updated.sessionId),
-          toolCallIds: [toolCallId],
-        })
-      })
-    },
-    [drive, persistScopeDefault, sessionQuery, sessionRecord],
-  )
-
   return {
     scope,
     setScope,
@@ -744,7 +674,6 @@ export function usePlatformAgentSessionDrive({
     sendMessage,
     interruptRun,
     approveTools,
-    approveToolAlwaysForSession,
     rejectTools,
     selectSession,
     createNewSession,

package/src/bridge/react/usePlatformAppSettings.test.tsx

@@ -0,0 +1,105 @@
+// @vitest-environment happy-dom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import { usePlatformAppSettings } from './usePlatformAppSettings.js'
+
+type ReactActGlobal = typeof globalThis & {
+  IS_REACT_ACT_ENVIRONMENT?: boolean
+}
+
+type Settings = Record<string, unknown> & {
+  view: 'list' | 'board'
+}
+
+const appSettingsMock = vi.hoisted(() => ({
+  getPlatformAppSettings: vi.fn(),
+  updatePlatformAppSettings: vi.fn(),
+}))
+
+vi.mock('../appSettings.mjs', () => appSettingsMock)
+
+let latest:
+  | ReturnType<typeof usePlatformAppSettings<Settings>>
+  | null = null
+
+function parseSettings(raw: Record<string, unknown>): Settings {
+  return {
+    view: raw.view === 'board' ? 'board' : 'list',
+  }
+}
+
+function Probe(): React.ReactElement {
+  latest = usePlatformAppSettings<Settings>({
+    appSlug: 'tasks',
+    parse: parseSettings,
+    initialSettings: { view: 'list' },
+  })
+  return <div />
+}
+
+async function flushEffects(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+describe('usePlatformAppSettings', () => {
+  let host: HTMLDivElement
+  let root: Root
+
+  beforeAll(() => {
+    ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  beforeEach(() => {
+    latest = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    appSettingsMock.getPlatformAppSettings.mockResolvedValue({ view: 'board' })
+    appSettingsMock.updatePlatformAppSettings.mockResolvedValue({ view: 'list' })
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    host.remove()
+    vi.clearAllMocks()
+  })
+
+  it('loads and normalizes app settings for one app slug', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    expect(appSettingsMock.getPlatformAppSettings).toHaveBeenCalledWith('tasks')
+    expect(latest?.settings).toEqual({ view: 'board' })
+  })
+
+  it('patches app settings through settings.app.update', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      await latest?.patchSettings({ view: 'list' })
+    })
+
+    expect(appSettingsMock.updatePlatformAppSettings).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      patch: { view: 'list' },
+    })
+    expect(latest?.settings).toEqual({ view: 'list' })
+  })
+})