@practicalkit/plugin-sdk 0.0.2

package/src/messages/ui/getState/message.schemas.ts

@@ -0,0 +1,33 @@
+import { string, array, object, boolean, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+const TabInfoSchema = object({
+  id: string(),
+  title: string(),
+  isActive: boolean(),
+});
+
+const UiGetStateRequestPayloadSchema = object({
+  requestId: string(),
+});
+
+const UiGetStateResponsePayloadSchema = object({
+  requestId: string(),
+  openTabs: array(TabInfoSchema),
+});
+
+export const UiGetState = {
+  Request: respondableMessage("ui.getState", {}),
+  Response: respondableMessage("ui.getState.response", {
+    openTabs: array(TabInfoSchema),
+  }),
+};
+
+export type UiGetStateRequest = InferOutput<typeof UiGetState.Request>;
+export type UiGetStateResponse = InferOutput<typeof UiGetState.Response>;
+export type UiGetStateRequestPayload = InferOutput<
+  typeof UiGetStateRequestPayloadSchema
+>;
+export type UiGetStateResponsePayload = InferOutput<
+  typeof UiGetStateResponsePayloadSchema
+>;

package/src/messages/ui/index.ts

@@ -0,0 +1,7 @@
+export * from "./setCollapseState/message.schemas.js";
+export * from "./showContextMenu/message.schemas.js";
+export * from "./showNotification/message.schemas.js";
+export * from "./tabsChanged/message.schemas.js";
+export * from "./getState/message.schemas.js";
+export * from "./confirm/message.schemas.js";
+export * from "./UiChannel.js";

package/src/messages/ui/setCollapseState/message.schemas.ts

@@ -0,0 +1,34 @@
+import { boolean, string, object, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+const UiSetCollapseStateRequestPayloadSchema = object({
+  requestId: string(),
+  collapsed: boolean(),
+});
+
+const UiSetCollapseStateResponsePayloadSchema = object({
+  requestId: string(),
+  success: boolean(),
+});
+
+export const UiSetCollapseState = {
+  Request: respondableMessage("ui.setCollapseState", {
+    collapsed: boolean(),
+  }),
+  Response: respondableMessage("ui.setCollapseState.response", {
+    success: boolean(),
+  }),
+};
+
+export type UiSetCollapseStateRequest = InferOutput<
+  typeof UiSetCollapseState.Request
+>;
+export type UiSetCollapseStateResponse = InferOutput<
+  typeof UiSetCollapseState.Response
+>;
+export type UiSetCollapseStateRequestPayload = InferOutput<
+  typeof UiSetCollapseStateRequestPayloadSchema
+>;
+export type UiSetCollapseStateResponsePayload = InferOutput<
+  typeof UiSetCollapseStateResponsePayloadSchema
+>;

package/src/messages/ui/showContextMenu/message.schemas.ts

@@ -0,0 +1,64 @@
+import {
+  number,
+  string,
+  array,
+  object,
+  nullable,
+  union,
+  literal,
+  optional,
+  type InferOutput,
+} from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+/**
+ * Context menu item schema.
+ * Can be either a regular item with id/label, or a separator.
+ */
+const ContextMenuItem = union([
+  object({
+    type: optional(literal("item")),
+    id: string(),
+    label: string(),
+  }),
+  object({
+    type: literal("separator"),
+  }),
+]);
+
+export const UiShowContextMenu = {
+  Request: respondableMessage("ui.showContextMenu", {
+    x: number(),
+    y: number(),
+    items: array(ContextMenuItem),
+  }),
+  Response: respondableMessage("ui.showContextMenu.response", {
+    selectedItemId: nullable(string()),
+  }),
+};
+
+const UiShowContextMenuRequestPayloadSchema = object({
+  requestId: string(),
+  x: number(),
+  y: number(),
+  items: array(ContextMenuItem),
+});
+
+const UiShowContextMenuResponsePayloadSchema = object({
+  requestId: string(),
+  selectedItemId: nullable(string()),
+});
+
+export type ContextMenuItemType = InferOutput<typeof ContextMenuItem>;
+export type UiShowContextMenuRequest = InferOutput<
+  typeof UiShowContextMenu.Request
+>;
+export type UiShowContextMenuResponse = InferOutput<
+  typeof UiShowContextMenu.Response
+>;
+export type UiShowContextMenuRequestPayload = InferOutput<
+  typeof UiShowContextMenuRequestPayloadSchema
+>;
+export type UiShowContextMenuResponsePayload = InferOutput<
+  typeof UiShowContextMenuResponsePayloadSchema
+>;

package/src/messages/ui/showNotification/message.schemas.ts

@@ -0,0 +1,41 @@
+import { string, object, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+const NotificationTypeSchema = union([
+  literal("info"),
+  literal("success"),
+  literal("warning"),
+  literal("error"),
+]);
+
+const UiShowNotificationRequestPayloadSchema = object({
+  requestId: string(),
+  message: string(),
+  type: NotificationTypeSchema,
+});
+
+export const UiShowNotification = {
+  Request: respondableMessage("ui.showNotification", {
+    message: string(),
+    type: NotificationTypeSchema,
+  }),
+  Response: union([
+    respondableMessage("ui.showNotification.response", {
+      success: literal(true),
+    }),
+    respondableMessage("ui.showNotification.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type UiShowNotificationRequest = InferOutput<
+  typeof UiShowNotification.Request
+>;
+export type UiShowNotificationResponse = InferOutput<
+  typeof UiShowNotification.Response
+>;
+export type UiShowNotificationRequestPayload = InferOutput<
+  typeof UiShowNotificationRequestPayloadSchema
+>;

package/src/messages/ui/tabsChanged/message.schemas.ts

@@ -0,0 +1,25 @@
+import * as v from "valibot";
+
+export const UI_TABS_CHANGED_EVENT = "ui.tabsChanged";
+
+export const UiTabsChangedEventPayloadSchema = v.object({
+  openTabs: v.array(
+    v.object({
+      id: v.string(),
+      title: v.string(),
+      isActive: v.boolean(),
+    })
+  ),
+  hasOpenTabs: v.boolean(),
+});
+
+export type UiTabsChangedEventPayload = v.InferOutput<
+  typeof UiTabsChangedEventPayloadSchema
+>;
+
+export const UiTabsChangedEventSchema = v.object({
+  type: v.literal(UI_TABS_CHANGED_EVENT),
+  payload: UiTabsChangedEventPayloadSchema,
+});
+
+export type UiTabsChangedEvent = v.InferOutput<typeof UiTabsChangedEventSchema>;

package/src/messages/vfs/createDir/message.schemas.ts

@@ -0,0 +1,20 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsCreateDir = {
+  Request: respondableMessage("vfs.createDir", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.createDir.response", {
+      success: literal(true),
+    }),
+    respondableMessage("vfs.createDir.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsCreateDirRequest = InferOutput<typeof VfsCreateDir.Request>;
+export type VfsCreateDirResponse = InferOutput<typeof VfsCreateDir.Response>;

package/src/messages/vfs/delete/message.schemas.ts

@@ -0,0 +1,20 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsDelete = {
+  Request: respondableMessage("vfs.delete", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.delete.response", {
+      success: literal(true),
+    }),
+    respondableMessage("vfs.delete.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsDeleteRequest = InferOutput<typeof VfsDelete.Request>;
+export type VfsDeleteResponse = InferOutput<typeof VfsDelete.Response>;

package/src/messages/vfs/exists/message.schemas.ts

@@ -0,0 +1,32 @@
+import {
+  string,
+  type InferOutput,
+  literal,
+  object,
+  union,
+  boolean,
+  nullable,
+} from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsExists = {
+  Request: respondableMessage("vfs.exists", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.exists.response", {
+      success: literal(true),
+      data: object({
+        exists: boolean(),
+        entryType: nullable(string()),
+      }),
+    }),
+    respondableMessage("vfs.exists.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsExistsRequest = InferOutput<typeof VfsExists.Request>;
+export type VfsExistsResponse = InferOutput<typeof VfsExists.Response>;

package/src/messages/vfs/getAbsolutePath/message.schemas.ts

@@ -0,0 +1,27 @@
+import { string, type InferOutput, literal, object, union } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsGetAbsolutePath = {
+  Request: respondableMessage("vfs.getAbsolutePath", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.getAbsolutePath.response", {
+      success: literal(true),
+      data: object({
+        absolutePath: string(),
+      }),
+    }),
+    respondableMessage("vfs.getAbsolutePath.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsGetAbsolutePathRequest = InferOutput<
+  typeof VfsGetAbsolutePath.Request
+>;
+export type VfsGetAbsolutePathResponse = InferOutput<
+  typeof VfsGetAbsolutePath.Response
+>;

package/src/messages/vfs/index.ts

@@ -0,0 +1,8 @@
+export * from "./createDir/message.schemas.js";
+export * from "./delete/message.schemas.js";
+export * from "./exists/message.schemas.js";
+export * from "./getAbsolutePath/message.schemas.js";
+export * from "./readDir/message.schemas.js";
+export * from "./readFile/message.schemas.js";
+export * from "./rename/message.schemas.js";
+export * from "./writeFile/message.schemas.js";

package/src/messages/vfs/readDir/message.schemas.ts

@@ -0,0 +1,36 @@
+import {
+  string,
+  type InferOutput,
+  literal,
+  array,
+  object,
+  union,
+  number,
+} from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const DirectoryEntrySchema = object({
+  name: string(),
+  type: union([literal("file"), literal("directory")]),
+  size: number(),
+});
+
+export const VfsReadDir = {
+  Request: respondableMessage("vfs.readDir", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.readDir.response", {
+      success: literal(true),
+      data: array(DirectoryEntrySchema),
+    }),
+    respondableMessage("vfs.readDir.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type DirectoryEntry = InferOutput<typeof DirectoryEntrySchema>;
+export type VfsReadDirRequest = InferOutput<typeof VfsReadDir.Request>;
+export type VfsReadDirResponse = InferOutput<typeof VfsReadDir.Response>;

package/src/messages/vfs/readFile/message.schemas.ts

@@ -0,0 +1,21 @@
+import { string, type InferOutput, literal, object, union } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsReadFile = {
+  Request: respondableMessage("vfs.readFile", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.readFile.response", {
+      success: literal(true),
+      data: string(),
+    }),
+    respondableMessage("vfs.readFile.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsReadFileRequest = InferOutput<typeof VfsReadFile.Request>;
+export type VfsReadFileResponse = InferOutput<typeof VfsReadFile.Response>;

package/src/messages/vfs/rename/message.schemas.ts

@@ -0,0 +1,21 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsRename = {
+  Request: respondableMessage("vfs.rename", {
+    oldPath: string(),
+    newPath: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.rename.response", {
+      success: literal(true),
+    }),
+    respondableMessage("vfs.rename.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsRenameRequest = InferOutput<typeof VfsRename.Request>;
+export type VfsRenameResponse = InferOutput<typeof VfsRename.Response>;

package/src/messages/vfs/writeFile/message.schemas.ts

@@ -0,0 +1,21 @@
+import { string, type InferOutput, literal, union } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const VfsWriteFile = {
+  Request: respondableMessage("vfs.writeFile", {
+    path: string(),
+    content: string(),
+  }),
+  Response: union([
+    respondableMessage("vfs.writeFile.response", {
+      success: literal(true),
+    }),
+    respondableMessage("vfs.writeFile.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type VfsWriteFileRequest = InferOutput<typeof VfsWriteFile.Request>;
+export type VfsWriteFileResponse = InferOutput<typeof VfsWriteFile.Response>;

package/src/messages/workspace/changed/message.schemas.ts

@@ -0,0 +1,18 @@
+import {
+  string,
+  type InferOutput,
+  object,
+  boolean,
+  nullable,
+  literal,
+} from "valibot";
+
+// Broadcast message (no requestId, no response)
+export const WorkspaceChangedSchema = object({
+  type: literal("workspace.changed"),
+  isOpen: boolean(),
+  path: nullable(string()),
+  name: nullable(string()),
+});
+
+export type WorkspaceChanged = InferOutput<typeof WorkspaceChangedSchema>;

package/src/messages/workspace/getDetails/message.schemas.ts

@@ -0,0 +1,39 @@
+import {
+  string,
+  type InferOutput,
+  literal,
+  union,
+  object,
+  boolean,
+  nullable,
+} from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+// Shared workspace details shape
+export const WorkspaceDetailsSchema = object({
+  isOpen: boolean(),
+  path: nullable(string()),
+  name: nullable(string()),
+});
+
+export const WorkspaceGetDetails = {
+  Request: respondableMessage("workspace.getDetails", {}),
+  Response: union([
+    respondableMessage("workspace.getDetails.response", {
+      success: literal(true),
+      data: WorkspaceDetailsSchema,
+    }),
+    respondableMessage("workspace.getDetails.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type WorkspaceDetails = InferOutput<typeof WorkspaceDetailsSchema>;
+export type WorkspaceGetDetailsRequest = InferOutput<
+  typeof WorkspaceGetDetails.Request
+>;
+export type WorkspaceGetDetailsResponse = InferOutput<
+  typeof WorkspaceGetDetails.Response
+>;

package/src/messages/workspace/index.ts

@@ -0,0 +1,3 @@
+export * from "./getDetails/message.schemas.js";
+export * from "./changed/message.schemas.js";
+export * from "./open/message.schemas.js";

package/src/messages/workspace/open/message.schemas.ts

@@ -0,0 +1,27 @@
+import {
+  string,
+  type InferOutput,
+  literal,
+  union,
+  object,
+  boolean,
+  nullable,
+} from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const WorkspaceOpen = {
+  Request: respondableMessage("workspace.open", {}),
+  Response: union([
+    respondableMessage("workspace.open.response", {
+      success: literal(true),
+      path: nullable(string()),
+    }),
+    respondableMessage("workspace.open.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type WorkspaceOpenRequest = InferOutput<typeof WorkspaceOpen.Request>;
+export type WorkspaceOpenResponse = InferOutput<typeof WorkspaceOpen.Response>;

package/src/namespaces/DocumentNamespace.ts

@@ -0,0 +1,164 @@
+import { safeParse } from "valibot";
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  DocumentRequestContent,
+  DocumentSave,
+  DocumentSaveRequested,
+  DocumentSaved,
+} from "../messages/index.js";
+
+/**
+ * Document lifecycle namespace for editor plugins.
+ * This class is not part of the public SDK API.
+ *
+ * Editor plugins should:
+ * 1. Call requestContent() to get initial content when ready
+ * 2. Listen for onSaveRequested and respond with current content
+ * 3. Listen for onSaved to know when save completed
+ * 4. Call requestSave() when user presses Ctrl+S
+ */
+export class DocumentNamespace {
+  private readonly client: IFrameClient;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  /**
+   * Request initial content from the host.
+   * Call this when the plugin is ready to receive content.
+   * @returns Promise with the content and hash
+   */
+  async requestContent(): Promise<{ content: string; hash: string }> {
+    const response = await this.client.sendAndWait(
+      "document.requestContent",
+      {},
+      DocumentRequestContent.Request,
+      DocumentRequestContent.Response
+    );
+
+    if (!response.success) {
+      throw new Error((response as { error: string }).error);
+    }
+    return {
+      content: (response as { content: string }).content,
+      hash: (response as { hash: string }).hash,
+    };
+  }
+
+  /**
+   * Request the host to save the current document.
+   * Call this when the user presses Ctrl+S inside the plugin.
+   * The host will request content via onSaveRequested, then save to disk.
+   * @returns Promise with the new file hash on success
+   */
+  async requestSave(): Promise<string> {
+    const response = await this.client.sendAndWait(
+      "document.save",
+      {},
+      DocumentSave.Request,
+      DocumentSave.Response
+    );
+
+    if (!response.success) {
+      throw new Error((response as { error: string }).error);
+    }
+    return (response as { hash: string }).hash;
+  }
+
+  /**
+   * Listen for save requests from the host.
+   * The plugin should respond with the current document content.
+   * @param callback Function to handle save request, should return current content
+   * @returns Unsubscribe function
+   */
+  onSaveRequested(
+    callback: (payload: { requestId: string }) => Promise<string>
+  ): () => void {
+    return this.client.subscribe(async (evt) => {
+      const { type } = evt.data || {};
+      if (type !== "document.saveRequested") {
+        return;
+      }
+
+      const result = safeParse(DocumentSaveRequested.Request, evt.data);
+
+      if (!result.success) {
+        console.error(
+          "[SDK] Invalid document.saveRequested payload:",
+          result.issues
+        );
+        return;
+      }
+
+      try {
+        const content = await callback(result.output.payload);
+        this.client.send({
+          type: "document.saveRequested.response",
+          payload: {
+            requestId: result.output.payload.requestId,
+            success: true,
+            content,
+          },
+        });
+      } catch (error) {
+        this.client.send({
+          type: "document.saveRequested.response",
+          payload: {
+            requestId: result.output.payload.requestId,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+      }
+    });
+  }
+
+  /**
+   * Listen for save completion notifications.
+   * Called after the host has successfully saved the document.
+   * @param callback Function called when save completes
+   * @returns Unsubscribe function
+   */
+  onSaved(
+    callback: (payload: { hash: string; requestId: string }) => void
+  ): () => void {
+    return this.client.subscribe((evt) => {
+      const { type } = evt.data || {};
+      if (type !== "document.saved") {
+        return;
+      }
+
+      const result = safeParse(DocumentSaved.Request, evt.data);
+
+      if (!result.success) {
+        console.error("[SDK] Invalid document.saved payload:", result.issues);
+        return;
+      }
+
+      callback(result.output.payload);
+    });
+  }
+
+  /**
+   * Send a response to a document.saved message.
+   * Call this after processing the saved notification in onSaved callback.
+   */
+  respondToSaved(requestId: string, success: boolean, error?: string): void {
+    if (success) {
+      this.client.send({
+        type: "document.saved.response",
+        payload: { requestId, success: true },
+      });
+    } else {
+      this.client.send({
+        type: "document.saved.response",
+        payload: {
+          requestId,
+          success: false,
+          error: error || "Unknown error",
+        },
+      });
+    }
+  }
+}