create-deck-plugin 0.15.1

package/index.mjs

@@ -0,0 +1,77 @@
+#!/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));
+}
+
+const run = (cmd, args) => {
+  try { execFileSync(cmd, args, { cwd: dir, stdio: "inherit" }); return true; }
+  catch { return false; }
+};
+
+console.log(`\nInstalling deck-plugin-sdk…`);
+const npm = process.platform === "win32" ? "npm.cmd" : "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");

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "create-deck-plugin",
+  "version": "0.15.1",
+  "description": "Scaffold a Deck plugin.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "create-deck-plugin": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepack": "node prepack.mjs"
+  }
+}

package/template/README.md

@@ -0,0 +1,17 @@
+# __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.

package/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+# Copied in by the build from the SDK — not yours to edit, and not worth committing.
+shim/
+types/

package/template/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "__ID__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "deck-plugin build",
+    "dev": "deck-plugin dev",
+    "install-local": "deck-plugin install"
+  }
+}

package/template/plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "__ID__",
+  "name": "__NAME__",
+  "description": "One line on what this is for, shown under its name in Settings.",
+  "icon": "Sparkles",
+  "version": "0.1.0",
+  "minDeck": "0.15.0"
+}

package/template/src/plugin.tsx

@@ -0,0 +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>
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*"]
+}