@ai-composer/plugin-command 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepak Chopkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,6 @@
+# @ai-composer/plugin-command
+
+/slash command trigger plugin.
+
+See [`docs/`](../../docs/README.md) for guides and API reference.
+

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @ai-composer/plugin-command — `/slash` commands.
+ *
+ * ```ts
+ * import { createAIComposer } from '@ai-composer/core';
+ * import { commandPlugin } from '@ai-composer/plugin-command';
+ *
+ * const editor = createAIComposer({
+ *   plugins: [
+ *     commandPlugin({
+ *       commands: [
+ *         { id: 'summarize', label: 'Summarize', description: 'Summarize the thread' },
+ *         { id: 'translate', label: 'Translate', run: (editor) => { … } },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Commands WITHOUT `run` insert a command node into the document; commands WITH
+ * `run` execute immediately and the trigger run is simply removed.
+ */
+import { type AIComposer, type AIComposerPlugin, type TriggerSearchContext } from '@ai-composer/core';
+export interface SlashCommandDefinition {
+    id: string;
+    label: string;
+    description?: string;
+    /** Immediate action; when omitted the command is inserted as a node. */
+    run?: (editor: AIComposer) => void | Promise<void>;
+    /** Extra payload stored on the node metadata / suggestion data. */
+    data?: Record<string, unknown>;
+}
+export interface CommandPluginOptions {
+    /** Trigger character (default '/'). */
+    trigger?: string;
+    /** Trigger id (default 'command'). */
+    id?: string;
+    /** Available commands. */
+    commands: SlashCommandDefinition[];
+    /** Dynamic command source; overrides `commands`. */
+    search?: (context: TriggerSearchContext) => SlashCommandDefinition[] | Promise<SlashCommandDefinition[]>;
+}
+export declare function commandPlugin(options: CommandPluginOptions): AIComposerPlugin;
+//# 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,sBAAsB,EAAE,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;CAC1G;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CAqE7E"}

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * @ai-composer/plugin-command — `/slash` commands.
+ *
+ * ```ts
+ * import { createAIComposer } from '@ai-composer/core';
+ * import { commandPlugin } from '@ai-composer/plugin-command';
+ *
+ * const editor = createAIComposer({
+ *   plugins: [
+ *     commandPlugin({
+ *       commands: [
+ *         { id: 'summarize', label: 'Summarize', description: 'Summarize the thread' },
+ *         { id: 'translate', label: 'Translate', run: (editor) => { … } },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Commands WITHOUT `run` insert a command node into the document; commands WITH
+ * `run` execute immediately and the trigger run is simply removed.
+ */
+import { createCommandNode, defineTrigger, } from '@ai-composer/core';
+export function commandPlugin(options) {
+    const character = options.trigger ?? '/';
+    const definitions = options.commands ?? [];
+    const toSuggestion = (definition) => ({
+        id: definition.id,
+        label: definition.label,
+        description: definition.description,
+        data: definition.data,
+    });
+    const defaultSearch = (context) => {
+        const query = context.query.trim().toLowerCase().replace(/^\//, '');
+        const matches = definitions.filter((definition) => !query ||
+            definition.label.toLowerCase().includes(query) ||
+            definition.id.toLowerCase().includes(query));
+        return matches.map(toSuggestion);
+    };
+    const select = (item, context) => {
+        const definition = definitions.find((candidate) => candidate.id === item.id);
+        const range = {
+            start: { nodeIndex: context.nodeIndex, offset: context.triggerOffset },
+            end: { nodeIndex: context.nodeIndex, offset: context.endOffset },
+        };
+        if (definition?.run) {
+            // Immediate action: strip the trigger run and run the handler.
+            context.editor.replaceRange(range, []);
+            void definition.run(context.editor);
+            return;
+        }
+        // Command nodes replace the trigger run in the document.
+        context.editor.replaceRange(range, [
+            createCommandNode({
+                id: definition?.id ?? item.id,
+                label: definition?.label ?? item.label,
+                ...(definition?.data ? { metadata: definition.data } : {}),
+            }),
+        ], { trailingSpace: true });
+    };
+    const trigger = defineTrigger({
+        id: options.id ?? 'command',
+        character,
+        type: 'command',
+        search: async (context) => {
+            if (options.search) {
+                const found = await options.search(context);
+                return found.map(toSuggestion);
+            }
+            return defaultSearch(context);
+        },
+        select,
+    });
+    return {
+        name: options.id ?? 'command',
+        version: '0.1.0',
+        triggers: [trigger],
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ai-composer/plugin-command",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@ai-composer/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@ai-composer/core": "workspace:*",
+    "vitest": "^2.1.8"
+  },
+  "module": "./index.js"
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ai-composer/plugin-command",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@ai-composer/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8",
+    "@ai-composer/core": "0.1.0"
+  }
+}

package/project.json

@@ -0,0 +1,56 @@
+{
+  "name": "plugin-command",
+  "$schema": "../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "plugins/command/src",
+  "projectType": "library",
+  "tags": [
+    "scope:plugin",
+    "type:lib"
+  ],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": [
+        "{options.outputPath}"
+      ],
+      "options": {
+        "outputPath": "plugins/command/dist",
+        "main": "plugins/command/src/index.ts",
+        "tsConfig": "plugins/command/tsconfig.lib.json",
+        "rootDir": "plugins/command/src",
+        "assets": [
+          {
+            "input": "../plugins/command",
+            "glob": "*.md",
+            "output": "."
+          }
+        ],
+        "generateExportsIfAbsent": false
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "vitest run --project plugin-command"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": [
+        "{options.outputFile}"
+      ],
+      "options": {
+        "lintFilePatterns": [
+          "plugins/command/**/*.ts",
+          "plugins/command/**/*.tsx"
+        ]
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc -p plugins/command/tsconfig.spec.json --noEmit"
+      }
+    }
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createAIComposer, createPosition, createSelection } from '@ai-composer/core';
+import { commandPlugin } from './index';
+
+function type(editor: ReturnType<typeof createAIComposer>, text: string): void {
+  const current = editor.serialize('text') as string;
+  editor.applyViewUpdate({ nodes: [{ type: 'text', key: 't', text: current + text }] });
+  editor.setSelection(createSelection(createPosition(0, (current + text).length)));
+}
+
+describe('commandPlugin', () => {
+  it('inserts a command node for commands without run()', async () => {
+    const editor = createAIComposer({
+      plugins: [
+        commandPlugin({
+          commands: [
+            { id: 'summarize', label: 'Summarize', description: 'Summarize the thread' },
+          ],
+        }),
+      ],
+    });
+
+    type(editor, '/sum');
+    await vi.waitFor(() => expect(editor.getState().suggestions.length).toBe(1));
+    await editor.acceptSuggestion();
+
+    expect(editor.serialize('text')).toBe('/Summarize ');
+    expect(editor.getValue().nodes).toEqual(
+      expect.arrayContaining([expect.objectContaining({ type: 'command', id: 'summarize' })]),
+    );
+  });
+
+  it('executes run() immediately and removes the trigger run', async () => {
+    const run = vi.fn();
+    const editor = createAIComposer({
+      plugins: [
+        commandPlugin({
+          commands: [{ id: 'clear', label: 'Clear all', run }],
+        }),
+      ],
+    });
+
+    type(editor, 'keep /cl');
+    await vi.waitFor(() => expect(editor.getState().suggestions.length).toBe(1));
+    await editor.acceptSuggestion();
+
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(editor.serialize('text')).toBe('keep ');
+  });
+
+  it('matches on id as well as label', async () => {
+    const editor = createAIComposer({
+      plugins: [
+        commandPlugin({
+          commands: [{ id: 'translate', label: 'Translate to French' }],
+        }),
+      ],
+    });
+    type(editor, '/trans');
+    await vi.waitFor(() => expect(editor.getState().suggestions.length).toBe(1));
+  });
+});

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * @ai-composer/plugin-command — `/slash` commands.
+ *
+ * ```ts
+ * import { createAIComposer } from '@ai-composer/core';
+ * import { commandPlugin } from '@ai-composer/plugin-command';
+ *
+ * const editor = createAIComposer({
+ *   plugins: [
+ *     commandPlugin({
+ *       commands: [
+ *         { id: 'summarize', label: 'Summarize', description: 'Summarize the thread' },
+ *         { id: 'translate', label: 'Translate', run: (editor) => { … } },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Commands WITHOUT `run` insert a command node into the document; commands WITH
+ * `run` execute immediately and the trigger run is simply removed.
+ */
+
+import {
+  createCommandNode,
+  defineTrigger,
+  type DocumentRange,
+
+  type AIComposer,
+  type AIComposerPlugin,
+  type AIComposerTrigger,
+  type SuggestionItem,
+  type TriggerSearchContext,
+  type TriggerSelectContext,
+} from '@ai-composer/core';
+
+export interface SlashCommandDefinition {
+  id: string;
+  label: string;
+  description?: string;
+  /** Immediate action; when omitted the command is inserted as a node. */
+  run?: (editor: AIComposer) => void | Promise<void>;
+  /** Extra payload stored on the node metadata / suggestion data. */
+  data?: Record<string, unknown>;
+}
+
+export interface CommandPluginOptions {
+  /** Trigger character (default '/'). */
+  trigger?: string;
+  /** Trigger id (default 'command'). */
+  id?: string;
+  /** Available commands. */
+  commands: SlashCommandDefinition[];
+  /** Dynamic command source; overrides `commands`. */
+  search?: (context: TriggerSearchContext) => SlashCommandDefinition[] | Promise<SlashCommandDefinition[]>;
+}
+
+export function commandPlugin(options: CommandPluginOptions): AIComposerPlugin {
+  const character = options.trigger ?? '/';
+  const definitions = options.commands ?? [];
+
+  const toSuggestion = (definition: SlashCommandDefinition): SuggestionItem => ({
+    id: definition.id,
+    label: definition.label,
+    description: definition.description,
+    data: definition.data,
+  });
+
+  const defaultSearch = (context: TriggerSearchContext): SuggestionItem[] => {
+    const query = context.query.trim().toLowerCase().replace(/^\//, '');
+    const matches = definitions.filter(
+      (definition) =>
+        !query ||
+        definition.label.toLowerCase().includes(query) ||
+        definition.id.toLowerCase().includes(query),
+    );
+    return matches.map(toSuggestion);
+  };
+
+  const select = (item: SuggestionItem, context: TriggerSelectContext): void => {
+    const definition = definitions.find((candidate) => candidate.id === item.id);
+    const range: DocumentRange = {
+      start: { nodeIndex: context.nodeIndex, offset: context.triggerOffset },
+      end: { nodeIndex: context.nodeIndex, offset: context.endOffset },
+    };
+
+    if (definition?.run) {
+      // Immediate action: strip the trigger run and run the handler.
+      context.editor.replaceRange(range, []);
+      void definition.run(context.editor);
+      return;
+    }
+
+    // Command nodes replace the trigger run in the document.
+    context.editor.replaceRange(
+      range,
+      [
+        createCommandNode({
+          id: definition?.id ?? item.id,
+          label: definition?.label ?? item.label,
+          ...(definition?.data ? { metadata: definition.data } : {}),
+        }),
+      ],
+      { trailingSpace: true },
+    );
+  };
+
+  const trigger: AIComposerTrigger = defineTrigger({
+    id: options.id ?? 'command',
+    character,
+    type: 'command',
+    search: async (context) => {
+      if (options.search) {
+        const found = await options.search(context);
+        return found.map(toSuggestion);
+      }
+      return defaultSearch(context);
+    },
+    select,
+  });
+
+  return {
+    name: options.id ?? 'command',
+    version: '0.1.0',
+    triggers: [trigger],
+  };
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": []
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "vitest.config.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "stripInternal": true,
+    "outDir": "../../dist/plugins/command"
+  },
+  "exclude": [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "vitest.config.ts",
+    "src/test-setup.ts"
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": [
+      "vitest"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "exclude": [
+    "vitest.config.ts"
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'node:path';
+
+export default defineConfig({
+  resolve: {
+      alias: {
+        '@ai-composer/core': resolve(__dirname, '../../packages/core/src/index.ts'),
+      },
+  },
+  test: {
+    name: 'plugin-command',
+    environment: 'node',
+    include: ['src/**/*.test.{ts,tsx}'],
+  },
+});
+