@puredesktop/puredesktop-ui-bridge 2.1.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/puredesktop-ui-bridge",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "PureScience plugin SDK — bridge client, theme, and shared UI",
   "type": "module",
   "repository": {
@@ -20,6 +20,8 @@
     "./bridge/client": "./src/bridge/client.mjs",
     "./bridge/events": "./src/bridge/events.mjs",
     "./bridge/methods": "./src/bridge/methods.mjs",
+    "./bridge/network": "./src/bridge/network.mjs",
+    "./bridge/storage": "./src/bridge/storage.mjs",
     "./bridge/vision": "./src/bridge/vision.mjs",
     "./bridge/react/usePlatformBridge": "./src/bridge/react/usePlatformBridge.tsx",
     "./bridge/react/useIpc": "./src/bridge/react/useIpc.tsx",

package/src/bridge/dialog.d.mts

@@ -1,5 +1,8 @@
-export interface PlatformDialogPathResult {
-  path: string | null
-}
-
-export declare function openPlatformImageDialog(): Promise<string | null>
+export interface PlatformDialogPathResult {
+  path: string | null
+}
+
+export declare function openPlatformFolderDialog(): Promise<string | null>
+export declare function savePlatformFolderDialog(): Promise<string | null>
+export declare function openPlatformImageDialog(): Promise<string | null>
+export declare function openPlatformFileDialog(): Promise<string | null>

package/src/bridge/dialog.mjs

@@ -1,13 +1,43 @@
-import { bridge } from './client.mjs'
-import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
-
-/**
- * @returns {Promise<string | null>} Absolute path to the picked image, or null if cancelled.
- */
-export async function openPlatformImageDialog() {
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @returns {Promise<string | null>} Absolute path to the picked folder, or null if cancelled.
+ */
+export async function openPlatformFolderDialog() {
+  const result = await bridge.call(
+    PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_FOLDER,
+    [],
+  )
+  return result?.path ?? null
+}
+
+/**
+ * @returns {Promise<string | null>} Absolute path to the picked parent folder, or null if cancelled.
+ */
+export async function savePlatformFolderDialog() {
+  const result = await bridge.call(
+    PLATFORM_BRIDGE_METHODS.DIALOG_SAVE_FOLDER,
+    [],
+  )
+  return result?.path ?? null
+}
+
+/**
+ * @returns {Promise<string | null>} Absolute path to the picked image, or null if cancelled.
+ */
+export async function openPlatformImageDialog() {
   const result = await bridge.call(
     PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_IMAGE,
     [],
-  )
-  return result?.path ?? null
-}
+  )
+  return result?.path ?? null
+}
+
+/**
+ * @returns {Promise<string | null>} Absolute path to the picked file, or null if cancelled.
+ */
+export async function openPlatformFileDialog() {
+  const result = await bridge.call(PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_FILE, [])
+  return result?.path ?? null
+}

package/src/bridge/dialog.test.ts

@@ -0,0 +1,73 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+const bridgeCall = vi.hoisted(() => vi.fn())
+
+vi.mock('./client.mjs', () => ({
+  bridge: {
+    call: bridgeCall,
+  },
+}))
+
+import {
+  openPlatformFileDialog,
+  openPlatformFolderDialog,
+  openPlatformImageDialog,
+  savePlatformFolderDialog,
+} from './dialog.mjs'
+
+beforeEach(() => {
+  bridgeCall.mockReset()
+})
+
+describe('dialog bridge helpers', () => {
+  it('opens a folder dialog using the shell method with no arguments', async () => {
+    bridgeCall.mockResolvedValue({ path: '/tmp' })
+
+    await expect(openPlatformFolderDialog()).resolves.toBe('/tmp')
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_FOLDER,
+      [],
+    )
+  })
+
+  it('opens a save folder dialog using the shell method with no arguments', async () => {
+    bridgeCall.mockResolvedValue({ path: '/tmp/project' })
+
+    await expect(savePlatformFolderDialog()).resolves.toBe('/tmp/project')
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.DIALOG_SAVE_FOLDER,
+      [],
+    )
+  })
+
+  it('opens an image dialog using the shell method with no arguments', async () => {
+    bridgeCall.mockResolvedValue({ path: '/tmp/image.png' })
+
+    await expect(openPlatformImageDialog()).resolves.toBe('/tmp/image.png')
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_IMAGE,
+      [],
+    )
+  })
+
+  it('opens a file dialog using the shell method with no arguments', async () => {
+    bridgeCall.mockResolvedValue({ path: '/tmp/file.md' })
+
+    await expect(openPlatformFileDialog()).resolves.toBe('/tmp/file.md')
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_FILE,
+      [],
+    )
+  })
+
+  it('returns null when the shell dialog is cancelled', async () => {
+    bridgeCall.mockResolvedValue({ path: null })
+
+    await expect(openPlatformFolderDialog()).resolves.toBeNull()
+  })
+})

