@practicalkit/plugin-sdk 0.0.2

package/src/namespaces/EditorNamespace.ts

@@ -0,0 +1,27 @@
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import { EditorOpenFile } from "../messages/index.js";
+
+/**
+ * Editor namespace for editor operations.
+ * This class is not part of the public SDK API.
+ */
+export class EditorNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  async openFile(path: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "editor.openFile",
+      { path },
+      EditorOpenFile.Request,
+      EditorOpenFile.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+}

package/src/namespaces/FsNamespace.ts

@@ -0,0 +1,77 @@
+import { safeParse } from "valibot";
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  FsSubscribe,
+  FsUnsubscribe,
+  FsFileChangedSchema,
+  type FsFileChanged,
+} from "../messages/index.js";
+
+/**
+ * File system namespace for file watching operations.
+ * This class is not part of the public SDK API.
+ */
+export class FsNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  /**
+   * Subscribe to file system change events.
+   * Requires the "fs.watch" permission in the plugin manifest.
+   */
+  async subscribe(): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "fs.subscribe",
+      {},
+      FsSubscribe.Request,
+      FsSubscribe.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  /**
+   * Unsubscribe from file system change events.
+   */
+  async unsubscribe(): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "fs.unsubscribe",
+      {},
+      FsUnsubscribe.Request,
+      FsUnsubscribe.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  /**
+   * Listen for file change events.
+   * Must call fs.subscribe() first.
+   * @param callback Function called when a file changes
+   * @returns Unsubscribe function
+   */
+  onFileChanged(callback: (event: FsFileChanged) => void): () => void {
+    return this.client.subscribe((evt) => {
+      const { type } = evt.data || {};
+      if (type !== "fs.fileChanged") {
+        return;
+      }
+
+      const result = safeParse(FsFileChangedSchema, evt.data);
+
+      if (!result.success) {
+        console.error("[SDK] Invalid fs.fileChanged payload:", result.issues);
+        return;
+      }
+
+      callback(result.output);
+    });
+  }
+}

package/src/namespaces/NativeNamespace.ts

@@ -0,0 +1,34 @@
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import { NativeCall } from "../messages/index.js";
+
+/**
+ * Native namespace for calling native plugin modules.
+ * This class is not part of the public SDK API.
+ */
+export class NativeNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  async call(
+    pluginId: string,
+    moduleId: string,
+    command: string,
+    args: unknown
+  ): Promise<unknown> {
+    const response = await this.client.sendAndWait(
+      "native.call",
+      { pluginId, moduleId, command, args },
+      NativeCall.Request,
+      NativeCall.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data;
+  }
+}

package/src/namespaces/PluginNamespace.ts

@@ -0,0 +1,156 @@
+import { safeParse } from "valibot";
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  PluginSendMessage,
+  PluginMessage,
+  PluginSendBroadcast,
+  PluginBroadcast,
+} from "../messages/index.js";
+
+/**
+ * Intra-plugin messaging namespace.
+ * This class is not part of the public SDK API.
+ *
+ * Allows modules within the same plugin to communicate with each other.
+ * Messages are routed through the host - modules cannot communicate directly.
+ *
+ * Use cases:
+ * - A panel module sending commands to a backgroundService module
+ * - A backgroundService module notifying UI modules of state changes
+ * - Coordinating work between multiple UI modules
+ */
+export class PluginNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  /**
+   * Send a message to a specific sibling module within the same plugin.
+   * Returns a promise that resolves with the response from the target module.
+   *
+   * @param targetModuleId - The module ID to send the message to
+   * @param message - The message payload (any serializable value)
+   * @returns Promise resolving to the response data from the target module
+   * @throws Error if the target module doesn't exist or fails to respond
+   */
+  async sendMessage<T = unknown>(
+    targetModuleId: string,
+    message: unknown
+  ): Promise<T> {
+    const response = await this.client.sendAndWait(
+      "plugin.sendMessage",
+      { targetModuleId, message },
+      PluginSendMessage.Request,
+      PluginSendMessage.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to send message");
+    }
+
+    return response.data as T;
+  }
+
+  /**
+   * Listen for incoming messages from sibling modules.
+   * The handler should return a response that will be sent back to the sender.
+   * Supports both sync and async handlers.
+   *
+   * @param handler - Function that handles incoming messages and returns a response (sync or async)
+   * @returns Unsubscribe function
+   */
+  onMessage(
+    handler: (
+      payload: PluginMessage.HandlerPayload
+    ) => unknown | Promise<unknown>
+  ): () => void {
+    return this.client.subscribe((evt) => {
+      const { type } = evt.data || {};
+      if (type !== "plugin.message") {
+        return;
+      }
+
+      const result = safeParse(PluginMessage.Request, evt.data);
+
+      if (!result.success) {
+        console.error("[SDK] Invalid plugin.message payload:", result.issues);
+        return;
+      }
+
+      const requestId = result.output.payload.requestId;
+
+      // Wrap in Promise.resolve to handle both sync and async handlers
+      Promise.resolve()
+        .then(() => handler(result.output.payload))
+        .then((responseData) => {
+          this.client.send({
+            type: "plugin.message.response",
+            payload: {
+              requestId,
+              success: true,
+              data: responseData,
+            },
+          });
+        })
+        .catch((error) => {
+          console.error("[SDK] Error in plugin.onMessage handler:", error);
+          this.client.send({
+            type: "plugin.message.response",
+            payload: {
+              requestId,
+              success: false,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          });
+        });
+    });
+  }
+
+  /**
+   * Broadcast a message to all sibling modules within the same plugin.
+   * This is fire-and-forget - no response is expected.
+   *
+   * @param message - The message payload (any serializable value)
+   */
+  async sendBroadcast(message: unknown): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "plugin.sendBroadcast",
+      { message },
+      PluginSendBroadcast.Request,
+      PluginSendBroadcast.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to send broadcast");
+    }
+  }
+
+  /**
+   * Listen for broadcast messages from sibling modules.
+   * Broadcasts are fire-and-forget - no response is expected.
+   *
+   * @param handler - Function that handles incoming broadcasts
+   * @returns Unsubscribe function
+   */
+  onBroadcast(
+    handler: (payload: { fromModuleId: string; message: unknown }) => void
+  ): () => void {
+    return this.client.subscribe((evt) => {
+      const { type } = evt.data || {};
+      if (type !== "plugin.broadcast") {
+        return;
+      }
+
+      const result = safeParse(PluginBroadcast.Event, evt.data);
+
+      if (!result.success) {
+        console.error("[SDK] Invalid plugin.broadcast payload:", result.issues);
+        return;
+      }
+
+      handler(result.output.payload);
+    });
+  }
+}

