@rigee/plugin-api 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# @rigee/plugin-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract a [Rigee](https://github.com/Qyuan-Tech/rigee) plugin is written against.
+
+```bash
+npm install --save-dev @rigee/plugin-api
+```
+
+It is a development dependency on purpose: a renderer half leaves it out of its bundle and gets
+Rigee's own copy at runtime (see Building), so the version you build against is for types and for
+`minAppVersion`, not something that ships.
+
+A plugin is up to two halves, because Electron leaves no choice: a PDF renders in the sandboxed
+renderer, and the bytes it renders can only be read in the main process. Each half default-exports
+a [cordis](https://github.com/cordiverse/cordis) plugin, and the two share an id and talk over one
+IPC channel.
+
+```
+my-plugin/
+  package.json     the manifest, under a "rigee" key
+  dist/main.js     ESM. Node. Optional.
+  dist/renderer.js ESM. DOM. Optional.
+```
+
+```jsonc
+{
+  "name": "rigee-plugin-hello",
+  "version": "1.0.0",
+  "rigee": {
+    "id": "hello",
+    "version": "1.0.0",
+    "displayName": "Hello",
+    "apiVersion": 1,
+    "minAppVersion": "1.1.0",
+    "permissions": ["files:read"],
+    "main": "dist/main.js",
+    "renderer": "dist/renderer.js",
+    "contributes": {
+      "views": [{ "id": "hello.panel", "title": "Hello", "slot": "left", "icon": "plugin" }]
+    }
+  }
+}
+```
+
+```tsx
+import { icons, openFile, type PluginViewProps } from '@rigee/plugin-api'
+import type { Context, Plugin } from 'cordis'
+
+function Panel({ onCollapse }: PluginViewProps) {
+  return <button onClick={onCollapse}><icons.CollapseLeft size={14} /></button>
+}
+
+const plugin: Plugin = {
+  name: 'hello',
+  inject: ['contributions'],
+  apply(ctx: Context) {
+    ctx.contributions.view('hello.panel', Panel)
+  }
+}
+export default plugin
+```
+
+## Four entry points
+
+| import | contains | realm |
+|---|---|---|
+| `@rigee/plugin-api` | everything | renderer half |
+| `@rigee/plugin-api/manifest` | the declarative contract only — no React, no DOM | either |
+| `@rigee/plugin-api/data` | the shared data types only | either |
+| `@rigee/plugin-api/context` | types only: what `ctx.contributions`, `ctx.rpc`, `ctx.commands` and `ctx.shell` are | either |
+
+The main half must not import the root entry: it would pull React into a process that cannot
+render. It gets the `ctx` typings with `import type {} from '@rigee/plugin-api/context'`; a plugin
+with a renderer half has them already, through the root entry.
+
+## Building
+
+**The renderer half** leaves exactly `react`, `react-dom`, `react/jsx-runtime` and
+`@rigee/plugin-api` external, as ESM. The shell resolves those through an import map to its own
+copies — two Reacts in one window means broken hooks, and a second copy of this package means
+talking to a host nobody installed. Bundle everything else, including anything you import from
+`@rigee/plugin-api/manifest`: the import map names the package, not its subpaths.
+
+**The main half** is one bundled ESM file for Node, with only `electron` and Node's built-ins left
+external. One file because Rigee re-imports it after an update under a new URL, and a second file
+it imported relatively would come back from Node's module cache as the old one.
+
+**Styles** cannot be a `<link>`: the window's policy does not load stylesheets from a plugin.
+Inline your CSS into the bundle and add it as a `<style>` element when the module loads.
+
+**Workers** cannot be started from a plugin's own files — a window only starts workers from its
+own origin. Start one through the shell instead, from a self-contained script (a worker has no
+import map):
+
+```ts
+new Worker(workerUrl(new URL('./parse.worker.js', import.meta.url)), { type: 'module' })
+```
+
+**Code highlighting** comes from the text editor's own tokenizers: `tokenizeCode(text, 'ts')`
+returns the tokens of each line, so a plugin need not ship a highlighter of its own.
+
+## Publishing, so that Rigee can find it
+
+Rigee's plugins view searches public GitHub. A repository is found and installable when:
+
+| | the rule |
+|---|---|
+| found by | the topic `rigee-plugin` |
+| named | `rigee-plugin-<id>` — the id in lower-case letters, digits and hyphens |
+| released | its latest release (not a draft or pre-release) is tagged `v<version>` |
+| packaged | that release carries `rigee-plugin-<id>-<version>.tgz`, exactly as `npm pack` writes it |
+| agreeing | `name` is the repository's name; the tag, `version` and `rigee.version` are one version |
+
+Rigee downloads the tarball, checks it against the SHA-256 GitHub reports for it, unpacks it
+(regular files and directories under `package/`, nothing else), checks the manifest, and only then
+asks the user — saying where the plugin came from, that it was found by searching, and that Rigee
+has not reviewed it. Turn on immutable releases if you can: a release that cannot be changed after
+it is published is one a user can trust to stay what they approved.
+
+## What `apiVersion` and `minAppVersion` are for
+
+`apiVersion` is the generation of this contract the plugin was built against. Rigee refuses a
+plugin whose `apiVersion` it does not implement, at discovery, with that as the stated reason —
+rather than letting it fail later as a missing export in a stack trace nobody can act on. Adding a
+function does not bump it; removing or reshaping one does.
+
+`minAppVersion` is the oldest Rigee the plugin runs in. A function added to this package exists
+only in Rigee releases from then on, so a plugin that calls one should say so — `tokenizeCode` and
+`workerUrl` arrived in Rigee 1.1.0. An older Rigee then refuses the plugin by name instead of
+failing to link it.
+
+## Permissions, and what they are not
+
+`permissions` is an integrity boundary: the grant is recorded per plugin, and a new version that
+asks for more has to ask again. It is **not** a sandbox. A renderer half runs in the shell's own
+JavaScript context, so a hostile plugin can reach whatever the shell can reach regardless of what
+it declared. Installing one is a decision to run its code with the application's privileges, and
+Rigee's install dialog says so in those words.

package/dist/context.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The services a plugin's halves are given on `ctx`, as a plugin sees them.
+ *
+ * The shell implements each one as a cordis Service, and used to declare them on `Context` from its
+ * own source — which only a plugin compiled INSIDE this repository could see. A plugin from another
+ * repository wrote `ctx.contributions.editor(…)` against a Context that, as far as its compiler
+ * knew, had no such property. So the shapes live here, with the augmentation, and the shell's
+ * classes implement them: one declaration, and a plugin anywhere types against it.
+ *
+ * Types only — this module emits nothing. It is reached through the root entry, which a renderer
+ * half imports anyway, and on its own as `@rigee/plugin-api/context`: a plugin with only a main
+ * half gets the typings with `import type {} from '@rigee/plugin-api/context'`, which costs
+ * nothing at runtime and keeps React out of a process that cannot render.
+ *
+ * Each service has to be named in a half's `inject` before it can be read — `inject: ['commands']`
+ * — or cordis throws, and a half whose injection cannot be met never runs at all.
+ *
+ * BIND A METHOD BEFORE PASSING IT AROUND: `const shell = ctx.shell; const emit = shell.emit.bind(shell)`.
+ * cordis tells the shell WHICH plugin is calling by swapping `this` when a method is called on the
+ * service itself, so a bare `const emit = ctx.shell.emit` arrives with no `this` and throws. Bound,
+ * it is also some eighty times cheaper per call than going through `ctx` each time.
+ */
+import type { Context } from 'cordis';
+import type { BrowserWindow, WebContents } from 'electron';
+import type { PluginId, ViewType } from './manifest';
+import type { PluginEditorComponent, PluginOverlayComponent, PluginStatusItemComponent, PluginTabComponent, PluginTabFactory, PluginViewComponent } from './ui';
+/**
+ * `ctx.contributions`: the components a manifest promised.
+ *
+ * Every id must be one the manifest declares, under the plugin's own prefix — `pdf.preview` for
+ * the plugin `pdf` — or the bind throws. Each bind is revoked with the plugin, so a tab showing a
+ * component of a plugin that was switched off falls back to the shell's notice.
+ */
+export interface PluginContributionsService {
+    /** A viewer for the files an `editors` contribution claims. */
+    editor(viewType: ViewType, component: PluginEditorComponent): void;
+    /** A tab type the plugin owns outright. */
+    tab(viewType: ViewType, component: PluginTabComponent): void;
+    /** What a fresh tab of a `creatable` tab type starts as. */
+    tabFactory(viewType: ViewType, factory: PluginTabFactory): void;
+    /** A side-bar panel. */
+    view(id: ViewType, component: PluginViewComponent): void;
+    statusItem(id: ViewType, component: PluginStatusItemComponent): void;
+    /** Mounted at the shell's root while the plugin is active. */
+    overlay(id: ViewType, component: PluginOverlayComponent): void;
+}
+/**
+ * `ctx.rpc`: the renderer half's line to its own main half, and nobody else's. A command or event
+ * name without the plugin's own prefix — `pdf:read` for `pdf` — throws locally.
+ */
+export interface PluginRpcService {
+    /** Call one of this plugin's main-half commands. Rejects with whatever the handler threw. */
+    invoke<T = unknown>(command: string, payload?: unknown): Promise<T>;
+    /** Listen for one of this plugin's own events — `status`, not `scm:status`. Revoked with the plugin. */
+    on<T = unknown>(event: string, listener: (payload: T) => void): void;
+}
+/** `ctx.commands`: what the renderer half can call. */
+export interface PluginCommandsService {
+    /**
+     * Answer `name`, which must carry the plugin's own prefix: `pdf:read`. What the handler returns
+     * — or the promise it returns resolves to — is what the renderer's `invoke` resolves to, so it
+     * must survive structured cloning: no functions, no class instances. Revoked with the plugin.
+     */
+    register(name: string, handler: (payload: unknown) => unknown): void;
+}
+/** A question for `ctx.shell.ask`: Electron's message box, cut down to what a question needs. */
+export interface AskOptions {
+    type?: 'none' | 'info' | 'error' | 'question' | 'warning';
+    message: string;
+    detail?: string;
+    buttons?: string[];
+    /** The button Return presses. */
+    defaultId?: number;
+    /** The button Escape presses, and the answer when the dialog is dismissed. */
+    cancelId?: number;
+}
+/** `ctx.shell`: what a main half is given of the shell — the window, the renderer, and the user. */
+export interface PluginShellService {
+    /** The app window, or null before it exists and after it is gone. */
+    window(): BrowserWindow | null;
+    /** The shell's own WebContents: the React renderer, not a browser tab. */
+    webContents(): WebContents | null;
+    /** Push an event to this plugin's renderer half. Plugin-local name: `status`, not `scm:status`. */
+    emit(event: string, payload: unknown): void;
+    /**
+     * A URL the renderer can stream this file from, Range requests and all — what a <video> needs.
+     * It names a token, not the path, and works until `releaseFile` or until the plugin is disposed.
+     */
+    serveFile(path: string, mime: string): string;
+    /** Stop serving a URL `serveFile` returned. Unknown or already released is not an error. */
+    releaseFile(url: string): void;
+    /**
+     * Ask the user something in a native dialog over the window: the index of the button pressed.
+     * Through the shell rather than Electron's `dialog`, so that Rigee's own tests can answer it.
+     */
+    ask(options: AskOptions): Promise<number>;
+    /**
+     * Offer to take keyboard focus instead of the shell — return true if you took it. For a plugin
+     * that composites a native view over the window, which the window never focuses by itself.
+     */
+    claimFocus(handler: () => boolean): void;
+}
+/**
+ * The Context both halves receive, with the services above declared on it.
+ *
+ * Also what keeps `cordis` imported in the published declarations: the augmentation below merges
+ * into cordis's own `Context` only when this file imports the module, and a type import that
+ * nothing used would be dropped from the emitted .d.ts — leaving a declaration that shadows cordis's
+ * Context instead of extending it.
+ */
+export type PluginContext = Context;
+declare module 'cordis' {
+    interface Context {
+        /** Renderer half. */
+        contributions: PluginContributionsService;
+        /** Renderer half. */
+        rpc: PluginRpcService;
+        /** Main half. */
+        commands: PluginCommandsService;
+        /** Main half. */
+        shell: PluginShellService;
+        /**
+         * Which plugin this Context belongs to, set by the host on each plugin's own Context.
+         *
+         * The `?` is a TypeScript fiction over a Proxy that THROWS on an unknown property read; both
+         * hosts install an accessor answering undefined on the root, so reading it is always safe.
+         */
+        pluginId?: PluginId;
+    }
+}

package/dist/context.js

@@ -0,0 +1,23 @@
+/**
+ * The services a plugin's halves are given on `ctx`, as a plugin sees them.
+ *
+ * The shell implements each one as a cordis Service, and used to declare them on `Context` from its
+ * own source — which only a plugin compiled INSIDE this repository could see. A plugin from another
+ * repository wrote `ctx.contributions.editor(…)` against a Context that, as far as its compiler
+ * knew, had no such property. So the shapes live here, with the augmentation, and the shell's
+ * classes implement them: one declaration, and a plugin anywhere types against it.
+ *
+ * Types only — this module emits nothing. It is reached through the root entry, which a renderer
+ * half imports anyway, and on its own as `@rigee/plugin-api/context`: a plugin with only a main
+ * half gets the typings with `import type {} from '@rigee/plugin-api/context'`, which costs
+ * nothing at runtime and keeps React out of a process that cannot render.
+ *
+ * Each service has to be named in a half's `inject` before it can be read — `inject: ['commands']`
+ * — or cordis throws, and a half whose injection cannot be met never runs at all.
+ *
+ * BIND A METHOD BEFORE PASSING IT AROUND: `const shell = ctx.shell; const emit = shell.emit.bind(shell)`.
+ * cordis tells the shell WHICH plugin is calling by swapping `this` when a method is called on the
+ * service itself, so a bare `const emit = ctx.shell.emit` arrives with no `this` and throws. Bound,
+ * it is also some eighty times cheaper per call than going through `ctx` each time.
+ */
+export {};

package/dist/data.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The shell's data types that appear on the plugin boundary.
+ *
+ * Moved here from the shell's own `types.ts` rather than copied, and the direction is the point: a
+ * plugin compiled against this package must be looking at the SAME `TabId` and `ViewBounds` the
+ * shell hands it, or the two agree only by coincidence and drift the first time either side edits
+ * a field. `src/shared/types.ts` re-exports these, so the shell still reads as if they were local.
+ *
+ * Only what actually crosses the boundary lives here. The tab union, the group row and the
+ * persisted document stay in the shell: a plugin receives its own state and its own tab id, never
+ * the shape the shell keeps them in, and publishing those would freeze the shell's internals into
+ * a contract nobody asked for.
+ */
+export type WorkspaceId = string;
+export type RepoId = string;
+export type TabId = string;
+/** One root folder inside a workspace. A workspace may hold several, VSCode-style. */
+export interface WorkspaceFolder {
+    /** Absolute path. */
+    path: string;
+    /** Display name; defaults to basename(path) but the user may rename it. */
+    name: string;
+    /** Whether `path` is (or is inside) a git work tree. Resolved at add time and on refresh. */
+    isGitRepo: boolean;
+    /**
+     * Absolute path to the repository root, when `isGitRepo`. May differ from `path` if the user
+     * added a subdirectory of a repo. This, not `path`, is the identity of a repo.
+     */
+    repoRoot: string | null;
+}
+export interface Workspace {
+    id: WorkspaceId;
+    name: string;
+    folders: WorkspaceFolder[];
+    createdAt: number;
+    lastOpenedAt: number;
+    /** Where terminals start when the workspace has no folders. Only set for Scratch. */
+    defaultCwd?: string;
+    /**
+     * The `.code-workspace` file this workspace was opened from, when it came from one.
+     *
+     * Absent for a workspace that is just a folder — which is the majority, and is exactly VS Code's
+     * distinction between a folder and a saved multi-root workspace. Its presence is what makes
+     * "Save Workspace As" an overwrite rather than a new file.
+     */
+    filePath?: string | null;
+}
+/** One entry in a directory listing. */
+export interface FileStat {
+    path: string;
+    name: string;
+    isDir: boolean;
+    /** True when a .gitignore in scope excludes this entry; the tree dims it. */
+    ignored: boolean;
+}
+/** Bounds of a DOM placeholder, in CSS pixels relative to the window's content area. */
+export interface ViewBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}

package/dist/data.js

@@ -0,0 +1,14 @@
+/**
+ * The shell's data types that appear on the plugin boundary.
+ *
+ * Moved here from the shell's own `types.ts` rather than copied, and the direction is the point: a
+ * plugin compiled against this package must be looking at the SAME `TabId` and `ViewBounds` the
+ * shell hands it, or the two agree only by coincidence and drift the first time either side edits
+ * a field. `src/shared/types.ts` re-exports these, so the shell still reads as if they were local.
+ *
+ * Only what actually crosses the boundary lives here. The tab union, the group row and the
+ * persisted document stay in the shell: a plugin receives its own state and its own tab id, never
+ * the shape the shell keeps them in, and publishing those would freeze the shell's internals into
+ * a contract nobody asked for.
+ */
+export {};