package/src/bridge/fs.d.mts

@@ -1,15 +1,31 @@
-import type {
-  PlatformFilePreviewUrlResult,
-  PlatformFileReadBinaryResult,
-  PlatformFileReadPreviewResult,
-} from './types.js'
+import type {
+  PlatformFileCreateFolderResult,
+  PlatformFileDeleteResult,
+  PlatformFileListResult,
+  PlatformFilePreviewUrlResult,
+  PlatformFileReadBinaryResult,
+  PlatformFileReadPreviewResult,
+  PlatformFileRenameResult,
+  PlatformFileWriteResult,
+} from './types.js'
 
-export declare const PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES: number
-export declare const PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES: number
-
-export declare function readPlatformFilePreview(
-  path: string,
-  maxBytes?: number,
+export declare const PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES: number
+export declare const PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES: number
+
+export declare function listPlatformFiles(
+  rootPath: string,
+): Promise<PlatformFileListResult>
+
+export declare function readPlatformTextFile(path: string): Promise<string>
+
+export declare function writePlatformTextFile(
+  path: string,
+  content: string,
+): Promise<PlatformFileWriteResult>
+
+export declare function readPlatformFilePreview(
+  path: string,
+  maxBytes?: number,
 ): Promise<PlatformFileReadPreviewResult>
 
 export declare function readPlatformFileBinary(
@@ -35,7 +51,17 @@ export declare function writePlatformFileBinary(
   base64: string,
 ): Promise<{ ok: true }>
 
-export declare function createPlatformFolder(
-  parentPath: string,
-  name: string,
-): Promise<{ path: string }>
+export declare function createPlatformFolder(
+  parentPath: string,
+  name: string,
+): Promise<PlatformFileCreateFolderResult>
+
+export declare function renamePlatformFile(
+  path: string,
+  name: string,
+): Promise<PlatformFileRenameResult>
+
+export declare function deletePlatformFile(
+  path: string,
+  recursive?: boolean,
+): Promise<PlatformFileDeleteResult>

package/src/bridge/fs.mjs

@@ -5,13 +5,38 @@ import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
 export const PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES = 64 * 1024
 
 /** Default binary preview cap for legacy inline image reads. Prefer `fs.previewUrl`. */
-export const PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES = 5 * 1024 * 1024
-
-/**
- * @param {string} path
- * @returns {Promise<import('./types.ts').PlatformFilePreviewUrlResult>}
- */
-export async function readPlatformFilePreviewUrl(path) {
+export const PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES = 5 * 1024 * 1024
+
+/**
+ * @param {string} rootPath
+ * @returns {Promise<import('./types.ts').PlatformFileListResult>}
+ */
+export async function listPlatformFiles(rootPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_LIST, [{ rootPath }])
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<string>}
+ */
+export async function readPlatformTextFile(path) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_READ, [path])
+}
+
+/**
+ * @param {string} path
+ * @param {string} content
+ * @returns {Promise<import('./types.ts').PlatformFileWriteResult>}
+ */
+export async function writePlatformTextFile(path, content) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_WRITE, [path, content])
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<import('./types.ts').PlatformFilePreviewUrlResult>}
+ */
+export async function readPlatformFilePreviewUrl(path) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.FS_PREVIEW_URL, [{ path }])
 }
 