package/src/namespaces/StorageNamespace.ts

@@ -0,0 +1,186 @@
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  StorageGet,
+  StorageSet,
+  StorageDelete,
+  StorageGetSecret,
+  StorageSetSecret,
+  StorageDeleteSecret,
+} from "../messages/index.js";
+
+/**
+ * Encode Uint8Array to base64 string.
+ */
+function encodeBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const len = bytes.length;
+  for (let i = 0; i < len; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Decode base64 string to Uint8Array.
+ */
+function decodeBase64(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const len = binary.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/**
+ * Storage namespace for plugin data and secrets.
+ *
+ * Provides two storage types:
+ * - `get`/`set`/`delete`: Non-secret storage for any binary data
+ * - `getSecret`/`setSecret`/`deleteSecret`: Encrypted storage for sensitive data
+ *
+ * Both use Uint8Array for values to support any binary data.
+ * Data is isolated per plugin (plugins cannot access each other's storage).
+ */
+export class StorageNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  // ===========================================================================
+  // Non-secret storage (raw bytes, unencrypted)
+  // ===========================================================================
+
+  /**
+   * Get a value from storage.
+   *
+   * @param key - The storage key
+   * @returns The value as Uint8Array, or null if not found
+   */
+  async get(key: string): Promise<Uint8Array | null> {
+    const response = await this.client.sendAndWait(
+      "storage.get",
+      { key },
+      StorageGet.Request,
+      StorageGet.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to get value");
+    }
+
+    if (response.value === null) {
+      return null;
+    }
+
+    return decodeBase64(response.value);
+  }
+
+  /**
+   * Set a value in storage.
+   *
+   * @param key - The storage key
+   * @param value - The value to store as Uint8Array
+   */
+  async set(key: string, value: Uint8Array): Promise<void> {
+    const base64 = encodeBase64(value);
+    const response = await this.client.sendAndWait(
+      "storage.set",
+      { key, value: base64 },
+      StorageSet.Request,
+      StorageSet.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to set value");
+    }
+  }
+
+  /**
+   * Delete a value from storage.
+   *
+   * @param key - The storage key to delete
+   */
+  async delete(key: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "storage.delete",
+      { key },
+      StorageDelete.Request,
+      StorageDelete.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to delete value");
+    }
+  }
+
+  // ===========================================================================
+  // Secret storage (encrypted at rest)
+  // ===========================================================================
+
+  /**
+   * Get a secret value for this plugin.
+   *
+   * @param key - The secret key (e.g., "apiKey", "token")
+   * @returns The secret value as Uint8Array, or null if not found
+   */
+  async getSecret(key: string): Promise<Uint8Array | null> {
+    const response = await this.client.sendAndWait(
+      "storage.getSecret",
+      { key },
+      StorageGetSecret.Request,
+      StorageGetSecret.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to get secret");
+    }
+
+    if (response.value === null) {
+      return null;
+    }
+
+    return decodeBase64(response.value);
+  }
+
+  /**
+   * Set a secret value for this plugin.
+   *
+   * @param key - The secret key (e.g., "apiKey", "token")
+   * @param value - The secret value to store as Uint8Array
+   */
+  async setSecret(key: string, value: Uint8Array): Promise<void> {
+    const base64 = encodeBase64(value);
+    const response = await this.client.sendAndWait(
+      "storage.setSecret",
+      { key, value: base64 },
+      StorageSetSecret.Request,
+      StorageSetSecret.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to set secret");
+    }
+  }
+
+  /**
+   * Delete a secret value for this plugin.
+   *
+   * @param key - The secret key to delete
+   */
+  async deleteSecret(key: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "storage.deleteSecret",
+      { key },
+      StorageDeleteSecret.Request,
+      StorageDeleteSecret.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to delete secret");
+    }
+  }
+}

