@vemjs/plugin-api 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @vemjs/plugin-api
+
+## 0.1.1
+
+### Patch Changes
+
+- 0498765: chore: release infrastructure, package metadata, and documentation scaffolding
+
+  This changeset covers all release preparation work for the initial 0.1.0 publish:
+
+  **Package metadata** — Added `license`, `repository`, `keywords`, and `publishConfig` fields to
+  all four packages so they display correctly on npmjs.com with proper source links, license badges,
+  and searchable tags.
+
+  **CI/CD pipeline** — Rewrote `.github/workflows/ci.yml` and `release.yml`:
+
+  - `quality` job: build → test → lint (oxlint) → dead-code scan (knip) on every PR and push
+  - `publish` job: automatic `changeset publish` to npm on every merge to `main` via
+    `changesets/action@v1` using the `NPM_TOKEN` org secret
+
+  **Changesets** — Initialized `.changeset/` with a `config.json` configured for public access and
+  patch-level internal dependency updates, enabling a fully automated release flow.
+
+  **Tooling** — Added `knip.config.ts` (dead-code detection), `oxlintrc.json` (TypeScript-aware
+  lint rules), `.lintstagedrc.json` (auto-fix staged files on commit), and updated root
+  `package.json` scripts: `build`, `test`, `lint`, `knip`, `changeset`, `version-packages`,
+  `release`.
+
+  **Dependabot** — Configured weekly npm dependency scanning with dev/prod groups and
+  `@vectojs/*` major-version pin to avoid upstream breaking changes.
+
+  **Repository** — Updated root `README.md` with CI/npm/license badges and package table.
+  Updated `SECURITY.md` with all four `@vemjs/*` packages and coordinated-disclosure guidance.
+  Added GitHub topics (vim, editor, typescript, vectojs, canvas, modal-editing, lsp) and branch
+  protection requiring the `quality` status check before merging to `main`.
+
+  **Build hygiene** — Cleaned all `dist/` directories and rebuilt from source to ensure no
+  test artefacts are included in published tarballs. Verified `knip` reports zero issues.
+
+- Updated dependencies [0498765]
+- Updated dependencies [3fa4848]
+  - @vemjs/core@0.2.0
+
+## 0.1.0
+
+### Features
+
+- `PluginRegistry` — plugin activation lifecycle manager
+- `PluginContext` — plugin SDK: `registerKeybinding`, `registerCommand`, `onDidOpenBuffer`, `onDidChangeBuffer`, `onDidChangeMode`
+- Chord-based custom keybinding with prefix-match buffering and Vim-native keystroke replay fallback

package/README.md

