alma-plugin-api 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# alma-plugin-api
+
+TypeScript type definitions for developing [Alma](https://github.com/yetone/alma) plugins.
+
+## Installation
+
+```bash
+npm install -D alma-plugin-api
+```
+
+## Usage
+
+```typescript
+import type { PluginContext, PluginActivation } from 'alma-plugin-api';
+
+export async function activate(context: PluginContext): Promise<PluginActivation> {
+    const { logger, tools, commands, ui, settings } = context;
+
+    logger.info('Plugin activated!');
+
+    // Register a tool
+    const toolDisposable = tools.register('my-plugin.hello', {
+        name: 'Hello',
+        description: 'Say hello',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Name to greet' }
+            },
+            required: ['name']
+        },
+        execute: async (args) => {
+            const { name } = args as { name: string };
+            return { message: `Hello, ${name}!` };
+        }
+    });
+
+    // Register a command
+    const commandDisposable = commands.register('my-plugin.greet', async () => {
+        ui.showNotification('Hello from my plugin!', { type: 'info' });
+    });
+
+    return {
+        dispose: () => {
+            logger.info('Plugin deactivated');
+            toolDisposable.dispose();
+            commandDisposable.dispose();
+        }
+    };
+}
+```
+
+## Available APIs
+
+### Core APIs
+
+| API | Description |
+|-----|-------------|
+| `logger` | Logging utilities (info, warn, error, debug) |
+| `tools` | Register AI-usable tools |
+| `commands` | Register command palette commands |
+| `hooks` | Subscribe to lifecycle events |
+| `ui` | UI utilities (notifications, status bar) |
+| `settings` | Read/write plugin settings |
+| `chat` | Access chat threads and messages |
+| `transform` | Transform prompts and messages |
+| `themes` | Register and manage themes |
+| `storage` | Persistent key-value storage |
+| `secrets` | Secure storage for sensitive data |
+
+### Plugin Info
+
+| Property | Description |
+|----------|-------------|
+| `pluginId` | Unique identifier of the plugin |
+| `pluginPath` | Filesystem path to the plugin |
+| `globalState` | Persistent state across sessions |
+| `workspaceState` | Workspace-scoped state |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Alma Plugin API
+ *
+ * TypeScript type definitions for developing Alma plugins.
+ * These types are provided by the Alma runtime when plugins are loaded.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A disposable resource that can be cleaned up.
+ */
+export interface Disposable {
+    dispose(): void;
+}
+/**
+ * Result returned from plugin activation.
+ */
+export interface PluginActivation {
+    dispose(): void;
+}
+/**
+ * Logging utilities for plugins.
+ */
+export interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Definition for a tool that can be used by the AI assistant.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    execute: (args: unknown) => Promise<unknown>;
+}
+/**
+ * API for registering and managing AI tools.
+ */
+export interface ToolsAPI {
+    register(id: string, tool: ToolDefinition): Disposable;
+    unregister(id: string): void;
+}
+/**
+ * API for registering command palette commands.
+ */
+export interface CommandsAPI {
+    register(id: string, handler: () => Promise<void> | void): Disposable;
+    execute(id: string, ...args: unknown[]): Promise<void>;
+}
+/**
+ * Options for hook registration.
+ */
+export interface HookOptions {
+    priority?: number;
+}
+/**
+ * API for subscribing to lifecycle events.
+ */
+export interface HooksAPI {
+    register<TInput, TOutput>(hookName: string, handler: (input: TInput, output: TOutput) => void | Promise<void>, options?: HookOptions): Disposable;
+}
+/**
+ * Options for showing notifications.
+ */
+export interface NotificationOptions {
+    type?: 'info' | 'success' | 'warning' | 'error';
+    duration?: number;
+}
+/**
+ * A status bar item that can display information.
+ */
+export interface StatusBarItem {
+    id: string;
+    text: string;
+    tooltip?: string;
+    command?: string;
+    alignment: 'left' | 'right';
+    priority: number;
+    show(): void;
+    hide(): void;
+    dispose(): void;
+}
+/**
+ * Options for creating a status bar item.
+ */
+export interface StatusBarItemOptions {
+    id?: string;
+    alignment?: 'left' | 'right';
+    priority?: number;
+}
+/**
+ * Theme change event handler.
+ */
+export interface ThemeChangeHandler {
+    onChange(callback: (theme: Theme) => void): Disposable;
+}
+/**
+ * UI utilities for plugins.
+ */
+export interface UIAPI {
+    showNotification(message: string, options?: NotificationOptions): void;
+    createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem;
+    theme: ThemeChangeHandler;
+}
+/**
+ * API for reading and writing plugin settings.
+ */
+export interface SettingsAPI {
+    get<T>(key: string): T | undefined;
+    get<T>(key: string, defaultValue: T): T;
+    set(key: string, value: unknown): Promise<void>;
+    onChange(key: string, callback: (value: unknown) => void): Disposable;
+    onDidChange(callback: (key?: string) => void): Disposable;
+}
+/**
+ * A chat message.
+ */
+export interface ChatMessage {
+    id: string;
+    threadId: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    createdAt: string;
+}
+/**
+ * A chat thread/conversation.
+ */
+export interface ChatThread {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * API for accessing chat threads and messages.
+ */
+export interface ChatAPI {
+    onMessage(callback: (message: ChatMessage) => void): Disposable;
+    getMessages(threadId: string): Promise<ChatMessage[]>;
+    getCurrentThread(): Promise<ChatThread | null>;
+}
+/**
+ * API for transforming messages and prompts.
+ */
+export interface TransformAPI {
+    registerSystemPrompt(id: string, transformer: (prompt: string) => string | Promise<string>): Disposable;
+    registerUserMessage(id: string, transformer: (message: string) => string | Promise<string>): Disposable;
+}
+/**
+ * Color definitions for a theme.
+ */
+export interface ThemeColors {
+    background: string;
+    foreground: string;
+    primary: string;
+    secondary?: string;
+    accent?: string;
+    muted?: string;
+    border?: string;
+    error?: string;
+    warning?: string;
+    success?: string;
+    info?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * A theme definition.
+ */
+export interface Theme {
+    id: string;
+    label: string;
+    type: 'dark' | 'light';
+    colors: ThemeColors;
+}
+/**
+ * API for registering and managing themes.
+ */
+export interface ThemesAPI {
+    register(theme: Theme): Disposable;
+    getCurrent(): Theme | null;
+    apply(themeId: string): Promise<void>;
+}
+/**
+ * Persistent key-value storage for plugins.
+ */
+export interface StorageAPI {
+    get<T>(key: string): T | undefined;
+    get<T>(key: string, defaultValue: T): T;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): string[];
+}
+/**
+ * Secure storage for sensitive data like API keys.
+ */
+export interface SecretsAPI {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * The main context object passed to plugins during activation.
+ * Provides access to all Alma APIs.
+ */
+export interface PluginContext {
+    logger: Logger;
+    tools: ToolsAPI;
+    commands: CommandsAPI;
+    hooks: HooksAPI;
+    ui: UIAPI;
+    settings: SettingsAPI;
+    chat: ChatAPI;
+    transform: TransformAPI;
+    themes: ThemesAPI;
+    storage: StorageAPI;
+    secrets: SecretsAPI;
+    pluginId: string;
+    pluginPath: string;
+    globalState: Map<string, unknown>;
+    workspaceState: Map<string, unknown>;
+}
+/**
+ * The activation function that plugins must export.
+ *
+ * @example
+ * ```typescript
+ * import type { PluginContext, PluginActivation } from 'alma-plugin-api';
+ *
+ * export async function activate(context: PluginContext): Promise<PluginActivation> {
+ *     context.logger.info('Plugin activated!');
+ *
+ *     return {
+ *         dispose: () => {
+ *             context.logger.info('Plugin deactivated');
+ *         }
+ *     };
+ * }
+ * ```
+ */
+export type ActivateFunction = (context: PluginContext) => Promise<PluginActivation>;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Alma Plugin API
+ *
+ * TypeScript type definitions for developing Alma plugins.
+ * These types are provided by the Alma runtime when plugins are loaded.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "alma-plugin-api",
+    "version": "0.1.0",
+    "description": "TypeScript type definitions for Alma plugin development",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "alma",
+        "plugin",
+        "api",
+        "types",
+        "typescript"
+    ],
+    "author": {
+        "name": "Alma Team",
+        "email": "hello@alma.now"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/yetone/alma-plugins.git",
+        "directory": "packages/plugin-api"
+    },
+    "homepage": "https://github.com/yetone/alma-plugins#readme",
+    "devDependencies": {
+        "typescript": "^5.0.0"
+    }
+}