package/src/namespaces/VfsNamespace.ts

@@ -0,0 +1,135 @@
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  VfsCreateDir,
+  VfsDelete,
+  VfsExists,
+  VfsGetAbsolutePath,
+  VfsReadDir,
+  VfsReadFile,
+  VfsRename,
+  VfsWriteFile,
+} from "../messages/index.js";
+
+/**
+ * Virtual file system namespace for file operations.
+ * This class is not part of the public SDK API.
+ */
+export class VfsNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  async exists(path: string) {
+    const response = await this.client.sendAndWait(
+      "vfs.exists",
+      { path },
+      VfsExists.Request,
+      VfsExists.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data;
+  }
+
+  async readDir(path: string) {
+    const response = await this.client.sendAndWait(
+      "vfs.readDir",
+      { path },
+      VfsReadDir.Request,
+      VfsReadDir.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data;
+  }
+
+  async readFile(path: string): Promise<string> {
+    const response = await this.client.sendAndWait(
+      "vfs.readFile",
+      { path },
+      VfsReadFile.Request,
+      VfsReadFile.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data;
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "vfs.writeFile",
+      { path, content },
+      VfsWriteFile.Request,
+      VfsWriteFile.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  async getAbsolutePath(path: string): Promise<string> {
+    const response = await this.client.sendAndWait(
+      "vfs.getAbsolutePath",
+      { path },
+      VfsGetAbsolutePath.Request,
+      VfsGetAbsolutePath.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data.absolutePath;
+  }
+
+  async rename(oldPath: string, newPath: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "vfs.rename",
+      { oldPath, newPath },
+      VfsRename.Request,
+      VfsRename.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  async delete(path: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "vfs.delete",
+      { path },
+      VfsDelete.Request,
+      VfsDelete.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  async createDir(path: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "vfs.createDir",
+      { path },
+      VfsCreateDir.Request,
+      VfsCreateDir.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+}

package/src/namespaces/WorkspaceNamespace.ts

@@ -0,0 +1,80 @@
+import { safeParse } from "valibot";
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  WorkspaceGetDetails,
+  WorkspaceOpen,
+  WorkspaceChangedSchema,
+  type WorkspaceChanged,
+  type WorkspaceDetails,
+} from "../messages/index.js";
+
+/**
+ * Workspace namespace for workspace operations.
+ * This class is not part of the public SDK API.
+ */
+export class WorkspaceNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  async getDetails(): Promise<WorkspaceDetails> {
+    const response = await this.client.sendAndWait(
+      "workspace.getDetails",
+      {},
+      WorkspaceGetDetails.Request,
+      WorkspaceGetDetails.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.data;
+  }
+
+  onChanged(callback: (payload: WorkspaceChanged) => void): () => void {
+    return this.client.subscribe((evt) => {
+      const { type, payload } = evt.data || {};
+
+      if (type !== "workspace.changed") {
+        return;
+      }
+
+      const result = safeParse(WorkspaceChangedSchema, {
+        type,
+        ...payload,
+      });
+
+      if (!result.success) {
+        console.error(
+          "[SDK] Invalid workspace.changed payload:",
+          result.issues
+        );
+        return;
+      }
+
+      callback(result.output);
+    });
+  }
+
+  /**
+   * Open a folder picker dialog to select a workspace.
+   * @returns The selected workspace path, or null if cancelled
+   */
+  async open(): Promise<string | null> {
+    const response = await this.client.sendAndWait(
+      "workspace.open",
+      {},
+      WorkspaceOpen.Request,
+      WorkspaceOpen.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+
+    return response.path;
+  }
+}

package/src/namespaces/index.ts

@@ -0,0 +1,8 @@
+export { VfsNamespace } from "./VfsNamespace.js";
+export { WorkspaceNamespace } from "./WorkspaceNamespace.js";
+export { EditorNamespace } from "./EditorNamespace.js";
+export { NativeNamespace } from "./NativeNamespace.js";
+export { FsNamespace } from "./FsNamespace.js";
+export { DocumentNamespace } from "./DocumentNamespace.js";
+export { PluginNamespace } from "./PluginNamespace.js";
+export { StorageNamespace } from "./StorageNamespace.js";