@abraca/plugin 2.26.0 → 2.28.0

package/dist/index.d.ts

@@ -116,11 +116,17 @@ interface AbraPlugin {
    */
   serverCacheRenderer?(docId: string, ydoc: AbraYDoc): unknown;
   /**
-   * Server-side background runners (Nitro context, service-role identity).
+   * Host-side background runners. Historically a Nitro, service-role context;
+   * now host-agnostic and capability-gated — a runner declares what it
+   * `requires` (e.g. `process`) and any host that can satisfy it runs it
+   * (Nitro, Electron-main `utilityProcess`, a headless Node daemon). Runners
+   * with no `requires` run everywhere, exactly as before. Identity is the
+   * host's to decide: a doc-transport runner can use the logged-in user's
+   * identity rather than a global service role.
    *
-   * Typed as `unknown[]` in the shared contract because each host wraps
-   * the runner ctx with its own `AbracadabraClient` / `AbracadabraProvider`
-   * / `DocCacheAPI` / etc. — a structural override here would force every
+   * Typed as `unknown[]` in the shared contract because each host wraps the
+   * runner ctx with its own `AbracadabraClient` / `AbracadabraProvider` /
+   * `DocCacheAPI` / etc. — a structural override here would force every
    * consumer to either match the shared base structure exactly or fight
    * input-contravariance. Consumers narrow this to their own
    * `ServerRunnerDefinition[]` in their `CouPlugin` / `AbracadabraPlugin`
@@ -253,6 +259,72 @@ interface CollaborationUser {
   publicKey?: string;
   docId?: string;
 }
+/**
+ * A capability a runner can require from its host environment. A host starts a
+ * runner only if it can satisfy every requirement, and injects the matching
+ * handle into the runner context's `host` bag. Hosts that can't satisfy a
+ * requirement skip the runner. This is what lets ONE runner definition target
+ * Electron-main, a headless Node daemon, or a future Nitro-with-PTY host
+ * interchangeably.
+ *
+ * Currently the only token is `process` (the host can execute OS processes /
+ * spawn a pseudo-terminal). String union so new capabilities stay additive.
+ */
+type HostCapability = "process";
+/** Options for spawning a pseudo-terminal via the `process` host capability. */
+interface PtySpawnOptions {
+  /** Working directory. Defaults to the host runner's cwd. */
+  cwd?: string;
+  /** Extra environment variables, merged over the host's. */
+  env?: Record<string, string>;
+  /** Initial column count. Host default (e.g. 80) when omitted. */
+  cols?: number;
+  /** Initial row count. Host default (e.g. 24) when omitted. */
+  rows?: number;
+  /** `TERM` value. Defaults to `xterm-color`. */
+  term?: string;
+}
+/**
+ * A live pseudo-terminal handle returned by `ProcessHostCapability.spawn`. The
+ * host owns the real PTY (node-pty, a helper binary, …); the runner drives it
+ * through this structural interface so the plugin bundle never imports a native
+ * module.
+ */
+interface PtyHandle {
+  /** Write bytes to the PTY's stdin. */
+  write(data: string | Uint8Array): void;
+  /** Resize the PTY. */
+  resize(cols: number, rows: number): void;
+  /** Subscribe to PTY output. Returns an unsubscribe function. */
+  onData(listener: (chunk: Uint8Array) => void): () => void;
+  /** Subscribe to PTY exit. Returns an unsubscribe function. */
+  onExit(listener: (info: {
+    exitCode: number;
+    signal?: number;
+  }) => void): () => void;
+  /** Terminate the PTY (host-defined default signal, e.g. SIGTERM). */
+  kill(signal?: string): void;
+  /** OS process id, when the host exposes one. */
+  readonly pid?: number;
+}
+/**
+ * The `process` capability handle: the host can spawn OS processes / PTYs.
+ * Injected into a runner's context (`ctx.host.process`) only by hosts that can
+ * satisfy `requires: ['process']`.
+ */
+interface ProcessHostCapability {
+  /** Spawn a pseudo-terminal running `file` with `args`. */
+  spawn(file: string, args?: readonly string[], options?: PtySpawnOptions): PtyHandle;
+}
+/**
+ * Bag of host-capability handles injected into a runner's context. The host
+ * populates only what it can provide; a runner that declared a matching
+ * `requires` entry is guaranteed the corresponding handle is present (the host
+ * would not have started it otherwise).
+ */
+interface HostCapabilities {
+  process?: ProcessHostCapability;
+}
 /**
  * Cleanup function returned by a runner's `start()`. Called on graceful
  * server shutdown.
@@ -268,6 +340,14 @@ type RunnerCleanup = (() => void | Promise<void>) | undefined | void;
  */
 interface ServerRunnerDefinition<TCtx = ServerRunnerContextBase> {
   name: string;
+  /**
+   * Host capabilities this runner needs. A host starts the runner only if it
+   * can satisfy every entry (and injects the matching handles into the
+   * context's `host` bag). Hosts that can't satisfy a requirement skip the
+   * runner. Omit / leave empty to run in any host — the historical behaviour
+   * of pure Y.Doc-observer runners, unchanged.
+   */
+  requires?: readonly HostCapability[];
   /** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
   start(ctx: TCtx): Promise<RunnerCleanup> | RunnerCleanup;
 }
@@ -280,6 +360,12 @@ interface ServerRunnerContextBase {
   rootDoc: AbraYDoc;
   /** Space ID if this runner is scoped to a space; `null` for hub-scoped runners. */
   spaceId?: string | null;
+  /**
+   * Host-capability handles satisfying this runner's `requires`. Populated by
+   * the host with whatever it can provide; a runner that declared
+   * `requires: ['process']` can rely on `host.process` being present.
+   */
+  host?: HostCapabilities;
 }
 //#endregion
 //#region packages/plugin/src/registry.d.ts
@@ -386,7 +472,7 @@ declare class PluginRegistry<P extends AbraPlugin = AbraPlugin> {
  * Wasm / Web Worker / iframe sandboxing so the contract is enforced at the
  * runtime boundary, not just the host-API boundary.
  */
-type PluginCapability = /** Outbound HTTP — `network` (any host) or `network:<host>` (exact match, wildcards allowed). */`network${"" | `:${string}`}` /** Filesystem reads — only meaningful in Tauri / native hosts. */ | "fs:read" /** Filesystem writes — Tauri / native only. */ | "fs:write" /** Read the clipboard. */ | "clipboard:read" /** Write the clipboard. */ | "clipboard:write" /** Read any Y.Doc the host has loaded. */ | "doc-read" /** Mutate Y.Docs (transact_mut against the host's provider). */ | "doc-write" /** Broadcast presence / awareness state. */ | "awareness" /** Register an RPC v1 handler on the service runner. */ | "server-runner" /** Contribute items to the global command palette. */ | "command-palette" /** Contribute editor toolbar items. */ | "toolbar" /** Contribute bubble-menu items (text selection). */ | "bubble-menu" /** Contribute slash-command suggestion items. */ | "slash-command" /** Contribute drag-handle items. */ | "drag-handle" /** Register a page-type renderer with the given slug. */ | `page-type:${string}` /** Send messages on the in-doc chat channel. */ | "chat:send" /** Read in-doc chat history. */ | "chat:read" /** Show user-visible notifications. */ | "notifications:show";
+type PluginCapability = /** Outbound HTTP — `network` (any host) or `network:<host>` (exact match, wildcards allowed). */`network${"" | `:${string}`}` /** Filesystem reads — only meaningful in Tauri / native hosts. */ | "fs:read" /** Filesystem writes — Tauri / native only. */ | "fs:write" /** Read the clipboard. */ | "clipboard:read" /** Write the clipboard. */ | "clipboard:write" /** Read any Y.Doc the host has loaded. */ | "doc-read" /** Mutate Y.Docs (transact_mut against the host's provider). */ | "doc-write" /** Broadcast presence / awareness state. */ | "awareness" /** Register an RPC v1 handler on the service runner. */ | "server-runner" /** Execute OS processes / spawn a pseudo-terminal — only honoured by process-capable hosts (Electron main, headless Node). */ | "process:exec" /** Contribute items to the global command palette. */ | "command-palette" /** Contribute editor toolbar items. */ | "toolbar" /** Contribute bubble-menu items (text selection). */ | "bubble-menu" /** Contribute slash-command suggestion items. */ | "slash-command" /** Contribute drag-handle items. */ | "drag-handle" /** Register a page-type renderer with the given slug. */ | `page-type:${string}` /** Send messages on the in-doc chat channel. */ | "chat:send" /** Read in-doc chat history. */ | "chat:read" /** Show user-visible notifications. */ | "notifications:show";
 interface PluginManifestAuthor {
   /** GitHub login. Identifies the author in the registry. */
   github?: string;
@@ -673,4 +759,4 @@ interface SandboxOptions extends PluginHostOptions {
  */
 declare function loadSandboxedPlugin(manifest: Pick<PluginManifest, "id" | "capabilities">, artifactUrl: string, options?: SandboxOptions): Promise<SandboxedPlugin>;
 //#endregion
-export { type AbraAwarenessContribution, type AbraCommandItem, type AbraKeyboardShortcut, type AbraMentionItem, type AbraMentionProvider, type AbraNodePanelSlot, type AbraPlugin, type AbraSettingsPanel, type AbraTiptapExtension, type AbraYDoc, CapabilityDenied, type ClientPluginCtx, type CollaborationUser, type CommandPaletteCtx, type DragHandlePluginCtx, type EditorPluginCtx, type EditorRefLike, type ExternalPluginEntry, type GuardedClipboard, type GuardedFetch, type GuardedNotifications, type MentionPluginCtx, type NodePanelCtx, type PluginCapability, type PluginHost, type PluginHostOptions, type PluginManifest, type PluginManifestAuthor, type PluginManifestContributes, type PluginOrigin, type PluginPricing, PluginRegistry, type PluginRegistryEntry, type PluginVersionStatus, type RefLike, type RunnerCleanup, type SandboxOptions, type SandboxedPlugin, type ServerRunnerContextBase, type ServerRunnerDefinition, createPluginHost, isSafePluginUrl, loadSandboxedPlugin, matchesNetworkCapability, normalizePluginUrl };
+export { type AbraAwarenessContribution, type AbraCommandItem, type AbraKeyboardShortcut, type AbraMentionItem, type AbraMentionProvider, type AbraNodePanelSlot, type AbraPlugin, type AbraSettingsPanel, type AbraTiptapExtension, type AbraYDoc, CapabilityDenied, type ClientPluginCtx, type CollaborationUser, type CommandPaletteCtx, type DragHandlePluginCtx, type EditorPluginCtx, type EditorRefLike, type ExternalPluginEntry, type GuardedClipboard, type GuardedFetch, type GuardedNotifications, type HostCapabilities, type HostCapability, type MentionPluginCtx, type NodePanelCtx, type PluginCapability, type PluginHost, type PluginHostOptions, type PluginManifest, type PluginManifestAuthor, type PluginManifestContributes, type PluginOrigin, type PluginPricing, PluginRegistry, type PluginRegistryEntry, type PluginVersionStatus, type ProcessHostCapability, type PtyHandle, type PtySpawnOptions, type RefLike, type RunnerCleanup, type SandboxOptions, type SandboxedPlugin, type ServerRunnerContextBase, type ServerRunnerDefinition, createPluginHost, isSafePluginUrl, loadSandboxedPlugin, matchesNetworkCapability, normalizePluginUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/plugin",
-  "version": "2.26.0",
+  "version": "2.28.0",
   "description": "Shared plugin contract + registry for @abraca/nuxt and cou-shell.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -26,6 +26,11 @@ export {
 	type AbraSettingsPanel,
 	type AbraKeyboardShortcut,
 	type CollaborationUser,
+	type HostCapability,
+	type PtySpawnOptions,
+	type PtyHandle,
+	type ProcessHostCapability,
+	type HostCapabilities,
 	type RunnerCleanup,
 	type ServerRunnerDefinition,
 	type ServerRunnerContextBase,

package/src/manifest.ts

@@ -35,6 +35,8 @@ export type PluginCapability =
 	| "awareness"
 	/** Register an RPC v1 handler on the service runner. */
 	| "server-runner"
+	/** Execute OS processes / spawn a pseudo-terminal — only honoured by process-capable hosts (Electron main, headless Node). */
+	| "process:exec"
 	/** Contribute items to the global command palette. */
 	| "command-palette"
 	/** Contribute editor toolbar items. */

package/src/types.ts

@@ -151,11 +151,17 @@ export interface AbraPlugin {
 	serverCacheRenderer?(docId: string, ydoc: AbraYDoc): unknown;
 
 	/**
-	 * Server-side background runners (Nitro context, service-role identity).
+	 * Host-side background runners. Historically a Nitro, service-role context;
+	 * now host-agnostic and capability-gated — a runner declares what it
+	 * `requires` (e.g. `process`) and any host that can satisfy it runs it
+	 * (Nitro, Electron-main `utilityProcess`, a headless Node daemon). Runners
+	 * with no `requires` run everywhere, exactly as before. Identity is the
+	 * host's to decide: a doc-transport runner can use the logged-in user's
+	 * identity rather than a global service role.
 	 *
-	 * Typed as `unknown[]` in the shared contract because each host wraps
-	 * the runner ctx with its own `AbracadabraClient` / `AbracadabraProvider`
-	 * / `DocCacheAPI` / etc. — a structural override here would force every
+	 * Typed as `unknown[]` in the shared contract because each host wraps the
+	 * runner ctx with its own `AbracadabraClient` / `AbracadabraProvider` /
+	 * `DocCacheAPI` / etc. — a structural override here would force every
 	 * consumer to either match the shared base structure exactly or fight
 	 * input-contravariance. Consumers narrow this to their own
 	 * `ServerRunnerDefinition[]` in their `CouPlugin` / `AbracadabraPlugin`
@@ -316,6 +322,82 @@ export interface CollaborationUser {
 	docId?: string;
 }
 
+// ── Host capabilities (capability-gated runners) ───────────────────────────────
+
+/**
+ * A capability a runner can require from its host environment. A host starts a
+ * runner only if it can satisfy every requirement, and injects the matching
+ * handle into the runner context's `host` bag. Hosts that can't satisfy a
+ * requirement skip the runner. This is what lets ONE runner definition target
+ * Electron-main, a headless Node daemon, or a future Nitro-with-PTY host
+ * interchangeably.
+ *
+ * Currently the only token is `process` (the host can execute OS processes /
+ * spawn a pseudo-terminal). String union so new capabilities stay additive.
+ */
+export type HostCapability = "process";
+
+/** Options for spawning a pseudo-terminal via the `process` host capability. */
+export interface PtySpawnOptions {
+	/** Working directory. Defaults to the host runner's cwd. */
+	cwd?: string;
+	/** Extra environment variables, merged over the host's. */
+	env?: Record<string, string>;
+	/** Initial column count. Host default (e.g. 80) when omitted. */
+	cols?: number;
+	/** Initial row count. Host default (e.g. 24) when omitted. */
+	rows?: number;
+	/** `TERM` value. Defaults to `xterm-color`. */
+	term?: string;
+}
+
+/**
+ * A live pseudo-terminal handle returned by `ProcessHostCapability.spawn`. The
+ * host owns the real PTY (node-pty, a helper binary, …); the runner drives it
+ * through this structural interface so the plugin bundle never imports a native
+ * module.
+ */
+export interface PtyHandle {
+	/** Write bytes to the PTY's stdin. */
+	write(data: string | Uint8Array): void;
+	/** Resize the PTY. */
+	resize(cols: number, rows: number): void;
+	/** Subscribe to PTY output. Returns an unsubscribe function. */
+	onData(listener: (chunk: Uint8Array) => void): () => void;
+	/** Subscribe to PTY exit. Returns an unsubscribe function. */
+	onExit(
+		listener: (info: { exitCode: number; signal?: number }) => void,
+	): () => void;
+	/** Terminate the PTY (host-defined default signal, e.g. SIGTERM). */
+	kill(signal?: string): void;
+	/** OS process id, when the host exposes one. */
+	readonly pid?: number;
+}
+
+/**
+ * The `process` capability handle: the host can spawn OS processes / PTYs.
+ * Injected into a runner's context (`ctx.host.process`) only by hosts that can
+ * satisfy `requires: ['process']`.
+ */
+export interface ProcessHostCapability {
+	/** Spawn a pseudo-terminal running `file` with `args`. */
+	spawn(
+		file: string,
+		args?: readonly string[],
+		options?: PtySpawnOptions,
+	): PtyHandle;
+}
+
+/**
+ * Bag of host-capability handles injected into a runner's context. The host
+ * populates only what it can provide; a runner that declared a matching
+ * `requires` entry is guaranteed the corresponding handle is present (the host
+ * would not have started it otherwise).
+ */
+export interface HostCapabilities {
+	process?: ProcessHostCapability;
+}
+
 // ── Server runners ────────────────────────────────────────────────────────────
 
 /**
@@ -337,6 +419,14 @@ export type RunnerCleanup =
  */
 export interface ServerRunnerDefinition<TCtx = ServerRunnerContextBase> {
 	name: string;
+	/**
+	 * Host capabilities this runner needs. A host starts the runner only if it
+	 * can satisfy every entry (and injects the matching handles into the
+	 * context's `host` bag). Hosts that can't satisfy a requirement skip the
+	 * runner. Omit / leave empty to run in any host — the historical behaviour
+	 * of pure Y.Doc-observer runners, unchanged.
+	 */
+	requires?: readonly HostCapability[];
 	/** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
 	start(ctx: TCtx): Promise<RunnerCleanup> | RunnerCleanup;
 }
@@ -350,4 +440,10 @@ export interface ServerRunnerContextBase {
 	rootDoc: AbraYDoc;
 	/** Space ID if this runner is scoped to a space; `null` for hub-scoped runners. */
 	spaceId?: string | null;
+	/**
+	 * Host-capability handles satisfying this runner's `requires`. Populated by
+	 * the host with whatever it can provide; a runner that declared
+	 * `requires: ['process']` can rely on `host.process` being present.
+	 */
+	host?: HostCapabilities;
 }