@@ -75,8 +100,27 @@ export async function writePlatformFileBinary(path, base64) {
  * @param {string} name
  * @returns {Promise<{ path: string }>}
  */
-export async function createPlatformFolder(parentPath, name) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_CREATE_FOLDER, [
-    { parentPath, name },
-  ])
-}
+export async function createPlatformFolder(parentPath, name) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_CREATE_FOLDER, [
+    { parentPath, name },
+  ])
+}
+
+/**
+ * @param {string} path
+ * @param {string} name
+ * @returns {Promise<import('./types.ts').PlatformFileRenameResult>}
+ */
+export async function renamePlatformFile(path, name) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_RENAME, [{ path, name }])
+}
+
+/**
+ * @param {string} path
+ * @param {boolean | undefined} recursive
+ * @returns {Promise<import('./types.ts').PlatformFileDeleteResult>}
+ */
+export async function deletePlatformFile(path, recursive) {
+  const request = recursive === undefined ? { path } : { path, recursive }
+  return bridge.call(PLATFORM_BRIDGE_METHODS.FS_DELETE, [request])
+}

package/src/bridge/fs.test.ts

@@ -1,9 +1,30 @@
-import { describe, expect, it } from 'vitest'
-import { dataUrlFromFileBinary } from './fs.mjs'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+const bridgeCall = vi.hoisted(() => vi.fn())
+
+vi.mock('./client.mjs', () => ({
+  bridge: {
+    call: bridgeCall,
+  },
+}))
+
+import {
+  dataUrlFromFileBinary,
+  deletePlatformFile,
+  listPlatformFiles,
+  readPlatformTextFile,
+  renamePlatformFile,
+  writePlatformTextFile,
+} from './fs.mjs'
+
+beforeEach(() => {
+  bridgeCall.mockReset()
+})
 
