deck-plugin-sdk 1.11.0 → 1.12.0

package/README.md

@@ -1,97 +1,97 @@
-# deck-plugin-sdk
-
-Build a plugin for Deck, outside Deck's own repository.
-
-```sh
-npm create deck-plugin my-thing
-cd my-thing
-npm run dev            # rebuild as you edit; each save shows in your test Deck
-npm run install-local  # when it is done: install it into your real Deck
-```
-
-Develop in a **test Deck**: a second Deck beside yours, with its own settings and data, started
-from Settings › Plugins › Open a test Deck (or `deck.exe --test`). `npm run dev` installs into it
-after every build and it reloads the plugin, so a save shows there within a few seconds, while your
-real Deck and its data are never touched.
-
-The project comes with an `AGENTS.md` (and a `CLAUDE.md` that points to it), so Claude Code,
-Codex or another agent started in the folder knows the commands, the API and the rules.
-
-## What a plugin is
-
-A folder with a `plugin.json` and a built `plugin.js`, read from
-`%APPDATA%\Deck\plugins\<id>\` when Deck starts. It becomes a tab, or a readout in the footer,
-or a panel, or commands in the palette — `docs/guide/api.md` in the Deck repository lists every
-slot a plugin can fill. One is enough.
-
-Your sources import `react`, `lucide-react` and `deck-plugin-sdk/*` as ordinary code does. At run
-time those resolve to **Deck's** copies, handed over on `window.__deck`. For React that is not
-an optimisation but a requirement: two Reacts in one tree break hooks.
-
-## Commands
-
-| | |
-|---|---|
-| `deck-plugin build` | bundle `src/` into `plugin.js` |
-| `deck-plugin dev` | rebuild whenever a source changes, and install each build into the test Deck |
-| `deck-plugin check` | validate `plugin.json` without building |
-| `deck-plugin install` | build once, then install into your real Deck |
-| `deck-plugin publish` | check everything Deck's registry checks, then tag, release on GitHub and submit it (`--dry-run`: only check); see [Publishing](../docs/guide/publishing.md) |
-
-`--target test` or `--target main` picks the other Deck for either command. The test Deck keeps
-its plugins in `%APPDATA%\Deck-Dev\plugins`, your real Deck in `%APPDATA%\Deck\plugins`.
-
-## What you can import
-
-```ts
-import { configRead, configWrite } from "deck-plugin-sdk/bridge";  // Deck's Tauri commands
-import { listen } from "deck-plugin-sdk/event";                     // Deck's event bus
-import { getSettings } from "deck-plugin-sdk/settings";             // Deck's settings store
-import { Field, GhostButton } from "deck-plugin-sdk/ui";            // Deck's form controls
-import { getLayout } from "deck-plugin-sdk/terminals";              // the terminal layout
-import { monaco } from "deck-plugin-sdk/monaco";                    // the editor
-```
-
-They come from the package, so the project holds only your own code. A plugin made with an
-older SDK imports `../shim/bridge.js` instead; the build still copies `shim/` and `types/` in
-for one of those, and switching its imports over makes both unnecessary.
-
-The types are generated from Deck's own source, so what your editor tells you is what Deck
-actually exposes rather than a hand-written approximation that has drifted.
-
-Any other npm package is `npm install` and import: the build bundles it into `plugin.js`, with the
-images, fonts and CSS it brings. Writing a plugin, in the Docs, says what cannot work that way.
-
-When the build needs more than that (a worker bundled into the plugin, a dependency's locales left
-out), export esbuild plugins from `deck-plugin.config.mjs` beside `plugin.json`:
-
-```js
-export const esbuildPlugins = [{ name: "my-step", setup(build) { /* ... */ } }];
-```
-
-## What a plugin cannot do
-
-Add native capability. Every Tauri command is compiled into Deck, so a plugin calls what already
-exists. Anything needing new Rust belongs in Deck itself.
-
-## What a plugin CAN do, which is worth saying plainly
-
-**Everything Deck can.** A plugin runs inside Deck with the whole bridge: every Tauri command,
-the config directory, the filesystem, the terminal, a Google access token if one is connected.
-There is no sandbox and no permission prompt.
-
-That is a deliberate position rather than an oversight — a plugin is code you chose to run, like
-a VS Code extension or a shell script. It is also why the plugin registry is curated rather than
-open: an entry exists there because it was reviewed, and installing a plugin from anywhere else
-is the same decision as running any other program.
-
-## Versions
-
-The SDK's major and minor track Deck's, so an SDK 0.15 builds plugins for Deck 0.15. Declare the
-oldest Deck you work with as `minDeck` in `plugin.json`; Deck refuses to load a plugin that
-needs a newer one, with a sentence rather than an error from inside your module.
-
-## Publishing
-
-A plugin is published by being listed in Deck's registry, which points at a release in your own
-repository. Until that is open to submissions, ask.
+# deck-plugin-sdk
+
+Build a plugin for Deck, outside Deck's own repository.
+
+```sh
+npm create deck-plugin my-thing
+cd my-thing
+npm run dev            # rebuild as you edit; each save shows in your test Deck
+npm run install-local  # when it is done: install it into your real Deck
+```
+
+Develop in a **test Deck**: a second Deck beside yours, with its own settings and data, started
+from Settings › Plugins › Open a test Deck (or `deck.exe --test`). `npm run dev` installs into it
+after every build and it reloads the plugin, so a save shows there within a few seconds, while your
+real Deck and its data are never touched.
+
+The project comes with an `AGENTS.md` (and a `CLAUDE.md` that points to it), so Claude Code,
+Codex or another agent started in the folder knows the commands, the API and the rules.
+
+## What a plugin is
+
+A folder with a `plugin.json` and a built `plugin.js`, read from
+`%APPDATA%\Deck\plugins\<id>\` when Deck starts. It becomes a tab, or a readout in the footer,
+or a panel, or commands in the palette — `docs/guide/api.md` in the Deck repository lists every
+slot a plugin can fill. One is enough.
+
+Your sources import `react`, `lucide-react` and `deck-plugin-sdk/*` as ordinary code does. At run
+time those resolve to **Deck's** copies, handed over on `window.__deck`. For React that is not
+an optimisation but a requirement: two Reacts in one tree break hooks.
+
+## Commands
+
+| | |
+|---|---|
+| `deck-plugin build` | bundle `src/` into `plugin.js` |
+| `deck-plugin dev` | rebuild whenever a source changes, and install each build into the test Deck |
+| `deck-plugin check` | validate `plugin.json` without building |
+| `deck-plugin install` | build once, then install into your real Deck |
+| `deck-plugin publish` | check everything Deck's registry checks, then tag, release on GitHub and submit it (`--dry-run`: only check); see [Publishing](../docs/guide/publishing.md) |
+
+`--target test` or `--target main` picks the other Deck for either command. The test Deck keeps
+its plugins in `%APPDATA%\Deck-Dev\plugins`, your real Deck in `%APPDATA%\Deck\plugins`.
+
+## What you can import
+
+```ts
+import { configRead, configWrite } from "deck-plugin-sdk/bridge";  // Deck's Tauri commands
+import { listen } from "deck-plugin-sdk/event";                     // Deck's event bus
+import { getSettings } from "deck-plugin-sdk/settings";             // Deck's settings store
+import { Field, GhostButton } from "deck-plugin-sdk/ui";            // Deck's form controls
+import { getLayout } from "deck-plugin-sdk/terminals";              // the terminal layout
+import { monaco } from "deck-plugin-sdk/monaco";                    // the editor
+```
+
+They come from the package, so the project holds only your own code. A plugin made with an
+older SDK imports `../shim/bridge.js` instead; the build still copies `shim/` and `types/` in
+for one of those, and switching its imports over makes both unnecessary.
+
+The types are generated from Deck's own source, so what your editor tells you is what Deck
+actually exposes rather than a hand-written approximation that has drifted.
+
+Any other npm package is `npm install` and import: the build bundles it into `plugin.js`, with the
+images, fonts and CSS it brings. Writing a plugin, in the Docs, says what cannot work that way.
+
+When the build needs more than that (a worker bundled into the plugin, a dependency's locales left
+out), export esbuild plugins from `deck-plugin.config.mjs` beside `plugin.json`:
+
+```js
+export const esbuildPlugins = [{ name: "my-step", setup(build) { /* ... */ } }];
+```
+
+## What a plugin cannot do
+
+Add native capability. Every Tauri command is compiled into Deck, so a plugin calls what already
+exists. Anything needing new Rust belongs in Deck itself.
+
+## What a plugin CAN do, which is worth saying plainly
+
+**Everything Deck can.** A plugin runs inside Deck with the whole bridge: every Tauri command,
+the config directory, the filesystem, the terminal, a Google access token if one is connected.
+There is no sandbox and no permission prompt.
+
+That is a deliberate position rather than an oversight — a plugin is code you chose to run, like
+a VS Code extension or a shell script. It is also why the plugin registry is curated rather than
+open: an entry exists there because it was reviewed, and installing a plugin from anywhere else
+is the same decision as running any other program.
+
+## Versions
+
+The SDK's major and minor track Deck's, so an SDK 0.15 builds plugins for Deck 0.15. Declare the
+oldest Deck you work with as `minDeck` in `plugin.json`; Deck refuses to load a plugin that
+needs a newer one, with a sentence rather than an error from inside your module.
+
+## Publishing
+
+A plugin is published by being listed in Deck's registry, which points at a release in your own
+repository. Until that is open to submissions, ask.

package/bin/deck-plugin.mjs

@@ -1,159 +1,159 @@
 #!/usr/bin/env node
-// The Deck plugin CLI.
-//
-//   deck-plugin build          bundle src/ into plugin.js
-//   deck-plugin dev            rebuild whenever a source changes, into the test Deck each time
-//   deck-plugin check          validate plugin.json without building
-//   deck-plugin install        build once and copy into your Deck
-//   deck-plugin publish        check, tag, release on GitHub, and submit to Deck's registry
-//                              (--dry-run: only check; see ../publish.mjs)
-//
-//   --target test|main         which Deck dev and install write to (defaults: dev -> test, install -> main)
-//
-// Run from a plugin's own directory.
-import { watch } from "node:fs";
-import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { buildPlugin } from "../build-plugin.mjs";
-import { publish } from "../publish.mjs";
-
-const argv = process.argv.slice(2);
-const at = argv.indexOf("--target");
-const targetFlag = at >= 0 ? argv[at + 1] : undefined;
-const cmd = argv.find((a, i) => !a.startsWith("-") && !(at >= 0 && i === at + 1)) ?? "build";
-const dir = process.cwd();
-
-const die = (msg) => { console.error(msg); process.exit(1); };
-
-/**
- * What Deck will refuse at install time, refused here instead.
- *
- * Every rule is one Deck's loader or install_from_registry applies — the id charset especially,
- * because the id becomes a config key and a path component. Finding out here costs a second;
- * finding out from a failed install costs a round trip.
- */
-function check() {
-  const p = join(dir, "plugin.json");
-  if (!existsSync(p)) die("no plugin.json here — is this a plugin directory?");
-
-  let manifest;
-  try { manifest = JSON.parse(readFileSync(p, "utf8")); }
-  catch (e) { die(`plugin.json is not valid JSON: ${e.message}`); }
-
-  const id = (manifest.id ?? "").trim();
-  if (!id) die("plugin.json has no id");
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(id)) {
-    die(`id "${id}" must be letters, digits and dashes, starting with a letter or digit`);
-  }
-  if (!existsSync(join(dir, "src", "plugin.tsx"))) {
-    die("no src/plugin.tsx — that is the entry point");
-  }
-
-  // Not fatal, but worth saying: the registry's plugin page renders a README, and a published
-  // plugin without one gets an empty page.
-  const warn = [];
-  if (!manifest.version) warn.push("no version — Settings shows one, and the registry orders by it");
-  if (!manifest.description) warn.push("no description — the row says only a name");
-  if (!existsSync(join(dir, "README.md"))) warn.push("no README.md — publishing needs one");
-
-  console.log(`${manifest.name ?? id} ${manifest.version ?? ""}`.trim());
-  for (const w of warn) console.log(`  note: ${w}`);
-  return manifest;
-}
-
-/**
- * The plugins folder of one of the two Decks on this machine.
- *
- * "test" is the test Deck (`deck.exe --test`, or Settings › Plugins › Open a test Deck), which keeps
- * its own folder, Deck-Dev, apart from your real data. `dev` always writes there, so a plugin you
- * are still writing never lands in your real Deck, even when the test Deck is closed. `install`
- * writes to your real Deck ("main"), for when the plugin is done.
- */
-function pluginsDir(defaultTarget) {
-  const appData = process.env.APPDATA;
-  if (!appData) die("APPDATA is not set — this command is for Windows, where Deck runs");
-  const target = targetFlag ?? defaultTarget;
-  if (target !== "test" && target !== "main") die(`--target is "test" or "main", not "${target}"`);
-  return { target, dir: join(appData, target === "test" ? "Deck-Dev" : "Deck", "plugins") };
-}
-
-/** Copy the built plugin into a Deck's plugins folder. Deck watches it and reloads the plugin. */
-function copyInto(manifest, defaultTarget) {
-  const { target, dir: plugins } = pluginsDir(defaultTarget);
-  const dest = join(plugins, manifest.id);
-  mkdirSync(dest, { recursive: true });
-  for (const f of ["plugin.json", "plugin.js", "mcp.js"]) {
-    if (existsSync(join(dir, f))) cpSync(join(dir, f), join(dest, f));
-  }
-  return { target, dest };
-}
-
-/** Whether the test Deck is running: it answers on its own port. */
-async function testDeckRunning() {
-  try { return (await fetch("http://127.0.0.1:8791/health", { signal: AbortSignal.timeout(800) })).ok; }
-  catch { return false; }
-}
-
-switch (cmd) {
-  case "check": {
-    check();
-    break;
-  }
-
-  case "build": {
-    const manifest = check();
-    await buildPlugin(dir);
-    console.log(`built ${manifest.id} -> plugin.js`);
-    break;
-  }
-
-  case "publish": {
-    const manifest = check();
-    await publish(dir, manifest, { dryRun: argv.includes("--dry-run"), buildPlugin });
-    break;
-  }
-
-  case "install": {
-    const manifest = check();
-    await buildPlugin(dir);
-    const { target, dest } = copyInto(manifest, "main");
-    console.log(`installed ${manifest.id} into your ${target === "test" ? "test " : ""}Deck -> ${dest}`);
-    console.log("Deck watches that folder, so it is loaded already — no restart.");
-    break;
-  }
-
-  case "dev": {
-    const manifest = check();
-    let building = false;
-    let again = false;
-    const once = async () => {
-      if (building) { again = true; return; }
-      building = true;
-      try {
-        await buildPlugin(dir);
-        // Into the test Deck after every build: it reloads the plugin when its folder changes, so
-        // a save shows there within a few seconds.
-        const { target, dest } = copyInto(manifest, "test");
-        console.log(`rebuilt at ${new Date().toLocaleTimeString()} -> ${target} Deck (${dest})`);
-      } catch (e) { console.error(e.message); }
-      building = false;
-      if (again) { again = false; void once(); }
-    };
-    if ((targetFlag ?? "test") === "test" && !(await testDeckRunning())) {
-      console.log("No test Deck is running, so you will not see changes yet. Start one from");
-      console.log("Settings › Plugins › Open a test Deck (or run deck.exe --test); it loads this plugin.");
-    }
-    await once();
-    // Debounced: an editor writing a file emits several events, and each would start a build.
-    let timer;
-    watch(join(dir, "src"), { recursive: true }, () => {
-      clearTimeout(timer);
-      timer = setTimeout(() => void once(), 120);
-    });
-    console.log("watching src/ — ctrl+c to stop");
-    break;
-  }
-
-  default:
-    die(`unknown command "${cmd}" — try build, dev, check or install`);
-}
+// The Deck plugin CLI.
+//
+//   deck-plugin build          bundle src/ into plugin.js
+//   deck-plugin dev            rebuild whenever a source changes, into the test Deck each time
+//   deck-plugin check          validate plugin.json without building
+//   deck-plugin install        build once and copy into your Deck
+//   deck-plugin publish        check, tag, release on GitHub, and submit to Deck's registry
+//                              (--dry-run: only check; see ../publish.mjs)
+//
+//   --target test|main         which Deck dev and install write to (defaults: dev -> test, install -> main)
+//
+// Run from a plugin's own directory.
+import { watch } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildPlugin } from "../build-plugin.mjs";
+import { publish } from "../publish.mjs";
+
+const argv = process.argv.slice(2);
+const at = argv.indexOf("--target");
+const targetFlag = at >= 0 ? argv[at + 1] : undefined;
+const cmd = argv.find((a, i) => !a.startsWith("-") && !(at >= 0 && i === at + 1)) ?? "build";
+const dir = process.cwd();
+
+const die = (msg) => { console.error(msg); process.exit(1); };
+
+/**
+ * What Deck will refuse at install time, refused here instead.
+ *
+ * Every rule is one Deck's loader or install_from_registry applies — the id charset especially,
+ * because the id becomes a config key and a path component. Finding out here costs a second;
+ * finding out from a failed install costs a round trip.
+ */
+function check() {
+  const p = join(dir, "plugin.json");
+  if (!existsSync(p)) die("no plugin.json here — is this a plugin directory?");
+
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(p, "utf8")); }
+  catch (e) { die(`plugin.json is not valid JSON: ${e.message}`); }
+
+  const id = (manifest.id ?? "").trim();
+  if (!id) die("plugin.json has no id");
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(id)) {
+    die(`id "${id}" must be letters, digits and dashes, starting with a letter or digit`);
+  }
+  if (!existsSync(join(dir, "src", "plugin.tsx"))) {
+    die("no src/plugin.tsx — that is the entry point");
+  }
+
+  // Not fatal, but worth saying: the registry's plugin page renders a README, and a published
+  // plugin without one gets an empty page.
+  const warn = [];
+  if (!manifest.version) warn.push("no version — Settings shows one, and the registry orders by it");
+  if (!manifest.description) warn.push("no description — the row says only a name");
+  if (!existsSync(join(dir, "README.md"))) warn.push("no README.md — publishing needs one");
+
+  console.log(`${manifest.name ?? id} ${manifest.version ?? ""}`.trim());
+  for (const w of warn) console.log(`  note: ${w}`);
+  return manifest;
+}
+
+/**
+ * The plugins folder of one of the two Decks on this machine.
+ *
+ * "test" is the test Deck (`deck.exe --test`, or Settings › Plugins › Open a test Deck), which keeps
+ * its own folder, Deck-Dev, apart from your real data. `dev` always writes there, so a plugin you
+ * are still writing never lands in your real Deck, even when the test Deck is closed. `install`
+ * writes to your real Deck ("main"), for when the plugin is done.
+ */
+function pluginsDir(defaultTarget) {
+  const appData = process.env.APPDATA;
+  if (!appData) die("APPDATA is not set — this command is for Windows, where Deck runs");
+  const target = targetFlag ?? defaultTarget;
+  if (target !== "test" && target !== "main") die(`--target is "test" or "main", not "${target}"`);
+  return { target, dir: join(appData, target === "test" ? "Deck-Dev" : "Deck", "plugins") };
+}
+
+/** Copy the built plugin into a Deck's plugins folder. Deck watches it and reloads the plugin. */
+function copyInto(manifest, defaultTarget) {
+  const { target, dir: plugins } = pluginsDir(defaultTarget);
+  const dest = join(plugins, manifest.id);
+  mkdirSync(dest, { recursive: true });
+  for (const f of ["plugin.json", "plugin.js", "mcp.js"]) {
+    if (existsSync(join(dir, f))) cpSync(join(dir, f), join(dest, f));
+  }
+  return { target, dest };
+}
+
+/** Whether the test Deck is running: it answers on its own port. */
+async function testDeckRunning() {
+  try { return (await fetch("http://127.0.0.1:8791/health", { signal: AbortSignal.timeout(800) })).ok; }
+  catch { return false; }
+}
+
+switch (cmd) {
+  case "check": {
+    check();
+    break;
+  }
+
+  case "build": {
+    const manifest = check();
+    await buildPlugin(dir);
+    console.log(`built ${manifest.id} -> plugin.js`);
+    break;
+  }
+
+  case "publish": {
+    const manifest = check();
+    await publish(dir, manifest, { dryRun: argv.includes("--dry-run"), buildPlugin });
+    break;
+  }
+
+  case "install": {
+    const manifest = check();
+    await buildPlugin(dir);
+    const { target, dest } = copyInto(manifest, "main");
+    console.log(`installed ${manifest.id} into your ${target === "test" ? "test " : ""}Deck -> ${dest}`);
+    console.log("Deck watches that folder, so it is loaded already — no restart.");
+    break;
+  }
+
+  case "dev": {
+    const manifest = check();
+    let building = false;
+    let again = false;
+    const once = async () => {
+      if (building) { again = true; return; }
+      building = true;
+      try {
+        await buildPlugin(dir);
+        // Into the test Deck after every build: it reloads the plugin when its folder changes, so
+        // a save shows there within a few seconds.
+        const { target, dest } = copyInto(manifest, "test");
+        console.log(`rebuilt at ${new Date().toLocaleTimeString()} -> ${target} Deck (${dest})`);
+      } catch (e) { console.error(e.message); }
+      building = false;
+      if (again) { again = false; void once(); }
+    };
+    if ((targetFlag ?? "test") === "test" && !(await testDeckRunning())) {
+      console.log("No test Deck is running, so you will not see changes yet. Start one from");
+      console.log("Settings › Plugins › Open a test Deck (or run deck.exe --test); it loads this plugin.");
+    }
+    await once();
+    // Debounced: an editor writing a file emits several events, and each would start a build.
+    let timer;
+    watch(join(dir, "src"), { recursive: true }, () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => void once(), 120);
+    });
+    console.log("watching src/ — ctrl+c to stop");
+    break;
+  }
+
+  default:
+    die(`unknown command "${cmd}" — try build, dev, check or install`);
+}