@abraca/plugin 2.3.0

package/src/source-spec.ts

@@ -0,0 +1,81 @@
+/**
+ * Plugin source specification — the user-typed shorthand that resolves to a
+ * loadable URL.
+ *
+ * Today the registry server (Phase C) hosts artifacts at canonical URLs.
+ * Until then, both `cou-shell` and `@abraca/nuxt` accept three forms:
+ *
+ *   - `npm:<package>[@version]`     → jsDelivr npm CDN
+ *   - `github:<user>/<repo>[@ref]`  → jsDelivr GitHub CDN
+ *   - any other string              → returned as-is (must be `https://` or `http://localhost`)
+ *
+ * Once Phase C ships we add:
+ *
+ *   - `abra:<plugin-id>[@version]`  → the official registry
+ *
+ * The output URL points at the plugin's bundle entry. Convention is
+ * `<root>/dist/plugin.js`.
+ */
+
+/** A locally-installed external plugin record (persisted to host storage). */
+export interface ExternalPluginEntry {
+	/** Resolved fetch URL — the output of `normalizePluginUrl`. */
+	url: string;
+	/** Plugin `name` from the loaded bundle's manifest / default export. */
+	name: string;
+	label?: string;
+	version?: string;
+	description?: string;
+	enabled: boolean;
+	/** Most recent load error, if any. Cleared on next successful load. */
+	error?: string;
+	installedAt: number;
+	/**
+	 * Integrity hash from the plugin's manifest, if known. Verified on every
+	 * load — a silent change indicates supply-chain tampering and the host
+	 * should refuse to instantiate the plugin.
+	 */
+	integrity?: string;
+}
+
+/**
+ * Resolve a user-typed plugin spec to a fetchable URL.
+ *
+ * - `npm:foo@1.2.3` → `https://cdn.jsdelivr.net/npm/foo@1.2.3/dist/plugin.js`
+ * - `github:org/repo@main` → `https://cdn.jsdelivr.net/gh/org/repo@main/dist/plugin.js`
+ * - anything else → returned trimmed, unchanged
+ */
+export function normalizePluginUrl(input: string): string {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("npm:")) {
+		const pkg = trimmed.slice(4);
+		return `https://cdn.jsdelivr.net/npm/${pkg}/dist/plugin.js`;
+	}
+	if (trimmed.startsWith("github:")) {
+		const repo = trimmed.slice(7);
+		return `https://cdn.jsdelivr.net/gh/${repo}/dist/plugin.js`;
+	}
+	return trimmed;
+}
+
+/**
+ * Reject any URL that isn't HTTPS or localhost over HTTP. Hosts should call
+ * this before importing — `normalizePluginUrl` does not enforce the policy
+ * (npm:/github: shorthand always produces HTTPS, so callers only need this
+ * for raw third-party URLs).
+ */
+export function isSafePluginUrl(url: string): boolean {
+	try {
+		const u = new URL(url);
+		if (u.protocol === "https:") return true;
+		if (
+			u.protocol === "http:" &&
+			(u.hostname === "localhost" || u.hostname === "127.0.0.1")
+		) {
+			return true;
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}

package/src/types.ts

@@ -0,0 +1,353 @@
+/**
+ * Shared plugin contract for cou-shell and `@abraca/nuxt`.
+ *
+ * `AbraPlugin` is the universal interface every plugin satisfies. App-specific
+ * supersets (`CouPlugin`, `AbracadabraPlugin`) extend or intersect this with
+ * tightened contribution shapes — TipTap toolbar items, Nuxt UI dropdown
+ * items, page-type renderers, file importers, etc.
+ *
+ * Zero peer-dep types. `Y.Doc`, `@tiptap/core`'s `Extension`, and Vue's
+ * `Component` are all referenced via local structural markers (`AbraYDoc`,
+ * `AbraTiptapExtension`, `unknown`) so this package compiles in isolation
+ * and can be consumed by hosts on any TipTap / yjs / Vue version without
+ * dragging duplicate-type fights along.
+ */
+
+/**
+ * Structural marker for `yjs`'s `Y.Doc`. Defined locally — and intentionally
+ * permissive — so the plugin contract doesn't pin a specific yjs version. Any
+ * `Y.Doc` from any minor yjs version (13.6.29, 13.6.30, …) is structurally
+ * compatible. Consumers cast back to their own `Y.Doc` as needed.
+ */
+export interface AbraYDoc {
+	readonly clientID?: number;
+}
+
+/**
+ * Structural marker for `@tiptap/core`'s `Extension`. Defined locally — and
+ * intentionally permissive — so the plugin contract doesn't pin a specific
+ * TipTap version. Any `Extension` from any minor TipTap version (3.22.5,
+ * 3.23.2, …) is structurally compatible. Consumers cast back to their own
+ * `Extension` as needed.
+ */
+export interface AbraTiptapExtension {
+	readonly name?: string;
+	readonly type?: string;
+}
+
+// ── Plugin definition ──────────────────────────────────────────────────────────
+
+/**
+ * The universal plugin shape. Every plugin in the Abracadabra ecosystem
+ * (built-in or third-party, in cou-shell or any `@abraca/nuxt` consumer)
+ * satisfies this interface.
+ *
+ * Contribution fields use widened shapes (`unknown`, `Record<string, unknown>`)
+ * where the concrete type is consumer-defined. App-level plugin aliases
+ * (e.g. `CouPlugin`, `AbracadabraPlugin`) narrow them.
+ */
+export interface AbraPlugin {
+	/** Unique slug. Must be stable across versions, e.g. `core`, `kanban`, `my-plugin`. */
+	name: string;
+	/** Human-readable label shown in plugin browsers. Falls back to `name`. */
+	label?: string;
+	/** Plugin version. Should follow semver. */
+	version?: string;
+	/** One-line plugin description shown in browsers and scorecards. */
+	description?: string;
+	/**
+	 * Whether a built-in plugin is enabled by default. `true` if omitted.
+	 * Only consulted for plugins that ship as built-ins; external plugins
+	 * are opt-in regardless.
+	 */
+	defaultEnabled?: boolean;
+
+	// ── Editor contributions ────────────────────────────────────────────────────
+
+	/** TipTap extensions (nodes, marks, extensions) contributed by this plugin. */
+	extensions?: () => AbraTiptapExtension[];
+
+	/**
+	 * Optional promise that resolves when this plugin's extensions are fully
+	 * loaded. Used by `PluginRegistry.waitForExtensions()` so the editor
+	 * doesn't initialise before async extension bundles are ready.
+	 */
+	extensionsReady?: Promise<void>;
+
+	/** Page-type renderers keyed by type slug. Concrete shape is consumer-defined. */
+	pageTypes?: Record<string, unknown>;
+
+	/**
+	 * Custom editor handlers (e.g. `table`, `fileUpload`). Each entry merges
+	 * into the host's handler map. Handler signatures are consumer-defined —
+	 * cou-shell types them as `EditorHandler` from `@nuxt/ui` (which uses
+	 * specific arg counts that wouldn't match `(...args: any[]) => any`), the
+	 * module uses a different shape; the shared contract just promises a
+	 * record of any values.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	customHandlers?: () => Record<string, any>;
+
+	/**
+	 * Editor toolbar / menu / slash-command / drag-handle contributions.
+	 *
+	 * The context shape and item-group shape are both consumer-defined. Method
+	 * shorthand syntax is used deliberately — interface-method positions are
+	 * bivariant in TypeScript, so app-specific aliases (`AbracadabraPlugin`,
+	 * `CouPlugin`) can narrow `ctx` to their own tightened context types
+	 * without `Omit`-and-rewrite gymnastics.
+	 */
+	toolbarItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+
+	bubbleMenuItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+
+	suggestionItems?(ctx: EditorPluginCtx): readonly (readonly unknown[])[];
+
+	dragHandleItems?(ctx: DragHandlePluginCtx): readonly (readonly unknown[])[];
+
+	/** Mention (@) providers contributing items to the mention popup. */
+	mentionProviders?: AbraMentionProvider[];
+
+	/** Awareness field declarations — keys this plugin reads/writes on awareness. */
+	awarenessContributions?: AbraAwarenessContribution[];
+
+	/** Global command-palette (⌘K) items. */
+	commandPaletteItems?(
+		ctx: CommandPaletteCtx,
+	): readonly AbraCommandItem[] | Promise<readonly AbraCommandItem[]>;
+
+	/** Extra tabs rendered in the child-document slideover panel. */
+	nodePanelSlots?: AbraNodePanelSlot[];
+
+	/** Settings panel contributed to the global settings view. */
+	settingsPanel?: AbraSettingsPanel;
+
+	/** Global keyboard shortcuts (document-level, not inside TipTap scope). */
+	keyboardShortcuts?: AbraKeyboardShortcut[];
+
+	/**
+	 * Client-side setup hook — called once after the client + provider are
+	 * ready. May return a teardown function called on app unmount.
+	 */
+	clientSetup?(
+		ctx: ClientPluginCtx,
+	):
+		| undefined
+		| void
+		| (() => void)
+		| Promise<undefined | void | (() => void)>;
+
+	// ── Server-side contributions ───────────────────────────────────────────────
+
+	/** TipTap extensions safe for server-side Y.Doc → HTML rendering (no Vue NodeViews). */
+	serverExtensions?: () => AbraTiptapExtension[];
+
+	/**
+	 * Custom cache renderer for non-doc page types. Receives the Y.Doc and
+	 * returns serialisable data for the host's cache. Method shorthand —
+	 * bivariant, so consumer plugins can narrow the `ydoc` parameter to a
+	 * real `Y.Doc` from their own yjs version.
+	 */
+	serverCacheRenderer?(docId: string, ydoc: AbraYDoc): unknown;
+
+	/**
+	 * Server-side background runners (Nitro context, service-role identity).
+	 *
+	 * 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`
+	 * aliases.
+	 */
+	serverRunners?: readonly unknown[];
+}
+
+// ── Context objects ────────────────────────────────────────────────────────────
+
+/**
+ * Context passed to editor-scoped plugin hooks.
+ *
+ * `editor` is the TipTap editor wrapped in whatever ref-like the host uses
+ * (`ShallowRef<Editor | null>` in Vue 3 hosts). Typed as a structural ref to
+ * avoid pulling `vue` into the type closure of plugin consumers that don't
+ * use Vue.
+ */
+export interface EditorPluginCtx<TEditor = unknown> {
+	editor: EditorRefLike<TEditor>;
+	docId: string;
+}
+
+/**
+ * Context passed to drag-handle plugin hooks. Carries the currently-selected
+ * node plus its document position.
+ */
+export interface DragHandlePluginCtx<TEditor = unknown, TNode = unknown>
+	extends EditorPluginCtx<TEditor> {
+	selectedNode: RefLike<
+		{ node: TNode | null; pos: number } | undefined
+	>;
+}
+
+/**
+ * Context passed to `clientSetup`. `abracadabra` is the host's full reactive
+ * state — typed as `unknown` here; app-specific plugin aliases tighten this
+ * to `AbracadabraState` / `ReturnType<typeof useAbracadabra>` / similar.
+ */
+export interface ClientPluginCtx<TState = unknown> {
+	abracadabra: TState;
+}
+
+/** Context passed to command-palette plugin hooks. */
+export interface CommandPaletteCtx<TState = unknown, TTree = unknown> {
+	docId: string | null;
+	/** `useRouter()`'s return value. Typed as `unknown` to avoid a `vue-router` peer dep. */
+	router: unknown;
+	abracadabra: TState;
+	tree: TTree | null;
+}
+
+/** Context passed to mention provider hooks. */
+export interface MentionPluginCtx {
+	docId: string;
+	connectedUsers: readonly CollaborationUser[];
+	rootDoc: AbraYDoc;
+}
+
+// ── Ref-like primitives ────────────────────────────────────────────────────────
+
+/**
+ * Minimal shape of a Vue `Ref`/`ShallowRef`/Solid signal. Defined locally so
+ * the plugin contract doesn't depend on a specific reactivity library.
+ */
+export interface RefLike<T> {
+	value: T;
+}
+
+/** A read-mostly ref for the TipTap editor instance. */
+export type EditorRefLike<TEditor = unknown> = RefLike<TEditor | null>;
+
+// ── Contribution types ────────────────────────────────────────────────────────
+
+export interface AbraMentionProvider {
+	/** Group label shown in the suggestion popup. */
+	label: string;
+	/**
+	 * Method shorthand (not arrow property) — TS treats this position as
+	 * bivariant, so consumer plugins can narrow `ctx` to their own tightened
+	 * mention-context type without contravariance fights.
+	 */
+	getItems(
+		query: string,
+		ctx: MentionPluginCtx,
+	): readonly AbraMentionItem[] | Promise<readonly AbraMentionItem[]>;
+}
+
+export interface AbraMentionItem {
+	id: string;
+	label: string;
+	avatar?: string;
+	color?: string;
+	attrs?: Record<string, unknown>;
+}
+
+export interface AbraAwarenessContribution {
+	/** Namespaced keys this plugin writes, e.g. `['cursor', 'presence:kanban']`. */
+	keys: readonly string[];
+	/**
+	 * Optional Vue component rendered as a presence overlay. Typed as
+	 * `unknown` so the plugin contract stays Vue-free at the type level.
+	 * Concrete consumers cast to `Component` / `DefineComponent` as needed.
+	 */
+	cursorComponent?: unknown;
+}
+
+export interface AbraCommandItem {
+	id: string;
+	label: string;
+	description?: string;
+	icon?: string;
+	group?: string;
+	shortcut?: string;
+	/** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+	when?(ctx: CommandPaletteCtx): boolean;
+	/** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+	handler(ctx: CommandPaletteCtx): void | Promise<void>;
+}
+
+export interface AbraNodePanelSlot {
+	id: string;
+	label: string;
+	icon: string;
+	/** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+	when(ctx: NodePanelCtx): boolean;
+	component: unknown;
+}
+
+export interface NodePanelCtx {
+	childId: string;
+	childDoc: AbraYDoc | null;
+	parentDocId: string;
+	parentType: string | undefined;
+	meta: Record<string, unknown>;
+	tree: unknown;
+}
+
+export interface AbraSettingsPanel {
+	label: string;
+	icon: string;
+	component: unknown;
+}
+
+export interface AbraKeyboardShortcut {
+	/** Key spec, e.g. `'Meta+Shift+K'`, `'Control+Alt+P'`. */
+	key: string;
+	description: string;
+	handler: () => void | Promise<void>;
+}
+
+// ── Collaboration / presence ──────────────────────────────────────────────────
+
+export interface CollaborationUser {
+	name: string;
+	color: string;
+	publicKey?: string;
+	docId?: string;
+}
+
+// ── Server runners ────────────────────────────────────────────────────────────
+
+/**
+ * Cleanup function returned by a runner's `start()`. Called on graceful
+ * server shutdown.
+ */
+export type RunnerCleanup =
+	| (() => void | Promise<void>)
+	| undefined
+	| void;
+
+/**
+ * A named background task that runs inside the host's server process
+ * (Nitro, in `@abraca/nuxt`'s case).
+ *
+ * The runner context is parameterised so each host can extend it with its
+ * own client/provider/storage shapes without the plugin contract dragging
+ * `@abraca/dabra` along.
+ */
+export interface ServerRunnerDefinition<TCtx = ServerRunnerContextBase> {
+	name: string;
+	/** Method shorthand — bivariant, so consumer types can narrow `ctx`. */
+	start(ctx: TCtx): Promise<RunnerCleanup> | RunnerCleanup;
+}
+
+/**
+ * Minimum context every server runner receives. Hosts extend this with
+ * `client`, `wsp`, `rootProvider`, etc.
+ */
+export interface ServerRunnerContextBase {
+	/** Root Y.Doc (the world / hub doc, or the space root doc for space-scoped runners). */
+	rootDoc: AbraYDoc;
+	/** Space ID if this runner is scoped to a space; `null` for hub-scoped runners. */
+	spaceId?: string | null;
+}