opencode-dynamic-skills 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Type definitions for OpenCode Dynamic Skills Plugin
+ */
+import { ReadyStateMachine } from './lib/ReadyStateMachine';
+/**
+ * PromptRenderer Interface - Provider Pattern for Prompt Injection Formatting
+ *
+ * WHY: Different LLM models have different strengths and preferences for structured data:
+ * - Claude models: trained extensively on XML, prefer structured XML injection
+ * - GPT models: strong JSON parsing, prefer JSON-formatted data
+ * - Other models: may benefit from markdown readability for better context
+ *
+ * The provider pattern allows selecting the appropriate renderer at runtime based on:
+ * - Model preference (configured in modelRenderers)
+ * - Global default (promptRenderer)
+ * - Model detection via client.session.message()
+ *
+ * This abstraction decouples rendering format from tool execution logic,
+ * enabling easy format additions without changing plugin code.
+ */
+type SkillInjectionResult = {
+    skill_name: string;
+    resource_path: string;
+    resource_mimetype: string;
+    content: string;
+};
+type SkillSearchResultInjection = {
+    mode?: 'search' | 'recommend';
+    query: string | string[];
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+    summary: {
+        total: number;
+        matches: number;
+        feedback: string;
+    };
+    recommendations?: Array<{
+        name: string;
+        description: string;
+        score: number;
+        reason: string;
+    }>;
+    guidance?: string;
+    debug?: SkillRegistryDebugInfo;
+};
+type Args = {
+    data: Skill;
+    type: 'Skill';
+} | {
+    data: SkillInjectionResult;
+    type: 'SkillResource';
+} | {
+    data: SkillSearchResultInjection;
+    type: 'SkillSearchResults';
+};
+export interface PromptRenderer {
+    /**
+     * Render an object to a string using the preferred format
+     *
+     * @param data The object to render (typically skill metadata or search results)
+     * @param rootElement Optional element name (used for XML rendering as root tag)
+     * @returns Formatted string ready for prompt injection
+     */
+    render(args: Args): string;
+    /**
+     * The format identifier for this renderer
+     * Used for logging, debugging, and format selection
+     */
+    readonly format: 'json' | 'xml' | 'md';
+}
+/**
+ * Skill resource map type for indexing skill resources
+ *
+ * A Map of relative paths to resource metadata. Used to securely resolve
+ * and access skill resources without allowing path traversal attacks.
+ *
+ * Key: relative path to the resource (e.g., "scripts/build.sh", "references/README.md")
+ * Value: resource metadata
+ *   - absolutePath: absolute filesystem path (pre-validated during skill initialization)
+ *   - mimeType: detected MIME type for proper content handling
+ *
+ * Example:
+ *   Map {
+ *     "scripts/build.sh" => { absolutePath: "/skills/cli/scripts/build.sh", mimeType: "application/x-sh" },
+ *     "references/api.md" => { absolutePath: "/skills/cli/references/api.md", mimeType: "text/markdown" }
+ *   }
+ */
+export type SkillResource = {
+    relativePath: string;
+    absolutePath: string;
+    mimeType: string;
+};
+export type SkillResourceMap = Map<string, Omit<SkillResource, 'relativePath'>>;
+declare const ResourceTypes: readonly ["script", "asset", "reference"];
+type ResourceType = (typeof ResourceTypes)[number];
+/**
+ * Asserts that the provided type is a valid ResourceType
+ */
+export declare const assertIsValidResourceType: (type: string) => asserts type is ResourceType;
+export type MapValue<T> = T extends Map<unknown, infer V> ? V : never;
+export type MapKey<T> = T extends Map<infer K, unknown> ? K : never;
+/**
+ * Skill definition parsed from SKILL.md
+ *
+ * Represents a complete skill including metadata and indexed resources.
+ * Resources are pre-indexed at skill initialization to enable:
+ * - Safe path traversal prevention (all paths are pre-validated)
+ * - Fast lookup by relative path
+ * - MIME type detection for proper content handling
+ */
+export type Skill = {
+    name: string;
+    fullPath: string;
+    toolName: string;
+    description: string;
+    compatibility?: string;
+    allowedTools?: string[];
+    metadata?: Record<string, string>;
+    license?: string;
+    content: string;
+    path: string;
+    scripts: SkillResourceMap;
+    references: SkillResourceMap;
+    assets: SkillResourceMap;
+};
+/**
+ * Text segment from parsed search query
+ */
+export type TextSegment = {
+    text: string;
+    negated: boolean;
+};
+/**
+ * Parsed query structure from search-string
+ */
+export type ParsedSkillQuery = {
+    include: string[];
+    exclude: string[];
+    originalQuery: string[];
+    hasExclusions: boolean;
+    termCount: number;
+};
+/**
+ * Search result with ranking and feedback
+ */
+export type SkillSearchResult = {
+    matches: Skill[];
+    totalMatches: number;
+    totalSkills: number;
+    feedback: string;
+    query: ParsedSkillQuery;
+};
+/**
+ * Ranking metrics for a skill match
+ */
+export type SkillRank = {
+    skill: Skill;
+    nameMatches: number;
+    descMatches: number;
+    totalScore: number;
+};
+/**
+ * Plugin configuration
+ */
+export type PluginConfig = {
+    debug: boolean;
+    basePaths: string[];
+    promptRenderer: 'json' | 'xml' | 'md';
+    modelRenderers?: Record<string, 'json' | 'xml' | 'md'>;
+    slashCommandName: string;
+    enableSkillAliases: boolean;
+};
+export type LogType = 'log' | 'debug' | 'error' | 'warn';
+export type PluginLogger = Record<LogType, (...message: unknown[]) => void>;
+/**
+ * Skill searcher function type
+ */
+export type SkillSearcher = (_query: string | string[]) => SkillSearchResult;
+/**
+ * Skill registry controller interface
+ */
+export type SkillRegistryController = {
+    ready: ReadyStateMachine;
+    skills: Skill[];
+    ids: string[];
+    clear: () => void;
+    delete: (_key: string) => void;
+    has: (_key: string) => boolean;
+    get: (_key: string) => Skill | undefined;
+    set: (_key: string, _skill: Skill) => void;
+};
+export type SkillRegistryDebugInfo = {
+    discovered: number;
+    parsed: number;
+    rejected: number;
+    errors: string[];
+};
+export type SkillRegistry = {
+    initialise: () => Promise<void>;
+    config: PluginConfig;
+    register: (...skillPaths: string[]) => Promise<SkillRegistryDebugInfo>;
+    controller: SkillRegistryController;
+    isSkillPath: (_path: string) => boolean;
+    getToolnameFromSkillPath: (_path: string) => string | null;
+    search: SkillSearcher;
+    debug?: SkillRegistryDebugInfo;
+    logger: PluginLogger;
+};
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "opencode-dynamic-skills",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for dynamic skill loading, slash skill commands, and skill-root-relative resources",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Wu-H-Y/opencode-dynamic-skills"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --target bun && tsc --noEmit false --emitDeclarationOnly --declaration --declarationDir dist",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check ."
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.2.26",
+    "bunfig": "^0.15.6",
+    "dedent": "^1.7.2",
+    "gray-matter": "^4.0.3",
+    "mime": "^4.1.0",
+    "ramda": "^0.32.0",
+    "search-string": "^4.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@types/node": "^25.5.0",
+    "@types/ramda": "^0.31.1",
+    "memfs": "^4.56.11",
+    "oxfmt": "^0.40.0",
+    "oxlint": "^1.55.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}