deck-plugin-sdk 1.14.0 → 1.15.0

package/bin/deck-plugin.mjs

@@ -13,6 +13,7 @@
 // Run from a plugin's own directory.
 import { watch } from "node:fs";
 import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildPlugin } from "../build-plugin.mjs";
 import { publish } from "../publish.mjs";
@@ -70,15 +71,27 @@ function check() {
  * 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") };
+  return { target, dir: join(configRoot(), target === "test" ? "Deck-Dev" : "Deck", "plugins") };
+}
+
+/** Where Deck keeps its folder, as its Rust side finds it: %APPDATA% on Windows, $XDG_CONFIG_HOME
+ *  or ~/.config on Linux, ~/Library/Application Support on macOS. */
+function configRoot() {
+  if (process.platform === "win32") return process.env.APPDATA || die("APPDATA is not set");
+  if (process.platform === "darwin") return join(homedir(), "Library", "Application Support");
+  return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
 }
 
 /** Copy the built plugin into a Deck's plugins folder. Deck watches it and reloads the plugin. */
 function copyInto(manifest, defaultTarget) {
+  // A plugin that lists the systems it runs on is not put into a Deck on any other, which would not
+  // load it anyway.
+  const here = { win32: "windows", darwin: "mac" }[process.platform] ?? "linux";
+  if (Array.isArray(manifest.platforms) && manifest.platforms.length && !manifest.platforms.includes(here)) {
+    die(`${manifest.id} runs on ${manifest.platforms.join(", ")} only (its plugin.json "platforms"), and this is ${here}`);
+  }
   const { target, dir: plugins } = pluginsDir(defaultTarget);
   const dest = join(plugins, manifest.id);
   mkdirSync(dest, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-plugin-sdk",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Build a plugin for Deck, outside the Deck repository.",
   "type": "module",
   "license": "MIT",

package/permissions.json

@@ -231,6 +231,7 @@
     "fsHomeDir",
     "getAutostart",
     "isFullscreen",
+    "isWindows",
     "languagesDir",
     "launchUrls",
     "mediaSetNowPlaying",
@@ -238,6 +239,7 @@
     "memUsage",
     "notifyOs",
     "openExternal",
+    "pathKey",
     "pickAnyFile",
     "pickExe",
     "pickFile",
@@ -245,8 +247,10 @@
     "pickImage",
     "pickSavePath",
     "pickScript",
+    "platform",
     "pluginsDir",
     "revealInFolder",
+    "samePath",
     "startupMarks",
     "toggleFullscreen"
   ]

package/publish.mjs

@@ -18,7 +18,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkAssets, checkIcon, checkId, checkLockfile, checkManifest, checkPermissions, fileFacts, ICON_FILE, points } from "./validate.mjs";
+import { checkAssets, checkIcon, checkId, checkLockfile, checkManifest, checkPermissions, checkPortable, fileFacts, ICON_FILE, points } from "./validate.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const REGISTRY = "deck-desktop/deck-registry";
@@ -83,6 +83,7 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
   const perms = checkPermissions(manifest.permissions, readFileSync(join(dir, "plugin.js"), "utf8"), table, manifest.id);
   errors.push(...perms.errors);
   notes.push(...perms.notes);
