create-deck-plugin 1.4.0 → 1.5.0

package/id.mjs

@@ -0,0 +1,8 @@
+// A plugin's id from the name someone typed. The id is a config key and a path component in Deck,
+// so it is letters, digits and dashes, starting with a letter or digit; "" when nothing usable is
+// left. Deck's "Create a plugin" makes the same id (src/core/pluginid.ts), and
+// src/core/pluginid.check.mjs holds the two to each other.
+export const pluginId = (raw) => {
+  const id = raw.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return /^[a-z0-9]/.test(id) ? id : "";
+};

package/index.mjs

@@ -1,102 +1,110 @@
-#!/usr/bin/env node
-// Scaffold a Deck plugin.
-//
-//   npm create deck-plugin my-thing
-//
-// Writes a folder that already builds, already has a git repository, and already knows how to
-// install itself into Deck. The real work is in deck-plugin-sdk, which this installs — a
-// scaffold on its own would freeze the shim and the types at the moment of creation, which is
-// the thing that rots.
-import { execFileSync } from "node:child_process";
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const here = dirname(fileURLToPath(import.meta.url));
-
-const raw = process.argv[2];
-if (!raw) {
-  console.error("usage: npm create deck-plugin <name>");
-  process.exit(1);
-}
-
-// The id is a config key and a path component in Deck, so it is checked here rather than at
-// install time. Same rule the loader applies.
-const id = raw.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
-if (!id || !/^[a-z0-9]/.test(id)) {
-  console.error(`"${raw}" does not reduce to a usable id (letters, digits and dashes)`);
-  process.exit(1);
-}
-
-const dir = resolve(process.cwd(), id);
-if (existsSync(dir) && readdirSync(dir).length) {
-  console.error(`${dir} already exists and is not empty`);
-  process.exit(1);
-}
-
-const name = id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
-const component = name.replace(/[^A-Za-z0-9]/g, "") || "Plugin";
-
-// The template is the SDK's — one copy, so the scaffold and the thing it installs cannot
-// disagree. Resolved through node rather than by relative path, because once published these
-// are two packages rather than two folders.
-const sdkTemplate = existsSync(join(here, "template"))
-  ? join(here, "template")                       // published: copied in at pack time
-  : join(here, "..", "sdk", "template");         // in the repo: the SDK's own
-cpSync(sdkTemplate, dir, { recursive: true });
-// npm refuses to publish a file called .gitignore, so the template ships it renamed.
-if (existsSync(join(dir, "gitignore"))) renameSync(join(dir, "gitignore"), join(dir, ".gitignore"));
-
-for (const rel of ["plugin.json", "package.json", "src/plugin.tsx", "README.md"]) {
-  const p = join(dir, rel);
-  if (!existsSync(p)) continue;
-  writeFileSync(p, readFileSync(p, "utf8")
-    .replaceAll("__ID__", id)
-    .replaceAll("__NAME__", name)
-    .replaceAll("__COMPONENT__", component));
-}
-
-/**
- * Run a command in the new plugin's directory.
- *
- * npm needs care on Windows. `npm` there is npm.cmd, and recent Node refuses to execFile a .cmd
- * at all — EINVAL, a deliberate fix for an argument-injection class of bug — so the scaffolder
- * silently installed nothing for every Windows user, which is every Deck user. Running it
- * through a shell works but is itself deprecated for the same reason, so npm's own JS entry
- * point is located and run with node instead: no shell, no .cmd, nothing to escape.
- */
-function npmCli() {
-  // npm sits beside node in the same installation, as lib/node_modules/npm/bin/npm-cli.js.
-  const guess = join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
-  if (existsSync(guess)) return guess;
-  const unix = join(dirname(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
-  return existsSync(unix) ? unix : null;
-}
-
-const run = (cmd, args) => {
-  try {
-    if (cmd === "npm") {
-      const cli = npmCli();
-      if (!cli) return false;
-      execFileSync(process.execPath, [cli, ...args], { cwd: dir, stdio: "inherit" });
-    } else {
-      execFileSync(cmd, args, { cwd: dir, stdio: "inherit" });
-    }
-    return true;
-  } catch { return false; }
-};
-
-console.log(`\nInstalling deck-plugin-sdk…`);
-const npm = "npm";
-const installed = run(npm, ["install", "--save-dev", "deck-plugin-sdk",
-  "react", "lucide-react", "@types/react"]);
-
-// A git repository from the start, because a plugin's home is its own repository — that is how
-// it gets published, and how it gets listed in the registry.
-run("git", ["init", "-q", "-b", "main"]);
-
-console.log(`\n${name} is in ${id}/\n`);
-console.log("  cd " + id);
-if (!installed) console.log("  npm install          # this failed; run it yourself");
-console.log("  npm run dev          # build, and rebuild as you edit");
-console.log("  npm run install-local  # copy it into Deck and load it\n");
+#!/usr/bin/env node
+// Scaffold a Deck plugin.
+//
+//   npm create deck-plugin my-thing
+//
+// Writes a folder that already builds, already has a git repository, and already knows how to
+// install itself into Deck. The real work is in deck-plugin-sdk, which this installs — a
+// scaffold on its own would freeze the shim and the types at the moment of creation, which is
+// the thing that rots.
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pluginId } from "./id.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const raw = process.argv[2];
+if (!raw) {
+  console.error("usage: npm create deck-plugin <name>");
+  process.exit(1);
+}
+
+// The id is a config key and a path component in Deck, so it is checked here rather than at
+// install time. Same rule the loader applies.
+const id = pluginId(raw);
+if (!id) {
+  console.error(`"${raw}" does not reduce to a usable id (letters, digits and dashes)`);
+  process.exit(1);
+}
+
+const dir = resolve(process.cwd(), id);
+if (existsSync(dir) && readdirSync(dir).length) {
+  console.error(`${dir} already exists and is not empty`);
+  process.exit(1);
+}
+
+const name = id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+const component = name.replace(/[^A-Za-z0-9]/g, "") || "Plugin";
+
+// The template is the SDK's — one copy, so the scaffold and the thing it installs cannot
+// disagree. Resolved through node rather than by relative path, because once published these
+// are two packages rather than two folders.
+// The repo's own copy first: the one beside this file is what the last `npm publish` copied in,
+// and is stale from the next change to sdk/template on.
+const repoSdk = join(here, "..", "sdk");
+const inRepo = existsSync(join(repoSdk, "template"));
+const sdkTemplate = inRepo
+  ? join(repoSdk, "template")                    // in the repo: the SDK's own
+  : join(here, "template");                      // published: copied in at pack time
+cpSync(sdkTemplate, dir, { recursive: true });
+// npm refuses to publish a file called .gitignore, so the template ships it renamed.
+if (existsSync(join(dir, "gitignore"))) renameSync(join(dir, "gitignore"), join(dir, ".gitignore"));
+
+for (const rel of ["plugin.json", "package.json", "src/plugin.tsx", "README.md", "AGENTS.md"]) {
+  const p = join(dir, rel);
+  if (!existsSync(p)) continue;
+  writeFileSync(p, readFileSync(p, "utf8")
+    .replaceAll("__ID__", id)
+    .replaceAll("__NAME__", name)
+    .replaceAll("__COMPONENT__", component));
+}
+
+/**
+ * Run a command in the new plugin's directory.
+ *
+ * npm needs care on Windows. `npm` there is npm.cmd, and recent Node refuses to execFile a .cmd
+ * at all — EINVAL, a deliberate fix for an argument-injection class of bug — so the scaffolder
+ * silently installed nothing for every Windows user, which is every Deck user. Running it
+ * through a shell works but is itself deprecated for the same reason, so npm's own JS entry
+ * point is located and run with node instead: no shell, no .cmd, nothing to escape.
+ */
+function npmCli() {
+  // npm sits beside node in the same installation, as lib/node_modules/npm/bin/npm-cli.js.
+  const guess = join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (existsSync(guess)) return guess;
+  const unix = join(dirname(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+  return existsSync(unix) ? unix : null;
+}
+
+const run = (cmd, args) => {
+  try {
+    if (cmd === "npm") {
+      const cli = npmCli();
+      if (!cli) return false;
+      execFileSync(process.execPath, [cli, ...args], { cwd: dir, stdio: "inherit" });
+    } else {
+      execFileSync(cmd, args, { cwd: dir, stdio: "inherit" });
+    }
+    return true;
+  } catch { return false; }
+};
+
+console.log(`\nInstalling deck-plugin-sdk…`);
+const npm = "npm";
+// Run from the repo, the SDK beside it: the template is the repo's, and the published SDK may not
+// have caught up with it yet.
+const installed = run(npm, ["install", "--save-dev", inRepo ? repoSdk : "deck-plugin-sdk",
+  "react", "lucide-react", "@types/react"]);
+
+// A git repository from the start, because a plugin's home is its own repository — that is how
+// it gets published, and how it gets listed in the registry.
+run("git", ["init", "-q", "-b", "main"]);
+
+console.log(`\n${name} is in ${id}/\n`);
+console.log("  cd " + id);
+if (!installed) console.log("  npm install          # this failed; run it yourself");
+console.log("  npm run dev            # rebuild as you edit; each save shows in your test Deck");
+console.log("  npm run install-local  # when it is done: install it into your real Deck");
+console.log("\nStart a test Deck from Deck's Settings › Plugins › Open a test Deck.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deck-plugin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Scaffold a Deck plugin.",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,7 @@
   },
   "files": [
     "index.mjs",
+    "id.mjs",
     "template"
   ],
   "engines": {

package/template/AGENTS.md

@@ -0,0 +1,77 @@
+# __NAME__: notes for AI agents
+
+This is a plugin for Deck, a Windows app (Tauri, React 19). It is
+bundled into one `plugin.js` that Deck imports at run time, inside Deck's own window. Read this
+before changing anything.
+
+## Commands
+
+```sh
+npm run dev            # build on every save and install into the test Deck, which reloads it
+npm run build          # build once into plugin.js
+npm run install-local  # build and install into the user's real Deck
+npx deck-plugin check  # validate plugin.json
+```
+
+The test Deck is a second Deck with its own data, started with
+`& "$env:LOCALAPPDATA\Deck\deck.exe" --test` (PowerShell). Develop against it, never the real
+Deck: `npm run dev` only ever writes there. Run `npm run install-local` only when the user asks
+for the plugin to be installed for real. Its log is `%APPDATA%\Deck-Dev\logs\deck-<date>.log`;
+the plugin's `console.warn` and `console.error` lines land there.
+
+## Files
+
+- `plugin.json`: `id` (letters, digits, dashes; it is a folder name and a config key), `name`,
+  `description`, `icon` (a lucide icon name), `color`, `version`, `minDeck`.
+- `src/plugin.tsx`: the entry. Its exports are what Deck uses (below).
+- `src/mcp.ts`, if present: tools for Deck's MCP server, built to `mcp.js`.
+- `plugin.js` (and `mcp.js`): the build's output, gitignored. Never edit them.
+- **The API is `node_modules/deck-plugin-sdk/types/core/bridge.d.ts`**: every function Deck
+  exposes, with its documentation, generated from Deck's own source. Read it rather than guessing
+  a name. A plugin imports it as `deck-plugin-sdk/bridge`.
+
+## What the plugin can export
+
+`default` (a tab), `PaneView` (a view that can sit in a split pane, given `{ cwd, runInTerminal }`),
+`Status` (a footer readout), `Panel` (a footer drawer tab), `commands` (palette entries),
+`Settings` (a settings panel), `keybindings`, `Provider` (wraps the app, for state that must
+survive the tab closing), `Bar`, and `dispose`. At least one; none is required on its own.
+
+## Rules that are easy to break
+
+- **Import Deck's copies.** `react`, `lucide-react` and the `deck-plugin-sdk/*` modules resolve to
+  Deck's own at run time. Never add a second React, or a UI library that bundles one: two
+  Reacts in one tree break hooks.
+- **No native code.** A plugin can only call what Deck already exposes (`deck-plugin-sdk/bridge`).
+  To run a program, use `exec` or `procStream`; to read and write files, the `fs*` calls.
+- **Opening files**: `export const opens = [".ext"]` with a `PaneView` makes Deck open those files
+  in the plugin, each as its own tab, given as the `file` prop. Open one yourself with `openFile`
+  from `deck-plugin-sdk/terminals`; save with `fsWriteBytes`.
+- **npm packages are fine** (`npm install` and import): the build bundles them, their images,
+  fonts and CSS included, into `plugin.js`. `?raw` on an import gives a file's text (a worker).
+  A build step of your own (an esbuild plugin) goes in `deck-plugin.config.mjs` as
+  `export const esbuildPlugins = [...]`. Not a package that needs Node (`fs`, `child_process`),
+  one that bundles its own React, or one that starts a Web Worker from a file.
+- **Storage goes through `configRead` / `configWrite`** with plain names (`"settings"`, or
+  `"notes.md"` for a plain file). Deck keeps them in the plugin's own folder. A name never
+  written reads as `""`. Do not write a config whose text has not changed: every write wakes
+  every config listener in Deck.
+- **`listen("config-changed", ...)` gets a `string[]` of names**: act only when it includes one
+  of yours.
+- **Deck reloads the plugin on every rebuild.** Anything module scope starts (a `setInterval`,
+  a `listen`, a window listener) must be stopped in an exported `dispose()`, or the old copy keeps
+  running beside the new one. Anything a component creates outside the DOM (an `Audio`, a timer,
+  a socket) is stopped in its effect's cleanup.
+- **A poll stops when nobody can see it**: skip ticks while `document.hidden`, and do not run it
+  while the readout it feeds is switched off.
+- **Styling uses Deck's stylesheet.** Tailwind classes Deck does not already use do not exist.
+  Use Deck's semantic tokens (`text-text-primary`, `text-text-secondary`, `text-text-muted`,
+  `bg-elev`, `border-subtle`, `var(--accent)`) and Deck's components from `deck-plugin-sdk/ui`, so
+  the plugin follows the user's theme.
+- **No error is dropped silently.** A failed save, load or action logs
+  `console.warn("[__ID__] what failed", e)`.
+
+## More
+
+The full guide (exports, storage, testing, publishing) is in Deck's **Docs** tab, which also has
+the API reference for the Deck that is installed.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -1,17 +1,20 @@
-# __NAME__
-
-A plugin for [Deck](https://deck.hasan-zarif.com).
-
-## Developing
-
-```sh
-npm run dev            # build, and rebuild as you edit
-npm run install-local  # copy it into Deck, which loads it without a restart
-```
-
-`src/plugin.tsx` is the entry point; its default export is the tab.
-
-## What it does
-
-Say what this plugin is for. This file is what the registry shows on its page, so it is worth
-writing for somebody deciding whether to install it rather than for yourself.
+# __NAME__
+
+A plugin for Deck.
+
+## Developing
+
+```sh
+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
+```
+
+Start a test Deck from Settings › Plugins › Open a test Deck: it keeps its own settings and data,
+so trying the plugin never touches your real Deck.
+
+`src/plugin.tsx` is the entry point; its default export is the tab.
+
+## What it does
+
+Say what this plugin is for. This file is what the registry shows on its page, so it is worth
+writing for somebody deciding whether to install it rather than for yourself.

package/template/gitignore

@@ -1,4 +1,4 @@
-node_modules/
-# Copied in by the build from the SDK — not yours to edit, and not worth committing.
-shim/
-types/
+node_modules/
+# What the build writes. A release carries plugin.json and these; the repository holds the source.
+plugin.js
+mcp.js

package/template/plugin.json

@@ -1,9 +1,9 @@
-{
-  "id": "__ID__",
-  "name": "__NAME__",
-  "description": "One line on what this is for, shown under its name in Settings.",
-  "icon": "Sparkles",
-  "color": "#a78bfa",
-  "version": "0.1.0",
-  "minDeck": "0.17.0"
-}
+{
+  "id": "__ID__",
+  "name": "__NAME__",
+  "description": "One line on what this is for, shown under its name in Settings.",
+  "icon": "Sparkles",
+  "color": "#a78bfa",
+  "version": "0.1.0",
+  "minDeck": "1.5.0"
+}

package/template/src/assets.d.ts

@@ -0,0 +1,16 @@
+// What importing a file that is not code gives you, so the editor knows. The build inlines each
+// into plugin.js: an image or font as a data: URL, a stylesheet as its text (or, imported with
+// nothing bound — `import "x.css"` — applied to the page), a .wasm file as its bytes.
+declare module "*.png" { const url: string; export default url; }
+declare module "*.jpg" { const url: string; export default url; }
+declare module "*.jpeg" { const url: string; export default url; }
+declare module "*.gif" { const url: string; export default url; }
+declare module "*.webp" { const url: string; export default url; }
+declare module "*.svg" { const url: string; export default url; }
+declare module "*.woff2" { const url: string; export default url; }
+declare module "*.css" { const text: string; export default text; }
+declare module "*.wasm" { const bytes: Uint8Array; export default bytes; }
+// `import text from "some/file?raw"`: any file, as its text.
+declare module "*?raw" { const text: string; export default text; }
+// `import data from "some/file?base64"`: any file's bytes, as a base64 string.
+declare module "*?base64" { const base64: string; export default base64; }

package/template/src/plugin.tsx

@@ -1,65 +1,65 @@
-// __NAME__ — a Deck plugin.
-//
-// The default export is the tab. A plugin can export more than that — a footer readout, a
-// settings panel, palette commands, a pane view — and `plugins/API.md` in the Deck repository
-// lists every slot. One export is enough to start.
-import { useState } from "react";
-import { Sparkles } from "lucide-react";
-import { configRead, configWrite } from "../shim/bridge.js";
-
-/** Where this plugin's own settings live. The `plugin-` prefix keeps them on this machine. */
-const CONFIG = "plugin-__ID__";
-
-export default function __COMPONENT__() {
-  const [note, setNote] = useState("");
-  const [saved, setSaved] = useState(false);
-
-  // Deck's config store, the same one its own modules use. Reading a key that has never been
-  // written resolves to an empty string rather than throwing.
-  const load = async () => {
-    const raw = await configRead(CONFIG).catch(() => "");
-    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
-  };
-
-  const save = async () => {
-    await configWrite(CONFIG, JSON.stringify({ note }));
-    setSaved(true);
-    setTimeout(() => setSaved(false), 1500);
-  };
-
-  return (
-    <div className="flex h-full flex-col gap-4 p-6">
-      <header className="flex items-center gap-3">
-        <Sparkles size={18} style={{ color: "var(--accent)" }} />
-        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
-      </header>
-
-      <p className="max-w-[60ch] text-sm text-text-secondary">
-        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
-        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
-        and Deck reloads the plugin as you save.
-      </p>
-
-      <div className="flex max-w-md items-center gap-2">
-        <input
-          value={note}
-          onChange={(e) => setNote(e.target.value)}
-          onFocus={() => void load()}
-          placeholder="Type something, then save it"
-          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
-        />
-        <button
-          onClick={() => void save()}
-          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
-        >
-          {saved ? "Saved" : "Save"}
-        </button>
-      </div>
-
-      <p className="text-xs text-text-muted">
-        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
-        machine.
-      </p>
-    </div>
-  );
-}
+// __NAME__ — a Deck plugin.
+//
+// The default export is the tab. A plugin can export more than that — a footer readout, a
+// settings panel, palette commands, a pane view — and `docs/guide/api.md` in the Deck repository
+// lists every slot. One export is enough to start.
+import { useState } from "react";
+import { Sparkles } from "lucide-react";
+import { configRead, configWrite } from "deck-plugin-sdk/bridge";
+
+/** This plugin's own settings. Deck keeps a plugin's configs in its own folder, so a plain name. */
+const CONFIG = "settings";
+
+export default function __COMPONENT__() {
+  const [note, setNote] = useState("");
+  const [saved, setSaved] = useState(false);
+
+  // Deck's config store, the same one its own modules use. Reading a key that has never been
+  // written resolves to an empty string rather than throwing.
+  const load = async () => {
+    const raw = await configRead(CONFIG).catch(() => "");
+    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
+  };
+
+  const save = async () => {
+    await configWrite(CONFIG, JSON.stringify({ note }));
+    setSaved(true);
+    setTimeout(() => setSaved(false), 1500);
+  };
+
+  return (
+    <div className="flex h-full flex-col gap-4 p-6">
+      <header className="flex items-center gap-3">
+        <Sparkles size={18} style={{ color: "var(--accent)" }} />
+        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
+      </header>
+
+      <p className="max-w-[60ch] text-sm text-text-secondary">
+        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
+        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
+        and Deck reloads the plugin as you save.
+      </p>
+
+      <div className="flex max-w-md items-center gap-2">
+        <input
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+          onFocus={() => void load()}
+          placeholder="Type something, then save it"
+          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
+        />
+        <button
+          onClick={() => void save()}
+          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
+        >
+          {saved ? "Saved" : "Save"}
+        </button>
+      </div>
+
+      <p className="text-xs text-text-muted">
+        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
+        machine.
+      </p>
+    </div>
+  );
+}