-describe('dataUrlFromFileBinary', () => {
-  it('builds a data URL from bridge binary result', () => {
-    expect(
+describe('dataUrlFromFileBinary', () => {
+  it('builds a data URL from bridge binary result', () => {
+    expect(
       dataUrlFromFileBinary({
         path: '/tmp/image.png',
         mimeType: 'image/png',
@@ -11,6 +32,59 @@ describe('dataUrlFromFileBinary', () => {
         truncated: false,
         byteLength: 3,
       }),
-    ).toBe('data:image/png;base64,abc123')
-  })
-})
+    ).toBe('data:image/png;base64,abc123')
+  })
+})
+
+describe('filesystem bridge helpers', () => {
+  it('lists files using the shell request object shape', async () => {
+    bridgeCall.mockResolvedValue({ entries: [] })
+
+    await listPlatformFiles('/tmp')
+
+    expect(bridgeCall).toHaveBeenCalledWith(PLATFORM_BRIDGE_METHODS.FS_LIST, [
+      { rootPath: '/tmp' },
+    ])
+  })
+
+  it('reads text files using the shell path argument shape', async () => {
+    bridgeCall.mockResolvedValue('hello')
+
+    await readPlatformTextFile('/tmp/a.md')
+
+    expect(bridgeCall).toHaveBeenCalledWith(PLATFORM_BRIDGE_METHODS.FS_READ, [
+      '/tmp/a.md',
+    ])
+  })
+
+  it('writes text files using the shell path and content argument shape', async () => {
+    bridgeCall.mockResolvedValue({ ok: true })
+
+    await writePlatformTextFile('/tmp/a.md', 'hello')
+
+    expect(bridgeCall).toHaveBeenCalledWith(PLATFORM_BRIDGE_METHODS.FS_WRITE, [
+      '/tmp/a.md',
+      'hello',
+    ])
+  })
+
+  it('renames files using the shell request object shape', async () => {
+    bridgeCall.mockResolvedValue({ path: '/tmp/b.md' })
+
+    await renamePlatformFile('/tmp/a.md', 'b.md')
+
+    expect(bridgeCall).toHaveBeenCalledWith(PLATFORM_BRIDGE_METHODS.FS_RENAME, [
+      { path: '/tmp/a.md', name: 'b.md' },
+    ])
+  })
+
+  it('deletes files using the shell request object shape', async () => {
+    bridgeCall.mockResolvedValue({ ok: true })
+
+    await deletePlatformFile('/tmp/a.md', true)
+
+    expect(bridgeCall).toHaveBeenCalledWith(PLATFORM_BRIDGE_METHODS.FS_DELETE, [
+      { path: '/tmp/a.md', recursive: true },
+    ])
+  })
+})

package/src/bridge/fs.ts

@@ -1,10 +1,28 @@
-export {
-  dataUrlFromFileBinary,
-  readPlatformFileBinary,
-  readPlatformFileBinaryDataUrl,
-  readPlatformFilePreview,
-  readPlatformFilePreviewUrl,
-  writePlatformFileBinary,
-  PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES,
-  PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES,
-} from './fs.mjs'
+export {
+  createPlatformFolder,
+  dataUrlFromFileBinary,
+  deletePlatformFile,
+  listPlatformFiles,
+  readPlatformFileBinary,
+  readPlatformFileBinaryDataUrl,
+  readPlatformFilePreview,
+  readPlatformFilePreviewUrl,
+  readPlatformTextFile,
+  renamePlatformFile,
+  writePlatformFileBinary,
+  writePlatformTextFile,
+  PLATFORM_FILE_BINARY_PREVIEW_MAX_BYTES,
+  PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES,
+} from './fs.mjs'
+
+export type {
+  PlatformFileCreateFolderResult,
+  PlatformFileDeleteResult,
+  PlatformFileEntry,
+  PlatformFileListResult,
+  PlatformFilePreviewUrlResult,
+  PlatformFileReadBinaryResult,
+  PlatformFileReadPreviewResult,
+  PlatformFileRenameResult,
+  PlatformFileWriteResult,
+} from './types.js'

package/src/bridge/network.d.mts

@@ -0,0 +1,17 @@
+export interface PlatformNetworkFetchRequest {
+  url: string
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+}
+
+export interface PlatformNetworkFetchResponse {
+  status: number
+  ok: boolean
+  headers: Record<string, string>
+  body: string
+}
+
+export declare function networkFetch(
+  request: PlatformNetworkFetchRequest,
+): Promise<PlatformNetworkFetchResponse>

package/src/bridge/network.mjs

@@ -0,0 +1,22 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Fetch an HTTP(S) resource through the shell network bridge.
+ *
+ * @param {{
+ *   url: string,
+ *   method?: string,
+ *   headers?: Record<string, string>,
+ *   body?: string,
+ * }} request
+ * @returns {Promise<{
+ *   status: number,
+ *   ok: boolean,
+ *   headers: Record<string, string>,
+ *   body: string,
+ * }>}
+ */
+export async function networkFetch(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.NETWORK_FETCH, [request])
+}

package/src/bridge/storage.d.mts

@@ -0,0 +1,27 @@
+export interface PlatformStorageJsonRequest {
+  appSlug: string
+  fileName: string
+}
+
+export interface PlatformStorageJsonReadResult {
+  path: string
+  value: unknown | null
+}
+
+export interface PlatformStorageJsonWriteRequest
+  extends PlatformStorageJsonRequest {
+  value: unknown
+}
+
+export interface PlatformStorageJsonWriteResult {
+  path: string
+  ok: true
+}
+
+export declare function readPlatformStorageJson(
+  request: PlatformStorageJsonRequest,
+): Promise<PlatformStorageJsonReadResult>
+
+export declare function writePlatformStorageJson(
+  request: PlatformStorageJsonWriteRequest,
+): Promise<PlatformStorageJsonWriteResult>

package/src/bridge/storage.mjs

@@ -0,0 +1,18 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @param {{ appSlug: string, fileName: string }} request
+ * @returns {Promise<{ path: string, value: unknown | null }>}
+ */
+export async function readPlatformStorageJson(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_READ_JSON, [request])
+}
+
+/**
+ * @param {{ appSlug: string, fileName: string, value: unknown }} request
+ * @returns {Promise<{ path: string, ok: true }>}
+ */
+export async function writePlatformStorageJson(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_WRITE_JSON, [request])
+}