+  notes.push(...checkPortable(manifest, readFileSync(join(dir, "plugin.js"), "utf8")));
   if (errors.length) {
     for (const e of errors) console.error(`  ✗ ${e}`);
     process.exit(1);

package/shim/bridge.js

@@ -161,6 +161,7 @@ export const installAgentMcp = (...a) => b().installAgentMcp(...a);
 export const installAgentSkills = (...a) => b().installAgentSkills(...a);
 export const installFromRegistry = (...a) => b().installFromRegistry(...a);
 export const isFullscreen = (...a) => b().isFullscreen(...a);
+export const isWindows = (...a) => b().isWindows(...a);
 export const languagesDir = (...a) => b().languagesDir(...a);
 export const launchFiles = (...a) => b().launchFiles(...a);
 export const launchUrls = (...a) => b().launchUrls(...a);
@@ -176,6 +177,7 @@ export const notifyOs = (...a) => b().notifyOs(...a);
 export const openExternal = (...a) => b().openExternal(...a);
 export const openFile = (...a) => b().openFile(...a);
 export const openTestDeck = (...a) => b().openTestDeck(...a);
+export const pathKey = (...a) => b().pathKey(...a);
 export const pickAnyFile = (...a) => b().pickAnyFile(...a);
 export const pickExe = (...a) => b().pickExe(...a);
 export const pickFile = (...a) => b().pickFile(...a);
@@ -183,6 +185,7 @@ export const pickFolder = (...a) => b().pickFolder(...a);
 export const pickImage = (...a) => b().pickImage(...a);
 export const pickSavePath = (...a) => b().pickSavePath(...a);
 export const pickScript = (...a) => b().pickScript(...a);
+export const platform = (...a) => b().platform(...a);
 export const pluginsDir = (...a) => b().pluginsDir(...a);
 export const procKill = (...a) => b().procKill(...a);
 export const procStream = (...a) => b().procStream(...a);
@@ -198,6 +201,7 @@ export const removeLanguage = (...a) => b().removeLanguage(...a);
 export const restartApp = (...a) => b().restartApp(...a);
 export const revealInFolder = (...a) => b().revealInFolder(...a);
 export const runScriptNow = (...a) => b().runScriptNow(...a);
+export const samePath = (...a) => b().samePath(...a);
 export const sessionList = (...a) => b().sessionList(...a);
 export const setAutostart = (...a) => b().setAutostart(...a);
 export const setDebugTargets = (...a) => b().setDebugTargets(...a);

package/template/plugin.json

@@ -5,6 +5,6 @@
   "icon": "Sparkles",
   "color": "#a78bfa",
   "version": "0.1.0",
-  "minDeck": "1.14.0",
+  "minDeck": "1.15.0",
   "permissions": []
 }

package/types/core/app/platform.d.ts

@@ -0,0 +1,14 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export type Platform = "windows" | "linux" | "mac";
+/** Which system Deck runs on. A function, as everything plugins reach through the bridge is. */
+export declare const platform: () => Platform;
+export declare const isWindows: () => boolean;
+/** Whether two paths name the same file: without regard to case on Windows, whose file system
+ *  ignores it, and exactly elsewhere, where `Readme.md` and `README.md` are two files. */
+export declare function samePath(a: string, b: string): boolean;
+/** A path as a key that `samePath` would match: lowercased on Windows only. */
+export declare function pathKey(p: string): string;
+/** The system's name, for words shown to the user. */
+export declare const osName: () => string;
+/** The menu item that shows a file in the system's file manager. */
+export declare const revealLabel: () => string;

package/types/core/bridge.d.ts

@@ -672,6 +672,11 @@ export interface TrackMeta {
 }
 export declare const readTrackMeta: (paths: string[]) => Promise<TrackMeta[]>;
 export { convertFileSrc } from "@tauri-apps/api/core";
+export { platform } from "./app/platform";
+export { isWindows } from "./app/platform";
+export { samePath } from "./app/platform";
+export { pathKey } from "./app/platform";
+export type { Platform } from "./app/platform";
 /** Start a sign-in. Returns the consent URL to open in the browser. */
 export declare const googleSignIn: () => Promise<string>;
 /** A valid access token, refreshed if needed. Rejects when not connected. */

package/types/core/browser/bookmarksources.d.ts

@@ -0,0 +1,9 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** A Chromium browser's bookmarks on this machine, one per profile that has any. */
+export interface BookmarkSource {
+    browser: string;
+    profile: string;
+    path: string;
+}
+/** Every profile of Chrome, Edge and Brave with a Bookmarks file. A browser not installed is no error. */
+export declare function findBookmarkSources(): Promise<BookmarkSource[]>;

package/types/core/browser/browser.d.ts

@@ -203,14 +203,8 @@ export declare function forgetDownload(key: string): void;
 export declare function clearDownloads(): void;
 export declare const browserBookmarks: () => Bookmarks;
 export declare function setBookmarks(next: Bookmarks): void;
