deck-plugin-sdk 1.6.1 → 1.8.0

package/types/core/terminals.d.ts

@@ -43,6 +43,8 @@ export interface LayoutTab {
      * tab that has a cell to itself, which is every tab written before zones held several.
      */
     hidden?: boolean;
+    /** The tab group it is in (LayoutWorkspace.groups); a group's tabs sit together in one zone. */
+    group?: string;
 }
 export interface LayoutWorkspace {
     id: string;
@@ -50,6 +52,8 @@ export interface LayoutWorkspace {
     cwd: string;
     tabs: LayoutTab[];
     activeTab: string;
+    /** Tab groups: a name and colour over tabs that sit together in a zone's row, folded or not. */
+    groups?: TabGroup[];
     /** Its colour on the sidebar's collapsed rail, by index (Terminals' TONES); none picks one from the name. */
     color?: number;
 }
@@ -121,7 +125,53 @@ export declare function moveZone(tabs: readonly LayoutTab[], id: string, to: {
  * Every tab's cell is pinned first (placeAll): a tab with no stored position takes its cell from
  * its index, so reordering the list could otherwise move a zone you never touched.
  */
-export declare function reorderTab(tabs: readonly LayoutTab[], srcId: string, overId: string, after: boolean): LayoutTab[];
+export declare function reorderTab(tabs: readonly LayoutTab[], srcId: string, overId: string, after: boolean, 
+/** A drag in the strip says which group the tab ends up in: the one of the tab it is held over
+ *  (null: none, held over a tab outside any group or over a group's chip). Left out, the tabs
+ *  either side decide (settleGroup). */
+group?: string | null): LayoutTab[];
+/** A tab group: its tabs carry its id. Its colour is an index into GROUP_COLORS. */
+export interface TabGroup {
+    id: string;
+    name: string;
+    color: number;
+    folded?: boolean;
+}
+/** Chrome's group colours, tuned for Deck's dark surfaces. */
+export declare const GROUP_COLORS: string[];
+/**
+ * Put a tab in a group: `groupId`, or a new one in the next colour not yet used (its id is
+ * returned, so its editor can open). The tab moves next to the group's other tabs.
+ */
+export declare function addToGroup(w: LayoutWorkspace, tabId: string, groupId?: string): {
+    w: LayoutWorkspace;
+    groupId: string;
+};
+/** Take a tab out of its group, to just after the group's tabs. */
+export declare function leaveGroup(w: LayoutWorkspace, tabId: string): LayoutWorkspace;
+/**
+ * Move a whole group, its tabs in their order, to just before or after `overId`. Over another
+ * group's tab it goes before or after that group as a whole, never into the middle of it.
+ */
+export declare function moveGroup(tabs: readonly LayoutTab[], groupId: string, overId: string, after: boolean): LayoutTab[];
+/**
+ * Fold a group, or open it. A group holding the tab its zone shows is not folded over it: the
+ * zone moves to the nearest tab outside the group that is not itself folded away (after the group
+ * first, then before it). With none, `makeTab` gives a new tab for the zone to open on; without
+ * it, the group stays open.
+ */
+export declare function toggleGroupFold(w: LayoutWorkspace, groupId: string, makeTab?: () => LayoutTab): LayoutWorkspace;
+/** The group goes; its tabs stay where they are. */
+export declare function ungroup(w: LayoutWorkspace, groupId: string): LayoutWorkspace;
+/** Change a group's name, colour or fold. */
+export declare function setGroup(w: LayoutWorkspace, groupId: string, patch: Partial<Omit<TabGroup, "id">>): LayoutWorkspace;
+/**
+ * The open tab is never folded away: however it came to be open (the tab beside a closed one, the
+ * switcher, a shortcut, an agent's notification), a folded group holding it opens.
+ */
+export declare function openActiveGroup(w: LayoutWorkspace): LayoutWorkspace;
+/** A group with no tabs left goes (its last tab closed, moved to another zone, taken out). */
+export declare function pruneGroups(w: LayoutWorkspace): LayoutWorkspace;
 /**
  * Move one tab to another zone's cell — joining the zone there as the tab it shows, or making a
  * new zone in an empty cell. The zone it left keeps its other tabs.
@@ -147,8 +197,9 @@ export declare function addTabToZone(tabs: readonly LayoutTab[], besideId: strin
  */
 export declare function showActiveTab(w: LayoutWorkspace): LayoutWorkspace;
 /**
- * Which tab becomes active when `closing` goes: another tab in the same zone if it has one, so
- * closing a tab does not also throw you out of the zone; otherwise the first zone left.
+ * Which tab becomes active when `closing` goes: the one beside it in the same zone (the next, or
+ * the one before when it was last), as a browser does, so closing a tab neither throws you out of
+ * the zone nor back to its first tab; otherwise the first zone left.
  */
 export declare function nextActiveAfterClose(tabs: readonly LayoutTab[], closing: string): string | undefined;
 /** The first free spot on the top row, for a zone created without a position of its own. */
@@ -186,6 +237,11 @@ export declare function paneLocation(paneId: string): {
     wsName: string;
     tabId: string;
 } | undefined;
+/**
+ * Go to a pane: switch to its workspace and tab, then focus it. The pane only mounts once
+ * Terminals has rendered the newly-selected tab, so the focus is retried across a few frames.
+ */
+export declare function revealPane(paneId: string): boolean;
 /** Give a pane real keyboard focus. No-op if it isn't mounted yet — the caller retries. */
 export declare function focusPane(paneId: string): boolean;
 export declare const termSpawn: (id: string, cwd: string, cols: number, rows: number) => Promise<void>;
@@ -307,6 +363,8 @@ export declare function paneLines(id: string, max?: number): string[];
  * PDF plugin), otherwise in this workspace's Editor, at `line` when given.
  */
 export declare function openFile(path: string, line?: number): void;
+/** Open a file in this workspace's Editor, whatever opens its type elsewhere (Open with › Editor). */
+export declare function openInEditor(path: string, line?: number): void;
 export declare function getInstance(id: string): Instance;
 /**
  * Wrap pasted text in bracketed-paste markers, so the receiving app can tell one paste from
@@ -384,6 +442,18 @@ export declare function refit(id: string): void;
  * (Claude, vim) treats it as a repaint. Terminal and shell stay in agreement either way.
  */
 export declare function clearPane(id: string): void;
+/**
+ * Stop the claude or codex in a pane: asked with Ctrl+C, so it tidies up and prints how to resume,
+ * and killed only if it stays (agent_stop in mem.rs), in which case its leftover modes are cleared.
+ */
+export declare function stopPaneAgent(id: string): Promise<void>;
+/**
+ * Turn off what a killed program left on in the pane's xterm: mouse reporting, focus events,
+ * bracketed paste, a hidden cursor. A program that exits turns these off itself; one killed
+ * never does, so every mouse move after it is typed into the shell. Only xterm is told (not the
+ * PTY), and unlike `term.reset()` the screen and scrollback stay.
+ */
+export declare function resetPaneModes(id: string): void;
 /**
  * Kill the pane's shell and start a fresh one in the same xterm, keeping the pane id (so the
  * layout, name and split position survive). Claude is NOT re-resumed: `agentResumed` already

package/types/modules/editor/tree.d.ts

@@ -8,6 +8,8 @@ export declare const normPath: (p: string) => string;
 export declare const dirName: (p: string) => string;
 /** A repo as a picker names it: its path under `root`, or its own name when it is not under it. */
 export declare function repoLabel(root: string, repo: string): string;
+/** The repo a path is in: the deepest of `repos` that holds it (a nested repo before its parent). */
+export declare function repoOf(repos: readonly string[], path: string): string | undefined;
 export interface ChangeDir<T> {
     kind: "dir";
     name: string;

package/validate.mjs

@@ -0,0 +1,112 @@
+// The checks a package must pass to be published, that need nothing but its files: shared by
+// `deck-plugin publish` (which runs them before anything leaves the machine) and the registry's
+// own validation (deck-registry's tools/validate.mjs, which adds what needs GitHub: who owns it,
+// the release, the rebuild). One copy, so the two cannot disagree about what is valid.
+//
+// Pure: no network, no filesystem.
+
+/** Deck's own modules and the view prefixes: a plugin with one of these ids could never load. */
+export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "deck", "module", "plugin", "browser"]);
+/**
+ * Packages the registry's rebuild executes. Each must be the real one from npm, since the rebuild
+ * runs on a machine that can merge; see the SECURITY note in deck-registry's tools/validate.mjs.
+ */
+export const BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion"];
+export const MAX_FILE = 10 * 1024 * 1024, MAX_TOTAL = 15 * 1024 * 1024;
+export const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** A file's name as a release asset: flat, so a language's snippets/x.json is snippets--x.json. */
+export const assetName = (name) => name.replace(/\//g, "--");
+
+export function compareVersions(a, b) {
+  const x = SEMVER.exec(a), y = SEMVER.exec(b);
+  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
+  if (x[4] === y[4]) return 0;
+  return x[4] === undefined ? 1 : y[4] === undefined ? -1 : x[4] < y[4] ? -1 : 1;
+}
+
+/** An id: its shape, and not one of Deck's own. */
+export function checkId(id) {
+  const errors = [];
+  if (!ID.test(id)) errors.push(`the id \`${id}\` must be lowercase letters, digits and dashes, 40 at most`);
+  if (RESERVED.has(id)) errors.push(`\`${id}\` is one of Deck's own names and cannot be a package id`);
+  return errors;
+}
+
+/** A plugin's plugin.json, for publishing: what the registry shows and what Deck needs. */
+export function checkManifest(m) {
+  const errors = [];
+  if (typeof m.name !== "string" || !m.name.trim() || m.name.length > 60) errors.push("the name must be 1 to 60 characters");
+  if (typeof m.description !== "string" || m.description.trim().length < 10 || m.description.length > 300) {
+    errors.push("the description must be 10 to 300 characters");
+  }
+  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");
+  return errors;
+}
+
+/** The release's files: the allowed names, the required ones, and the size limits. */
+export function checkAssets(kind, assets) {
+  const errors = [];
+  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js"].includes(n) : n === "language.json" || /^snippets--[\w.-]+\.json$/.test(n);
+  for (const a of assets) if (!ok(a.name)) errors.push(`the release has \`${a.name}\`, which a ${kind} cannot contain`);
+  for (const need of kind === "plugin" ? ["plugin.json", "plugin.js"] : ["language.json"]) {
+    if (!assets.some((a) => a.name === need)) errors.push(`the release has no \`${need}\``);
+  }
+  for (const a of assets) if (a.size > MAX_FILE) errors.push(`\`${a.name}\` is ${(a.size / 1048576).toFixed(1)} MB; a file may be 10 MB at most`);
+  const total = assets.reduce((n, a) => n + a.size, 0);
+  if (total > MAX_TOTAL) errors.push(`the release is ${(total / 1048576).toFixed(1)} MB; a package may be 15 MB at most`);
+  for (const a of assets) if ("digest" in a && !/^sha256:[0-9a-f]{64}$/.test(a.digest ?? "")) errors.push(`GitHub gives no sha256 for \`${a.name}\`; upload it again`);
+  return errors;
+}
+
+/** Whether a lockfile lets `npm ci` install only published npm packages. */
+export function checkLockfile(lock) {
+  const errors = [];
+  if (!lock || lock.lockfileVersion < 2 || typeof lock.packages !== "object") return ["package-lock.json must be npm 7 or newer (lockfileVersion 2 or 3)"];
+  for (const [path, p] of Object.entries(lock.packages)) {
+    if (path === "") continue;
+    if (p.link) { errors.push(`\`${path}\` is a link to a folder; publish it to npm or bundle it`); continue; }
+    if (!p.resolved?.startsWith("https://registry.npmjs.org/") || !/^sha(512|384|256)-/.test(p.integrity ?? "")) {
+      errors.push(`\`${path}\` does not come from registry.npmjs.org with an integrity hash`);
+    }
+    const name = path.replace(/^.*node_modules\//, "");
+    const runs = BUILD_RUNS.includes(name) || name.startsWith("@esbuild/");
+    if (runs && p.name && p.name !== name) errors.push(`\`${name}\` is an alias of \`${p.name}\`; the build runs it, so it must be the real package`);
+  }
+  if (!lock.packages["node_modules/deck-plugin-sdk"]) errors.push("the lockfile has no deck-plugin-sdk; a plugin is built with it");
+  return errors;
+}
+
+/**
+ * What a plugin's permissions must be, from its manifest and its bundle (`table` is the SDK's
+ * permissions.json): only known names, and covering every bridge call the bundle makes. The shim
+ * calls the bridge as `b().fsWrite(`, which minifying keeps, so `().fn(` is the pattern, and a
+ * method of the same name on something else (a RegExp's .exec) does not count. Reaching Deck's
+ * internals directly, around the bridge, is refused outright.
+ */
+export function checkPermissions(declared, bundle, table) {
+  const errors = [], notes = [];
+  if (!Array.isArray(declared)) {
+    return { errors: ['plugin.json must say what it uses: "permissions": [...], or [] when it needs nothing beyond its own data and settings'], notes };
+  }
+  const unknown = declared.filter((p) => !(p in table.permissions));
+  if (unknown.length) errors.push(`unknown permission${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (known: ${Object.keys(table.permissions).join(", ")})`);
+  if (/__TAURI_INTERNALS__|__TAURI_IPC__|window\.__TAURI__\b/.test(bundle)) {
+    errors.push("its bundle reaches Deck's internals directly, around the bridge its permissions apply to");
+  }
+  const needs = new Map();
+  for (const [fn, p] of Object.entries(table.bridge)) {
+    if (new RegExp(`\\(\\)\\.${fn}\\(`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), fn]);
+  }
+  for (const [mod, p] of Object.entries(table.modules)) {
+    if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
+  }
+  for (const [p, fns] of needs) {
+    if (!declared.includes(p)) errors.push(`it uses ${fns.slice(0, 4).join(", ")}${fns.length > 4 ? ` and ${fns.length - 4} more` : ""}, which ${fns.length > 1 ? "need" : "needs"} the "${p}" permission; add it to "permissions"`);
+  }
+  if (/\beval\(|new Function\(/.test(bundle)) notes.push("Its bundle uses eval or new Function, which runs code made at run time; a library may do this legitimately.");
+  return { errors, notes };
+}