@@ -0,0 +1,151 @@
+# @vemjs/plugin-api
+
+[![npm version](https://img.shields.io/npm/v/@vemjs/plugin-api.svg)](https://www.npmjs.com/package/@vemjs/plugin-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The official Plugin SDK and life-cycle registration layer for the **Vem Editor**. It allows third-party developers to register custom keybindings, hook into buffer updates, intercept mode transitions, and build complex chords or commands.
+
+## Features
+
+- **Standardized Plugin Interface**: Clean activation/deactivation lifecycles matching the `@vemjs/core` environment.
+- **Keybinding Registration**: Dynamically override editor shortcuts or register command chords in specific modes.
+- **Event Observers**: Hook into buffer creation (`onDidOpenBuffer`), text mutations (`onDidChangeBuffer`), and mode changes (`onDidChangeMode`).
+- **Command Management**: Define global editor commands that can be invoked via the Command Bar or mapped to shortcuts.
+
+## Installation
+
+```bash
+bun add @vemjs/plugin-api
+# or via npm
+npm install @vemjs/plugin-api
+```
+
+## Quick Start
+
+Create and activate a plugin that adds a custom keystroke in NORMAL mode:
+
+```typescript
+import { VemEditorState } from '@vemjs/core';
+import { PluginRegistry, type VemPlugin } from '@vemjs/plugin-api';
+
+const editor = new VemEditorState('initial text');
+const registry = new PluginRegistry(editor);
+
+// Define a plugin
+const myPlugin: VemPlugin = {
+  name: 'my-custom-shortcuts',
+  version: '1.0.0',
+  activate(context) {
+    // Register a command
+    context.registerCommand('custom.hello', () => {
+      console.log('Hello from command!');
+    });
+
+    // Bind keys (e.g. pressing 'gh' in NORMAL mode fires command)
+    context.registerKeybinding('NORMAL', 'gh', 'custom.hello');
+  },
+};
+
+// Register & Activate
+registry.register(myPlugin);
+
+// Pressing keys in sequence triggers the command
+editor.input('g');
+editor.input('h'); // Console prints: "Hello from command!"
+```
+
+## API Reference
+
+### `VemPlugin`
+
+Interface representing a loadable plugin.
+
+- `name: string`: Unique package identifier.
+- `version: string`: Semantic version string.
+- `activate(context: PluginContext): void`: Called by the engine when loading the plugin.
+- `deactivate?(): void`: Optional cleanup callback.
+
+### `PluginContext`
+
+Provided to `activate(context)` to interact with the editor.
+
+- `editorState: VemEditorState`: Access to core editor properties.
+- `registerCommand(commandName: string, callback: () => void): void`: Registers a function callback globally.
+- `registerKeybinding(mode: EditorMode, keys: string, commandName: string): void`: Binds a specific key combination (or chord prefix) in the specified mode to a registered command.
+- `onDidOpenBuffer(cb: () => void): void`: Subscribes to buffer open events.
+- `onDidChangeBuffer(cb: () => void): void`: Subscribes to buffer content mutation events.
+- `onDidChangeMode(cb: (mode: EditorMode) => void): void`: Subscribes to mode change notifications.
+
+### `PluginRegistry`
+
+Manager executing plugin installation.
+
+- `constructor(editorState: VemEditorState)`: Creates the registry bound to an editor instance.
+- `register(plugin: VemPlugin): void`: Registers context callbacks and triggers the plugin's `activate` method.
+- `executeCommand(name: string): void`: Runs the callback associated with a command.
+
+---
+
+## Plugin Development Guide
+
+### Naming Conventions
+
+For consistency in the ecosystem, plugins should be named using the prefix `vem-plugin-` when published as standalone packages, or `@vemjs/plugin-<name>` if they are officially maintained packages:
+
+- Third-party: `vem-plugin-format-on-save`
+- Official: `@vemjs/plugin-treesitter`
+
+### Complete Example: Format-on-Save
+
+Here is a full plugin implementation that automatically trims trailing whitespace whenever a buffer changes (an automated linter/formatter behavior):
+
+```typescript
+import { type VemPlugin } from '@vemjs/plugin-api';
+
+export const FormatOnSavePlugin: VemPlugin = {
+  name: 'format-on-save',
+  version: '1.0.0',
+  activate(context) {
+    let isFormatting = false;
+
+    context.onDidChangeBuffer(() => {
+      // Avoid recursive change loops
+      if (isFormatting) return;
+
+      const editor = context.editorState;
+      const originalText = editor.getText();
+      const lines = originalText.split('\n');
+
+      // Trim trailing spaces
+      const formattedLines = lines.map((line) => line.trimEnd());
+      const formattedText = formattedLines.join('\n');
+
+      if (formattedText !== originalText) {
+        isFormatting = true;
+        // Access buffer to set raw text
+        editor.getBuffer().setText(formattedText);
+        isFormatting = false;
+        console.log('[FormatOnSave] Trimmed trailing whitespaces');
+      }
+    });
+  },
+};
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    Engine[VemEditorState] <--> Context[PluginContext]
+    Context --> Registry[PluginRegistry]
+    Registry --> Plugin1[VemPlugin A]
+    Registry --> Plugin2[VemPlugin B]
+```
+
+## Contributing
+
+Please review [CONTRIBUTING.md](../../CONTRIBUTING.md) for details on our workflow and engineering guidelines.
+
+## License
+
+This package is licensed under the MIT License - see the LICENSE file for details.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { VemEditorState } from '@vemjs/core';
+import type { EditorMode } from '@vemjs/core';
+export interface VemPlugin {
+    name: string;
+    version: string;
+    activate(context: PluginContext): void;
+    deactivate?(): void;
+}
+export interface PluginContext {
+    editorState: VemEditorState;
+    registerCommand(commandName: string, callback: () => void): void;
+    registerKeybinding(mode: EditorMode, keys: string, commandName: string): void;
+    onDidOpenBuffer(cb: () => void): void;
+    onDidChangeBuffer(cb: () => void): void;
+    onDidChangeMode(cb: (mode: EditorMode) => void): void;
+}
+export declare class PluginRegistry {
+    private plugins;
+    private commands;
+    private editorState;
+    constructor(editorState: VemEditorState);
+    register(plugin: VemPlugin): void;
+    executeCommand(name: string): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,cAAc,CAAC;IAC5B,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACjE,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9E,eAAe,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACtC,iBAAiB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACxC,eAAe,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;CACvD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,WAAW,CAAiB;gBAExB,WAAW,EAAE,cAAc;IAIhC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAiBjC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAQ1C"}

package/dist/index.js

@@ -0,0 +1,34 @@
+import { VemEditorState } from '@vemjs/core';
+export class PluginRegistry {
+    plugins = new Map();
+    commands = new Map();
+    editorState;
+    constructor(editorState) {
+        this.editorState = editorState;
+    }
+    register(plugin) {
+        const context = {
+            editorState: this.editorState,
+            registerCommand: (name, cb) => this.commands.set(name, cb),
+            registerKeybinding: (mode, keys, commandName) => {
+                this.editorState.registerKeybinding(mode, keys, commandName);
+            },
+            onDidOpenBuffer: (cb) => this.editorState.onDidOpenBuffer(cb),
+            onDidChangeBuffer: (cb) => this.editorState.onDidChangeBuffer(cb),
+            onDidChangeMode: (cb) => this.editorState.onDidChangeMode(cb),
+        };
+        plugin.activate(context);
+        this.plugins.set(plugin.name, plugin);
+        console.log(`Plugin [${plugin.name}] activated.`);
+    }
+    executeCommand(name) {
+        const cmd = this.commands.get(name);
+        if (cmd) {
+            cmd();
+        }
+        else {
+            console.warn(`Command [${name}] not found.`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAmB7C,MAAM,OAAO,cAAc;IACjB,OAAO,GAA2B,IAAI,GAAG,EAAE,CAAC;IAC5C,QAAQ,GAA4B,IAAI,GAAG,EAAE,CAAC;IAC9C,WAAW,CAAiB;IAEpC,YAAY,WAA2B;QACrC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAEM,QAAQ,CAAC,MAAiB;QAC/B,MAAM,OAAO,GAAkB;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,eAAe,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1D,kBAAkB,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE;gBAC9C,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;YAC/D,CAAC;YACD,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC;YAC7D,iBAAiB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACjE,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC;SAC9D,CAAC;QAEF,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,IAAI,cAAc,CAAC,CAAC;IACpD,CAAC;IAEM,cAAc,CAAC,IAAY;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,EAAE,CAAC;QACR,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,YAAY,IAAI,cAAc,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@vemjs/plugin-api",
+  "version": "0.1.0",
+  "description": "SDK interfaces for 3rd-party plugins on the Vem editor",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@vemjs/core": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'bun:test';
+import { VemEditorState } from '@vemjs/core';
+import { PluginRegistry, type VemPlugin } from './index';
+
+describe('Plugin System', () => {
+  it('should register and activate a plugin', () => {
+    const editor = new VemEditorState('test content');
+    const registry = new PluginRegistry(editor);
+
+    let activated = false;
+    const testPlugin: VemPlugin = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      activate(_context) {
+        activated = true;
+      },
+    };
+
+    registry.register(testPlugin);
+    expect(activated).toBe(true);
+  });
+
+  it('should execute registered custom commands and intercept custom keybindings', () => {
+    const editor = new VemEditorState('hello');
+    const registry = new PluginRegistry(editor);
+
+    let executed = false;
+    const testPlugin: VemPlugin = {
+      name: 'chord-plugin',
+      version: '1.0.0',
+      activate(context) {
+        context.registerCommand('testCmd', () => {
+          executed = true;
+        });
+        context.registerKeybinding('NORMAL', ' gw', 'testCmd');
+      },
+    };
+
+    registry.register(testPlugin);
+
+    editor.onExecutePluginCommand((name) => {
+      registry.executeCommand(name);
+    });
+
+    // Type chord: Space, g, w
+    editor.handleKey(' ');
+    editor.handleKey('g');
+    editor.handleKey('w');
+
+    expect(executed).toBe(true);
+  });
+
+  it('should support buffer change event listeners', () => {
+    const editor = new VemEditorState('line1');
+    const registry = new PluginRegistry(editor);
+
+    let changeCount = 0;
+    const testPlugin: VemPlugin = {
+      name: 'buffer-listener',
+      version: '1.0.0',
+      activate(context) {
+        context.onDidChangeBuffer(() => {
+          changeCount++;
+        });
+      },
+    };
+
+    registry.register(testPlugin);
+
+    // Modify the buffer
+    editor.handleKey('i');
+    editor.handleKey('a');
+    editor.handleKey('Escape');
+
+    expect(changeCount).toBe(1);
+  });
+
+  it('should support mode change event listeners', () => {
+    const editor = new VemEditorState('line1');
+    const registry = new PluginRegistry(editor);
+
+    let lastMode = 'NORMAL';
+    const testPlugin: VemPlugin = {
+      name: 'mode-listener',
+      version: '1.0.0',
+      activate(context) {
+        context.onDidChangeMode((mode) => {
+          lastMode = mode;
+        });
+      },
+    };
+
+    registry.register(testPlugin);
+
+    // Change mode
+    editor.handleKey('i');
+    expect(lastMode).toBe('INSERT');
+
+    editor.handleKey('Escape');
+    expect(lastMode).toBe('NORMAL');
+  });
+});

package/src/index.ts

@@ -0,0 +1,54 @@
+import { VemEditorState } from '@vemjs/core';
+import type { EditorMode } from '@vemjs/core';
+
+export interface VemPlugin {
+  name: string;
+  version: string;
+  activate(context: PluginContext): void;
+  deactivate?(): void;
+}
+
+export interface PluginContext {
+  editorState: VemEditorState;
+  registerCommand(commandName: string, callback: () => void): void;
+  registerKeybinding(mode: EditorMode, keys: string, commandName: string): void;
+  onDidOpenBuffer(cb: () => void): void;
+  onDidChangeBuffer(cb: () => void): void;
+  onDidChangeMode(cb: (mode: EditorMode) => void): void;
+}
+
+export class PluginRegistry {
+  private plugins: Map<string, VemPlugin> = new Map();
+  private commands: Map<string, () => void> = new Map();
+  private editorState: VemEditorState;
+
+  constructor(editorState: VemEditorState) {
+    this.editorState = editorState;
+  }
+
+  public register(plugin: VemPlugin): void {
+    const context: PluginContext = {
+      editorState: this.editorState,
+      registerCommand: (name, cb) => this.commands.set(name, cb),
+      registerKeybinding: (mode, keys, commandName) => {
+        this.editorState.registerKeybinding(mode, keys, commandName);
+      },
+      onDidOpenBuffer: (cb) => this.editorState.onDidOpenBuffer(cb),
+      onDidChangeBuffer: (cb) => this.editorState.onDidChangeBuffer(cb),
+      onDidChangeMode: (cb) => this.editorState.onDidChangeMode(cb),
+    };
+
+    plugin.activate(context);
+    this.plugins.set(plugin.name, plugin);
+    console.log(`Plugin [${plugin.name}] activated.`);
+  }
+
+  public executeCommand(name: string): void {
+    const cmd = this.commands.get(name);
+    if (cmd) {
+      cmd();
+    } else {
+      console.warn(`Command [${name}] not found.`);
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts"]
+}