-/** A Chromium browser's bookmarks on this machine, one per profile that has any. */
-export interface BookmarkSource {
-    browser: string;
-    profile: string;
-    path: string;
-}
-/** Every profile of Chrome, Edge and Brave with a Bookmarks file. A browser not installed is no error. */
-export declare function findBookmarkSources(): Promise<BookmarkSource[]>;
+import type { BookmarkSource } from "./bookmarksources";
+export { findBookmarkSources, type BookmarkSource } from "./bookmarksources";
 /** Import one source's bookmarks as a "From Chrome" folder in each root. Returns how many pages. */
 export declare function importBookmarks(src: BookmarkSource): Promise<number>;
 /** Every bookmark to a bookmarks HTML file, which any browser imports, and Deck too. How many pages. */

package/types/core/keys/keys.d.ts

@@ -89,10 +89,4 @@ export declare function toMonaco(chord: string, mods: {
     Shift: number;
     WinCtrl: number;
 }, codes: Record<string, number>): number | null;
-/**
- * Deck's built-in bindings.
- *
- * Plugin bindings are not here — they arrive at load time through the `keybindings` export and
- * are concatenated on, so a disabled plugin's chords leave the table with it.
- */
 export declare const DEFAULT_BINDINGS: readonly KeyBinding[];

package/types/core/workspaces/windows.d.ts

@@ -32,7 +32,7 @@ export declare function activeElement(): Element | null;
 /** Run `fn` for every Deck window, now and as floats open; what it returns runs when that window goes, or on the returned unsubscribe. */
 export declare function onEachWindow(fn: Hook): () => void;
 /** A floating window opened (floatwin.ts), its label known: every hook runs for it. */
-export declare function addWindow(win: Window): void;
+export declare function addWindow(win: Window, label?: string): void;
 /** A floating window is going: what each hook installed in it is undone. */
 export declare function removeWindow(win: Window): void;
 /**

package/validate.mjs

@@ -44,6 +44,10 @@ export function checkManifest(m) {
   if (typeof m.version !== "string" || !SEMVER.test(m.version)) errors.push("`version` must be a version, such as \"1.0.0\"");
   if (typeof m.minDeck !== "string" || !SEMVER.test(m.minDeck)) errors.push("`minDeck` must say which Deck it needs, such as \"1.8.0\"");
   if (m.color !== undefined && !/^#[0-9a-f]{6}$/i.test(m.color)) errors.push("`color` must be #rrggbb");
+  // Where it runs: absent means every system. Deck will not load or install it on any other.
+  if (m.platforms !== undefined && (!Array.isArray(m.platforms) || !m.platforms.length || !m.platforms.every((p) => ["windows", "linux", "mac"].includes(p)))) {
+    errors.push("`platforms` lists the systems it runs on, from \"windows\", \"linux\" and \"mac\"; leave it out to run on all of them");
+  }
   if (typeof m.icon === "string" && m.icon.endsWith(".svg") && m.icon !== ICON_FILE) errors.push(`an icon of its own must be named ${ICON_FILE}`);
   return errors;
 }
@@ -152,6 +156,21 @@ export function checkPermissions(declared, bundle, table, id) {
   return { errors, notes, used: [...needs.keys()] };
 }
 
+/**
+ * Windows-only habits in a plugin that says it runs on Linux too (no "platforms", or a list naming
+ * "linux"): a path joined with a backslash, a program named with ".exe". Notes, not errors, and
+ * none for a bundle that asks isWindows(), which keeps a Windows branch beside a Linux one.
+ */
+export function checkPortable(manifest, bundle) {
+  const runs = Array.isArray(manifest.platforms) ? manifest.platforms : ["windows", "linux"];
+  if (!runs.includes("linux") || /\(\)\.isWindows\(|\bisWindows\(/.test(bundle)) return [];
+  const notes = [];
+  const joins = (bundle.match(/\}\\\\|["'`]\\\\["'`]/g) ?? []).length;
+  if (joins) notes.push(`It joins paths with a backslash (${joins} place${joins > 1 ? "s" : ""}), which on Linux is part of a file name: ask isWindows() from the bridge for the separator, or say "platforms": ["windows"] in plugin.json.`);
+  if (/\.exe["'`]/.test(bundle)) notes.push(`It names a program with ".exe", which Linux programs do not have: ask isWindows() from the bridge, or say "platforms": ["windows"] in plugin.json.`);
+  return notes;
+}
+
 // ---- points ----
 // A version's points: advice for whoever is choosing a plugin, never a gate (the checks above are
 // that). Worked out once when it is published, by the registry for a submission and by