@stina/extension-api 0.19.1 → 0.20.0

package/src/types.contributions.ts

@@ -0,0 +1,404 @@
+/**
+ * Contribution Types
+ *
+ * Types for extension contributions: settings, panels, providers, tools, commands, prompts.
+ */
+
+import type { LocalizedString } from './types.localization.js'
+import type { ExtensionComponentData } from './types.components.js'
+
+/**
+ * What an extension can contribute to Stina
+ */
+export interface ExtensionContributions {
+  /** User-configurable settings */
+  settings?: SettingDefinition[]
+  /** Tool settings views for UI */
+  toolSettings?: ToolSettingsViewDefinition[]
+  /** Right panel contributions */
+  panels?: PanelDefinition[]
+  /** AI providers */
+  providers?: ProviderDefinition[]
+  /** Tools for Stina to use */
+  tools?: ToolDefinition[]
+  /** Slash commands */
+  commands?: CommandDefinition[]
+  /** Prompt contributions for the system prompt */
+  prompts?: PromptContribution[]
+}
+
+// ============================================================================
+// Settings
+// ============================================================================
+
+/**
+ * Setting definition for the UI
+ */
+export interface SettingDefinition {
+  /** Setting ID (namespaced automatically) */
+  id: string
+  /** Display title */
+  title: string
+  /** Help text */
+  description?: string
+  /** Setting type */
+  type: 'string' | 'number' | 'boolean' | 'select'
+  /** Default value */
+  default?: unknown
+  /** For select type: available options */
+  options?: { value: string; label: string }[]
+  /** For select type: load options from tool */
+  optionsToolId?: string
+  /** Params for options tool */
+  optionsParams?: Record<string, unknown>
+  /** Mapping for options tool response */
+  optionsMapping?: SettingOptionsMapping
+  /** Tool ID for creating a new option */
+  createToolId?: string
+  /** Label for create action */
+  createLabel?: string
+  /** Fields for create form */
+  createFields?: SettingDefinition[]
+  /** Static params always sent to create tool */
+  createParams?: Record<string, unknown>
+  /** Mapping for create tool response */
+  createMapping?: SettingCreateMapping
+  /** Validation rules */
+  validation?: {
+    required?: boolean
+    min?: number
+    max?: number
+    pattern?: string
+  }
+}
+
+/**
+ * Mapping for select field options from tool response
+ */
+export interface SettingOptionsMapping {
+  /** Key for items array in tool result data */
+  itemsKey: string
+  /** Key for option value */
+  valueKey: string
+  /** Key for option label */
+  labelKey: string
+  /** Optional key for description */
+  descriptionKey?: string
+}
+
+/**
+ * Mapping for create tool response
+ */
+export interface SettingCreateMapping {
+  /** Key for result data object */
+  resultKey?: string
+  /** Key for option value (defaults to "id") */
+  valueKey: string
+}
+
+// ============================================================================
+// Tool Settings Views
+// ============================================================================
+
+/**
+ * Tool settings view definition (UI schema)
+ */
+export interface ToolSettingsViewDefinition {
+  /** Unique view ID within the extension */
+  id: string
+  /** Display title */
+  title: string
+  /** Help text */
+  description?: string
+  /** View configuration */
+  view: ToolSettingsView
+  /** Fields for create/edit forms (uses SettingDefinition) */
+  fields?: SettingDefinition[]
+}
+
+/**
+ * Tool settings view types
+ */
+export type ToolSettingsView = ToolSettingsListView | ToolSettingsComponentView
+
+/**
+ * List view backed by tools
+ */
+export interface ToolSettingsListView {
+  /** View kind */
+  kind: 'list'
+  /** Tool ID for listing items */
+  listToolId: string
+  /** Tool ID for fetching details (optional) */
+  getToolId?: string
+  /** Tool ID for creating/updating items (optional) */
+  upsertToolId?: string
+  /** Tool ID for deleting items (optional) */
+  deleteToolId?: string
+  /** Mapping from tool data to UI fields */
+  mapping: ToolSettingsListMapping
+  /** Param name for search query (default: "query") */
+  searchParam?: string
+  /** Param name for limit (default: "limit") */
+  limitParam?: string
+  /** Param name for get/delete ID (default: "id") */
+  idParam?: string
+  /** Static params always sent to list tool */
+  listParams?: Record<string, unknown>
+}
+
+/**
+ * Mapping from tool list data to UI fields
+ */
+export interface ToolSettingsListMapping {
+  /** Key for items array in tool result data */
+  itemsKey: string
+  /** Key for total count in tool result data */
+  countKey?: string
+  /** Key for item ID */
+  idKey: string
+  /** Key for item label */
+  labelKey: string
+  /** Key for item description */
+  descriptionKey?: string
+  /** Key for secondary label */
+  secondaryKey?: string
+}
+
+/**
+ * Component-based tool settings view using the declarative DSL.
+ * Reuses the same structure as PanelComponentView for consistency.
+ */
+export interface ToolSettingsComponentView {
+  /** View kind */
+  kind: 'component'
+  /** Data sources. Keys become scope variables (e.g., "$settings"). */
+  data?: Record<string, ToolSettingsActionDataSource>
+  /** Root component to render */
+  content: ExtensionComponentData
+}
+
+/**
+ * Action-based data source for tool settings.
+ */
+export interface ToolSettingsActionDataSource {
+  /** Action ID to call for fetching data */
+  action: string
+  /** Parameters to pass to the action */
+  params?: Record<string, unknown>
+  /** Event names that trigger refresh */
+  refreshOn?: string[]
+}
+
+// ============================================================================
+// Panels
+// ============================================================================
+
+/**
+ * Panel definition for right panel views
+ */
+export interface PanelDefinition {
+  /** Unique panel ID within the extension */
+  id: string
+  /** Display title */
+  title: string
+  /** Icon name (from huge-icons) */
+  icon?: string
+  /** Panel view schema */
+  view: PanelView
+}
+
+/**
+ * Panel view schema (declarative)
+ */
+export type PanelView = PanelComponentView | PanelUnknownView
+
+export interface PanelUnknownView {
+  /** View kind */
+  kind: string
+  /** Additional view configuration */
+  [key: string]: unknown
+}
+
+/**
+ * Action-based data source for declarative panels.
+ * Uses actions (not tools) to fetch data.
+ */
+export interface PanelActionDataSource {
+  /** Action ID to call for fetching data */
+  action: string
+  /** Parameters to pass to the action */
+  params?: Record<string, unknown>
+  /** Event names that should trigger a refresh of this data */
+  refreshOn?: string[]
+}
+
+/**
+ * Component-based panel view using the declarative DSL.
+ * Data is fetched via actions, content is rendered via ExtensionComponent.
+ */
+export interface PanelComponentView {
+  kind: 'component'
+  /** Data sources available in the panel. Keys become variable names (e.g., "$projects"). */
+  data?: Record<string, PanelActionDataSource>
+  /** Root component to render */
+  content: ExtensionComponentData
+}
+
+// ============================================================================
+// Providers
+// ============================================================================
+
+/**
+ * Provider definition (metadata only, implementation in code)
+ */
+export interface ProviderDefinition {
+  /** Provider ID */
+  id: string
+  /** Display name */
+  name: string
+  /** Description */
+  description?: string
+  /** Suggested default model when creating a new model configuration */
+  suggestedDefaultModel?: string
+  /** Default settings for this provider (e.g., { url: "http://localhost:11434" }) */
+  defaultSettings?: Record<string, unknown>
+  /** Schema for provider-specific configuration UI */
+  configSchema?: ProviderConfigSchema
+}
+
+/**
+ * Schema for provider-specific configuration.
+ * Used to generate UI forms for configuring provider settings.
+ */
+export interface ProviderConfigSchema {
+  /** Property definitions */
+  properties: Record<string, ProviderConfigProperty>
+  /** Display order of properties in UI (optional, defaults to object key order) */
+  order?: string[]
+}
+
+/**
+ * Property types for provider configuration
+ */
+export type ProviderConfigPropertyType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'select'
+  | 'password'
+  | 'url'
+
+/**
+ * Single property in a provider configuration schema.
+ * Defines how a setting should be rendered and validated in the UI.
+ */
+export interface ProviderConfigProperty {
+  /** Property type - determines UI control */
+  type: ProviderConfigPropertyType
+  /** Display label */
+  title: string
+  /** Help text shown below the input */
+  description?: string
+  /** Default value */
+  default?: unknown
+  /** Whether the field is required */
+  required?: boolean
+  /** Placeholder text for input fields */
+  placeholder?: string
+  /** For 'select' type: static options */
+  options?: ProviderConfigSelectOption[]
+  /** Validation rules */
+  validation?: ProviderConfigValidation
+}
+
+/**
+ * Option for select-type properties
+ */
+export interface ProviderConfigSelectOption {
+  /** Value stored in settings */
+  value: string
+  /** Display label */
+  label: string
+}
+
+/**
+ * Validation rules for a property
+ */
+export interface ProviderConfigValidation {
+  /** Regex pattern the value must match */
+  pattern?: string
+  /** Minimum string length */
+  minLength?: number
+  /** Maximum string length */
+  maxLength?: number
+  /** Minimum number value */
+  min?: number
+  /** Maximum number value */
+  max?: number
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+/**
+ * Tool definition (metadata only, implementation in code)
+ */
+export interface ToolDefinition {
+  /** Tool ID */
+  id: string
+  /**
+   * Display name - can be a simple string or localized strings.
+   * @example "Get Weather"
+   * @example { en: "Get Weather", sv: "Hämta väder" }
+   */
+  name: LocalizedString
+  /**
+   * Description for Stina - can be a simple string or localized strings.
+   * Note: The AI always receives the English description (or fallback) for consistency.
+   * Localized descriptions are used for UI display only.
+   * @example "Fetches current weather for a location"
+   * @example { en: "Fetches current weather", sv: "Hämtar aktuellt väder" }
+   */
+  description: LocalizedString
+  /** Parameter schema (JSON Schema) */
+  parameters?: Record<string, unknown>
+}
+
+// ============================================================================
+// Commands
+// ============================================================================
+
+/**
+ * Command definition
+ */
+export interface CommandDefinition {
+  /** Command ID (e.g., "weather" for /weather) */
+  id: string
+  /** Display name */
+  name: string
+  /** Description */
+  description: string
+}
+
+// ============================================================================
+// Prompts
+// ============================================================================
+
+export type PromptSection = 'system' | 'behavior' | 'tools'
+
+export interface PromptContribution {
+  /** Unique ID within the extension */
+  id: string
+  /** Optional title for the prompt chunk */
+  title?: string
+  /** Prompt section placement */
+  section?: PromptSection
+  /** Plain text prompt content */
+  text?: string
+  /** Optional localized prompt content (keyed by locale, e.g. "en", "sv") */
+  i18n?: Record<string, string>
+  /** Optional ordering hint (lower comes first) */
+  order?: number
+}

package/src/types.localization.ts

@@ -0,0 +1,39 @@
+/**
+ * Localization Types
+ *
+ * Types and utilities for localized strings in extensions.
+ */
+
+/**
+ * A string that can be either a simple string or a map of language codes to localized strings.
+ * When a simple string is provided, it's used as the default/fallback value.
+ * When a map is provided, the appropriate language is selected at runtime.
+ *
+ * @example
+ * // Simple string (backwards compatible)
+ * name: "Get Weather"
+ *
+ * @example
+ * // Localized strings
+ * name: { en: "Get Weather", sv: "Hämta väder", de: "Wetter abrufen" }
+ */
+export type LocalizedString = string | Record<string, string>
+
+/**
+ * Resolves a LocalizedString to an actual string value.
+ * @param value The LocalizedString to resolve
+ * @param lang The preferred language code (e.g., "sv", "en")
+ * @param fallbackLang The fallback language code (defaults to "en")
+ * @returns The resolved string value
+ */
+export function resolveLocalizedString(
+  value: LocalizedString,
+  lang: string,
+  fallbackLang = 'en'
+): string {
+  if (typeof value === 'string') {
+    return value
+  }
+  // Try preferred language first, then fallback language, then first available, then empty string
+  return value[lang] ?? value[fallbackLang] ?? Object.values(value)[0] ?? ''
+}

package/src/types.manifest.ts

@@ -0,0 +1,45 @@
+/**
+ * Manifest Types
+ *
+ * Types for extension manifest files (manifest.json).
+ */
+
+import type { Permission } from './types.permissions.js'
+import type { ExtensionContributions } from './types.contributions.js'
+
+/**
+ * Extension manifest format (manifest.json)
+ */
+export interface ExtensionManifest {
+  /** Unique identifier (e.g., "ollama-provider") */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Version string (semver) */
+  version: string
+  /** Short description */
+  description: string
+  /** Author information */
+  author: {
+    name: string
+    url?: string
+  }
+  /** Repository URL */
+  repository?: string
+  /** License identifier */
+  license?: string
+  /** Minimum Stina version required */
+  engines?: {
+    stina: string
+  }
+  /** Supported platforms */
+  platforms?: Platform[]
+  /** Entry point file (relative to extension root) */
+  main: string
+  /** Required permissions */
+  permissions: Permission[]
+  /** What the extension contributes */
+  contributes?: ExtensionContributions
+}
+
+export type Platform = 'web' | 'electron' | 'tui'

package/src/types.permissions.ts

@@ -0,0 +1,48 @@
+/**
+ * Permission Types
+ *
+ * Defines all permission types for extensions.
+ */
+
+export type Permission =
+  | NetworkPermission
+  | StoragePermission
+  | UserDataPermission
+  | CapabilityPermission
+  | SystemPermission
+
+/** Network access permissions */
+export type NetworkPermission =
+  | 'network:*'
+  | `network:localhost`
+  | `network:localhost:${number}`
+  | `network:${string}`
+
+/** Storage permissions */
+export type StoragePermission = 'database.own' | 'storage.local'
+
+/** User data permissions */
+export type UserDataPermission =
+  | 'user.profile.read'
+  | 'user.location.read'
+  | 'chat.history.read'
+  | 'chat.current.read'
+
+/** Capability permissions */
+export type CapabilityPermission =
+  | 'provider.register'
+  | 'tools.register'
+  | 'actions.register'
+  | 'settings.register'
+  | 'commands.register'
+  | 'panels.register'
+  | 'events.emit'
+  | 'scheduler.register'
+  | 'chat.message.write'
+
+/** System permissions */
+export type SystemPermission =
+  | 'files.read'
+  | 'files.write'
+  | 'clipboard.read'
+  | 'clipboard.write'

package/src/types.provider.ts

@@ -0,0 +1,111 @@
+/**
+ * AI Provider Types
+ *
+ * Types for AI providers, models, and chat interactions.
+ */
+
+import type { ToolDefinition } from './types.contributions.js'
+
+/**
+ * AI provider implementation
+ */
+export interface AIProvider {
+  /** Provider ID (must match manifest) */
+  id: string
+  /** Display name */
+  name: string
+
+  /**
+   * Get available models from this provider
+   * @param options Optional settings for the provider (e.g., URL)
+   */
+  getModels(options?: GetModelsOptions): Promise<ModelInfo[]>
+
+  /**
+   * Chat completion with streaming
+   */
+  chat(
+    messages: ChatMessage[],
+    options: ChatOptions
+  ): AsyncGenerator<StreamEvent, void, unknown>
+
+  /**
+   * Optional: Generate embeddings
+   */
+  embed?(texts: string[]): Promise<number[][]>
+}
+
+/**
+ * Model information
+ */
+export interface ModelInfo {
+  /** Model ID */
+  id: string
+  /** Display name */
+  name: string
+  /** Description */
+  description?: string
+  /** Context window size */
+  contextLength?: number
+}
+
+/**
+ * Chat message
+ */
+export interface ChatMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool'
+  content: string
+  /** For assistant messages: tool calls made by the model */
+  tool_calls?: ToolCall[]
+  /** For tool messages: the ID of the tool call this is a response to */
+  tool_call_id?: string
+}
+
+/**
+ * A tool call made by the model
+ */
+export interface ToolCall {
+  /** Unique ID for this tool call */
+  id: string
+  /** Tool name/ID to invoke */
+  name: string
+  /** Arguments for the tool (as parsed object) */
+  arguments: Record<string, unknown>
+}
+
+/**
+ * Options for chat completion
+ */
+export interface ChatOptions {
+  /** Model to use */
+  model?: string
+  /** Temperature (0-1) */
+  temperature?: number
+  /** Maximum tokens to generate */
+  maxTokens?: number
+  /** Abort signal for cancellation */
+  signal?: AbortSignal
+  /** Provider-specific settings from model configuration */
+  settings?: Record<string, unknown>
+  /** Available tools for this request */
+  tools?: ToolDefinition[]
+}
+
+/**
+ * Options for getModels
+ */
+export interface GetModelsOptions {
+  /** Provider-specific settings (e.g., URL for Ollama) */
+  settings?: Record<string, unknown>
+}
+
+/**
+ * Streaming events from chat
+ */
+export type StreamEvent =
+  | { type: 'content'; text: string }
+  | { type: 'thinking'; text: string }
+  | { type: 'tool_start'; name: string; input: unknown; toolCallId: string }
+  | { type: 'tool_end'; name: string; output: unknown; toolCallId: string }
+  | { type: 'done'; usage?: { inputTokens: number; outputTokens: number } }
+  | { type: 'error'; message: string }