package/src/bridge/storage.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+const bridgeCall = vi.hoisted(() => vi.fn())
+
+vi.mock('./client.mjs', () => ({
+  bridge: {
+    call: bridgeCall,
+  },
+}))
+
+import {
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+} from './storage.mjs'
+
+beforeEach(() => {
+  bridgeCall.mockReset()
+})
+
+describe('storage bridge helpers', () => {
+  it('reads JSON storage using the shell request object shape', async () => {
+    const request = { appSlug: 'puretasks', fileName: 'tasks.json' }
+    bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', value: null })
+
+    await readPlatformStorageJson(request)
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.STORAGE_READ_JSON,
+      [request],
+    )
+  })
+
+  it('writes JSON storage using the shell request object shape', async () => {
+    const request = {
+      appSlug: 'puretasks',
+      fileName: 'tasks.json',
+      value: { tasks: [] },
+    }
+    bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', ok: true })
+
+    await writePlatformStorageJson(request)
+
+    expect(bridgeCall).toHaveBeenCalledWith(
+      PLATFORM_BRIDGE_METHODS.STORAGE_WRITE_JSON,
+      [request],
+    )
+  })
+})

package/src/bridge/types.ts

@@ -255,31 +255,64 @@ export interface PlatformAppInstallState {
   pluginRoot?: string
 }
 
-export interface PlatformFileReadPreviewResult {
-  path: string
-  content: string | null
-  truncated: boolean
-  encoding: 'utf-8'
-}
-
-export interface PlatformFileReadBinaryResult {
-  path: string
-  mimeType: string
-  base64: string
-  truncated: boolean
-  byteLength: number
-}
-
-export interface PlatformFilePreviewUrlResult {
-  path: string
-  url: string
-  mimeType: string
-  byteLength: number
-}
-
-/** Minimal file entry fields required for inline preview in plugin iframes. */
-export interface PlatformFilePreviewEntry {
-  path: string
+export interface PlatformFileReadPreviewResult {
+  path: string
+  content: string | null
+  truncated: boolean
+  encoding: 'utf-8'
+}
+
+export interface PlatformFileEntry {
+  path: string
+  name: string
+  extension: string
+  kind: PlatformFileKind
+  mimeType: string
+  byteLength: number
+  modifiedAt: string
+  isDirectory: boolean
+}
+
+export interface PlatformFileListResult {
+  rootPath: string
+  parentPath: string | null
+  entries: PlatformFileEntry[]
+}
+
+export interface PlatformFileReadBinaryResult {
+  path: string
+  mimeType: string
+  base64: string
+  truncated: boolean
+  byteLength: number
+}
+
+export interface PlatformFilePreviewUrlResult {
+  path: string
+  url: string
+  mimeType: string
+  byteLength: number
+}
+
+export interface PlatformFileCreateFolderResult {
+  path: string
+}
+
+export interface PlatformFileRenameResult {
+  path: string
+}
+
+export interface PlatformFileWriteResult {
+  ok: true
+}
+
+export interface PlatformFileDeleteResult {
+  ok: true
+}
+
+/** Minimal file entry fields required for inline preview in plugin iframes. */
+export interface PlatformFilePreviewEntry {
+  path: string
   name: string
   extension: string
   kind: PlatformFileKind