wings-plugin-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Josip Papež
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# wings-plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Types, a React hook and a build command for [Wings](https://github.com/josippapez/Wings) plugins.
+
+Wings itself gives each plugin the `wings` object at runtime. This package doesn't contain it: it types it, and
+bundles your TypeScript and React into the plain scripts Wings loads.
+
+## Set up
+
+```sh
+npm install --save-dev wings-plugin-sdk typescript
+npm install --save-dev react react-dom @types/react @types/react-dom   # only for React pages
+```
+
+`tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "types": ["wings-plugin-sdk"]
+  },
+  "include": ["src"]
+}
+```
+
+## Build
+
+Put the code in `src/`, next to `wings-plugin.json`. Every file at the top of `src/` builds to the file of the
+same name in the plugin folder, so `src/main.ts` becomes `main.js` and `src/sidebar.tsx` becomes `sidebar.js`.
+Folders inside `src/` hold the modules they import.
+
+```sh
+npx wings-plugin build           # writes main.js, sidebar.js, ...
+npx wings-plugin build --check   # fails if a built file is older than its source
+```
+
+Commit the built files. Wings installs a plugin from GitHub as the files in the repo, without building it.
+
+## React pages
+
+A sidebar, popover or view page is your own HTML that loads its built script:
+
+```html
+<main id="app"></main>
+<script src="sidebar.js"></script>
+```
+
+```tsx
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { useBroadcast } from "wings-plugin-sdk/react";
+
+function Sidebar() {
+  const [state, setState] = useState<unknown>(null);
+  useBroadcast((message) => setState(message));
+  return <pre>{JSON.stringify(state, null, 2)}</pre>;
+}
+
+createRoot(document.getElementById("app")!).render(<Sidebar />);
+```
+
+Every `wings.on*` call returns a function that removes the listener, so you can also return it from a
+`useEffect` yourself. The API reference is
+[plugins/README.md](https://github.com/josippapez/Wings/blob/main/plugins/README.md) in the Wings repo.

package/bin.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// wings-plugin build           builds the plugin in this folder
+// wings-plugin build --check   fails if a built file is older than its source
+import { relative } from "node:path";
+import { buildPlugin, entries } from "./build.mjs";
+
+const [command, ...flags] = process.argv.slice(2);
+if (command !== "build") {
+  console.error("Usage: wings-plugin build [--check]");
+  process.exit(2);
+}
+const dir = process.cwd();
+if (!entries(dir).length) {
+  console.error("No plugin to build here: wings-plugin build runs next to wings-plugin.json, with the code in src/.");
+  process.exit(1);
+}
+const check = flags.includes("--check");
+const { built, stale } = await buildPlugin(dir, { check });
+for (const { file, bytes } of built) console.log(`${relative(dir, file)}  ${(bytes / 1024).toFixed(1)} KB`);
+for (const file of stale) console.error(`${relative(dir, file)} is out of date. Run wings-plugin build and commit it.`);
+if (stale.length) process.exit(1);

package/build.d.ts

@@ -0,0 +1,11 @@
+/** The entries of the plugin in `dir`: one for each file at the top of its `src/`. */
+export function entries(dir: string): { src: string; out: string }[];
+
+/**
+ * Builds the plugin in `dir`: `src/main.ts` to `main.js`, `src/sidebar.tsx` to `sidebar.js`, and so on. With
+ * `check`, writes nothing and lists in `stale` the outputs that differ from what's on disk.
+ */
+export function buildPlugin(
+  dir: string,
+  options?: { check?: boolean; banner?: string },
+): Promise<{ built: { file: string; bytes: number }[]; stale: string[] }>;

package/build.mjs

@@ -0,0 +1,50 @@
+// Builds a plugin's src/ into the files Wings loads. Every file at the top of src/ is one entry, so src/main.ts
+// becomes main.js and src/sidebar.tsx becomes sidebar.js, next to wings-plugin.json. Folders inside src/ hold
+// the modules they import. Wings runs plain scripts, so each file is one bundle with its imports, React too.
+import * as esbuild from "esbuild";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, parse } from "node:path";
+
+const BANNER = "// Built from src/ by wings-plugin build. Edit src/, not this file.";
+
+/** The entries of the plugin in `dir`: `{ src, out }` for each file at the top of its src/. */
+export function entries(dir) {
+  const src = join(dir, "src");
+  if (!existsSync(join(dir, "wings-plugin.json")) || !existsSync(src)) return [];
+  return readdirSync(src, { withFileTypes: true })
+    .filter((f) => f.isFile() && /\.(ts|tsx|js|jsx)$/.test(f.name) && !f.name.endsWith(".d.ts"))
+    .map((f) => ({ src: join(src, f.name), out: join(dir, `${parse(f.name).name}.js`) }));
+}
+
+/**
+ * Builds the plugin in `dir`. With `check`, writes nothing and returns the outputs that differ from what's on
+ * disk instead, so a release can refuse built files older than their source.
+ */
+export async function buildPlugin(dir, { check = false, banner = BANNER } = {}) {
+  const built = [];
+  const stale = [];
+  for (const { src, out } of entries(dir)) {
+    const result = await esbuild.build({
+      entryPoints: [src],
+      bundle: true,
+      format: "iife",
+      // WKWebView on the oldest macOS Wings supports.
+      target: "safari16",
+      jsx: "automatic",
+      define: { "process.env.NODE_ENV": '"production"' },
+      banner: { js: banner },
+      legalComments: "none",
+      minify: true,
+      write: false,
+      logLevel: "warning",
+    });
+    const code = result.outputFiles[0].text;
+    if (check) {
+      if (!existsSync(out) || readFileSync(out, "utf8") !== code) stale.push(out);
+    } else {
+      writeFileSync(out, code);
+      built.push({ file: out, bytes: code.length });
+    }
+  }
+  return { built, stale };
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Types, React hooks and a build command for Wings plugins.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./wings.d.ts",
+  "exports": {
+    ".": {
+      "types": "./wings.d.ts"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./build": {
+      "types": "./build.d.ts",
+      "default": "./build.mjs"
+    }
+  },
+  "bin": {
+    "wings-plugin": "./bin.mjs"
+  },
+  "files": [
+    "wings.d.ts",
+    "react.js",
+    "react.d.ts",
+    "build.mjs",
+    "build.d.ts",
+    "bin.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josippapez/Wings.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/react.d.ts

@@ -0,0 +1,6 @@
+/// <reference path="./wings.d.ts" />
+/**
+ * Calls `listener` with each message the plugin's other pages send with `wings.broadcast`, while the component
+ * is mounted. The latest `listener` is used, so it can read state without resubscribing.
+ */
+export function useBroadcast(listener: (message: unknown) => void): void;

package/react.js

@@ -0,0 +1,11 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Calls `listener` with each message the plugin's other pages send with `wings.broadcast`, while the component
+ * is mounted. The latest `listener` is used, so it can read state without resubscribing.
+ */
+export function useBroadcast(listener) {
+  const latest = useRef(listener);
+  latest.current = listener;
+  useEffect(() => wings.onBroadcast((message) => latest.current(message)), []);
+}

package/wings.d.ts

@@ -0,0 +1,219 @@
+// Types for the Wings plugin SDK, API 1. `window.wings` exists in every plugin; this file only helps your editor.
+// In TypeScript, add "wings-plugin-sdk" to `types` in tsconfig.json. In JavaScript, start a file with
+// `// @ts-check` and `/// <reference types="wings-plugin-sdk" />`.
+
+type Tone = "neutral" | "info" | "success" | "warning" | "danger" | "merged";
+
+interface WingsPane {
+  paneId: string;
+  /** Follows `cd` in the pane. */
+  cwd: string;
+  /** What runs in the pane right now, like `zsh` or `claude`. */
+  command: string;
+  project: string;
+  /** Set while Claude Code runs in the pane. `startedAt` is when that `claude` started, in ms; a resumed session's transcript also has what came before. */
+  session: { sessionId: string; name: string | null; state: string; startedAt: number } | null;
+  /** The focused pane of the tab on screen. At most one pane has it, and none while no tab is open. */
+  focused: boolean;
+}
+
+interface WingsTranscriptEvent {
+  sessionId: string;
+  /** The pane the session runs in. */
+  paneId: string;
+  /** The entry as Claude Code wrote it. Its `type` is one of `permissions.transcript`. */
+  entry: { type: string } & Record<string, unknown>;
+}
+
+interface WingsBadge {
+  label: string;
+  tone: Tone;
+  icon?: "pr-open" | "pr-merged" | "pr-closed" | "pr-draft";
+  /** Small icon-and-number chips after the label. Leave out zeros. */
+  counts?: { icon: "changed" | "push" | "pull"; value: number }[];
+  /** Shows a spinner in the pill. */
+  loading?: boolean;
+  title?: string;
+  subtitle?: string;
+  rows?: { label: string; value: string; tone?: Tone }[];
+  actions?: { id: string; label: string; primary?: boolean }[];
+}
+
+interface WingsComment {
+  id: number;
+  replyTo: number | null;
+  /** `null` for a comment on the whole change. */
+  path: string | null;
+  /** `null` when the comment no longer matches the diff. */
+  line: number | null;
+  side: "additions" | "deletions";
+  author: string;
+  body: string;
+  createdAt: string;
+  url: string;
+  /** On the first comment of a thread: the viewer offers a reply box, and sends replies to `onReply`. */
+  canReply?: boolean;
+}
+
+/** A reply typed in the diff viewer. `replyTo` is the id of the thread's first comment. */
+interface WingsReply {
+  diffId: string;
+  replyTo: number;
+  body: string;
+}
+
+/** A usage limit window. `resetsAt` is in Unix epoch seconds. */
+interface WingsLimitWindow {
+  usedPercentage: number;
+  resetsAt: number | null;
+}
+
+/** What Claude Code last told `wings statusline`. `at` is when Wings got it, in ms. */
+interface WingsStatusline {
+  /** Your account's 5-hour and weekly limits, from the newest session that reported them. `null` until one has. */
+  rateLimits: { fiveHour: WingsLimitWindow | null; sevenDay: WingsLimitWindow | null; at: number } | null;
+  /** By session id. Token counts are from the session's last API response. */
+  sessions: Record<
+    string,
+    {
+      /** Like `Opus 5.5 (1M context)`. */
+      model: string | null;
+      contextWindowSize: number | null;
+      usedPercentage: number | null;
+      totalInputTokens: number | null;
+      totalOutputTokens: number | null;
+      currentUsage: { inputTokens: number; outputTokens: number; cacheCreationInputTokens: number; cacheReadInputTokens: number } | null;
+      /** `expiresAt` is in Unix epoch seconds. */
+      promptCache: { warm: boolean; ttl: "5m" | "1h" | null; expiresAt: number | null } | null;
+      at: number;
+    }
+  >;
+}
+
+interface WingsExecOptions {
+  cwd?: string;
+  /** 30 s by default, 5 min at most. */
+  timeoutMs?: number;
+  /** Gets each stdout and stderr line while the program runs. */
+  onOutput?: (line: string) => void;
+}
+
+interface Wings {
+  // Every `on*` call returns a function that removes the listener, for cleaning up in a React effect.
+  /** Every terminal pane, on every change. */
+  onPanes(listener: (panes: WingsPane[]) => void): () => void;
+  /**
+   * A badge action was clicked. Return a promise: the button spins until it settles (up to 5 min), and a thrown
+   * error shows in the card. What it resolves to is ignored.
+   */
+  onAction(listener: (action: { paneId: string; actionId: string }) => unknown): () => void;
+  /**
+   * Handles Claude's calls to a tool in `contributes.mcpTools`. Return a string or a JSON value; a thrown error
+   * is sent back as a failed call. `paneId` is the Wings pane Claude runs in, or `null`. Register it in `main`.
+   */
+  onTool(name: string, handler: (input: Record<string, unknown>, context: { paneId: string | null }) => unknown): void;
+  /** Runs a command from `permissions.exec`, like `git branch --show-current`. */
+  exec(program: string, args?: string[], options?: WingsExecOptions): Promise<{ code: number | null; stdout: string; stderr: string }>;
+  /**
+   * Needs `permissions.statusline`. What Claude Code last told its status line, once `wings statusline` is your
+   * `statusLine` command: usage limits and each session's context and cache, as Claude Code reports them.
+   */
+  statusline(): Promise<WingsStatusline>;
+  /** Claude Code transcript entries of types in `permissions.transcript`, oldest first. */
+  transcript(sessionId: string, types: string[], options?: { last?: number }): Promise<Record<string, unknown>[]>;
+  /**
+   * Each transcript entry Claude Code writes while it runs in a pane, for the types in `permissions.transcript`.
+   * Only entries written after the plugin started, or after the session started in the pane; `transcript` reads
+   * earlier ones. Entries over 256 KB are skipped.
+   */
+  onTranscript(listener: (event: WingsTranscriptEvent) => void): () => void;
+  /** Needs `"badges"` in `contributes.ui`. `null` removes it. */
+  setBadge(paneId: string, badge: WingsBadge | null): Promise<void>;
+  /**
+   * Needs `permissions.ports`. The local TCP ports the programs in your panes listen on, that `localhost`
+   * reaches. About 20 ms a call, so poll slowly.
+   */
+  ports(): Promise<{ paneId: string; pid: number; name: string; port: number; startedAt: number }[]>;
+  /** Opens an https URL, or an http one to localhost, 127.0.0.1 or [::1], that starts with a prefix in `permissions.openUrl`. */
+  openUrl(url: string): Promise<void>;
+  /**
+   * Needs `permissions.panes`. Opens a terminal in a new tab, or a split beside the focused pane, and resolves
+   * once the pane is in `onPanes`. `command`, like `"npm run dev"`, is typed into its shell and must start with
+   * an entry of `permissions.panes`. `cwd` must be inside one of your projects; without it the pane opens at the
+   * root of the project on screen.
+   */
+  openPane(options?: { command?: string; cwd?: string; placement?: "tab" | "right" | "down" }): Promise<{ paneId: string }>;
+  /** Needs `permissions.panes`. Shows an open pane and moves the keyboard to it. */
+  focusPane(paneId: string): Promise<void>;
+  /**
+   * After `exec` rejected with "<program> is not installed or not on PATH": Wings asks you, installs it in a new tab
+   * and restarts the plugin once it's there. Only `az`, `gh` and `glab`, and only ones `permissions.exec` names.
+   * Resolves true once the install started (or it's already installed), false if you cancelled.
+   */
+  installTool(program: "az" | "gh" | "glab"): Promise<boolean>;
+  /** Needs `permissions.notify`. A desktop notification, up to 3 a minute. The title is cut at 64 characters, the body at 256. */
+  notify(notification: { title: string; body?: string }): Promise<void>;
+  /** Needs `"diff"` in `contributes.ui`. Leave out `patch` to open it loading, then call `updateDiff`. */
+  openDiff(diff: { title: string; subtitle?: string; patch?: string; comments?: WingsComment[] }): Promise<{ id: string }>;
+  /** Updates a viewer opened with `openDiff`; ignored once it's closed. `{ comments }` alone keeps the patch, like after a reply. */
+  updateDiff(id: string, update: { patch: string; comments?: WingsComment[] } | { comments: WingsComment[] } | { error: string }): Promise<void>;
+  /**
+   * Needs `"diff"` in `contributes.ui`. A reply typed under a comment with `canReply` in the diff viewer. Post it,
+   * then add it with `updateDiff`. The reply box waits for the returned promise, and a thrown error shows under it
+   * with the text kept. One handler: a second call replaces the first.
+   */
+  onReply(handler: (reply: WingsReply) => unknown): void;
+  /**
+   * POSTs `fields` (string or whole-number values, up to 64 KB) as JSON to a `permissions.post` path, as you:
+   * `gh api`, `glab api` against `host`, or `az rest` for Azure DevOps. Wings builds the command itself.
+   */
+  post(
+    program: "gh" | "glab" | "az",
+    url: string,
+    fields: Record<string, string | number>,
+    options?: { host?: string },
+  ): Promise<{ code: number | null; stdout: string; stderr: string }>;
+  /**
+   * An HTTP request to a URL under `permissions.fetch`, made by Wings. `bearer` names a secret that Wings sends
+   * as `Authorization: Bearer <secret>`. Resolves for any status; redirects aren't followed.
+   */
+  fetch(
+    url: string,
+    init?: { method?: string; headers?: Record<string, string>; body?: string; bearer?: string },
+  ): Promise<{ status: number; contentType: string | null; body: string }>;
+  /** Secrets, like API tokens, in the system keychain. `fetch` can send them, but they can't be read back. */
+  secrets: {
+    set(name: string, value: string): Promise<void>;
+    delete(name: string): Promise<void>;
+    has(name: string): Promise<boolean>;
+  };
+  /**
+   * The plugin's own storage for settings and state, since `localStorage` throws in plugin pages. Values are
+   * JSON. Keys are 1 to 128 letters, digits and `- _ . : /`, and it holds 1 MB in all. Only this plugin sees it.
+   */
+  storage: {
+    /** The value, or `null` when the key isn't set. */
+    get(key: string): Promise<unknown>;
+    /** Refused if it would take the plugin's storage over 1 MB. */
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every key, sorted. */
+    keys(): Promise<string[]>;
+  };
+  /** Short text next to a sidebar's or view's title bar button, like a running timer. `null` clears it. */
+  setSidebarLabel(sidebarId: string, label: string | null, options?: { rows?: { label: string; value: string }[]; tone?: "warning" | "danger" }): Promise<void>;
+  /**
+   * Opens one of `contributes.sidebars` or `contributes.views` by id: in the right sidebar, in a modal over Wings,
+   * or in a window of its own. `as` must be in the view's `opens`, and defaults to the first. A window that's
+   * already open comes to the front. The page gets the same `wings` object wherever it opens.
+   */
+  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" }): Promise<void>;
+  /** Closes a sidebar or view wherever it's open. */
+  closeView(id: string): Promise<void>;
+  /** Sends a JSON value, up to 64 KB, to the plugin's other pages: its main script and open sidebars, modals and windows. */
+  broadcast(message: unknown): Promise<void>;
+  /** Gets what the plugin's other pages send with `broadcast`. */
+  onBroadcast(listener: (message: unknown) => void): () => void;
+}
+
+declare const wings: Wings;