@magnolia/skill-loader 0.1.0-preview.1

package/dist/parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @magnolia/skill-loader - Frontmatter Parser
+ *
+ * Parses skill files with YAML frontmatter into Skill objects.
+ */
+import { Skill, SkillMetadata } from './types.js';
+/**
+ * Parse a skill file content into a Skill object.
+ *
+ * @param content - The raw file content (with frontmatter)
+ * @param filename - Optional filename for deriving the skill name
+ * @returns Parsed Skill object
+ * @throws SkillLoaderError if parsing fails
+ */
+export declare function parseSkillFile(content: string, filename?: string): Skill;
+/**
+ * Create a skill programmatically.
+ *
+ * @param name - Unique identifier for the skill
+ * @param content - The prompt content
+ * @param metadata - Optional metadata for filtering
+ * @returns A Skill object
+ */
+export declare function createSkill(name: string, content: string, metadata?: Partial<SkillMetadata>): Skill;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAQpE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAoCxE;AA2DD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,KAAK,CAOP"}

package/dist/parser.js

@@ -0,0 +1,110 @@
+/**
+ * @magnolia/skill-loader - Frontmatter Parser
+ *
+ * Parses skill files with YAML frontmatter into Skill objects.
+ */
+import { parse as parseYaml } from 'yaml';
+import { SkillLoaderError } from './types.js';
+/**
+ * Regex to match YAML frontmatter at the start of a file.
+ * Matches content between --- delimiters.
+ */
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/**
+ * Parse a skill file content into a Skill object.
+ *
+ * @param content - The raw file content (with frontmatter)
+ * @param filename - Optional filename for deriving the skill name
+ * @returns Parsed Skill object
+ * @throws SkillLoaderError if parsing fails
+ */
+export function parseSkillFile(content, filename) {
+    try {
+        const frontmatterMatch = content.match(FRONTMATTER_REGEX);
+        let metadata = {};
+        let skillContent;
+        if (frontmatterMatch) {
+            const frontmatterYaml = frontmatterMatch[1];
+            metadata = parseYaml(frontmatterYaml) || {};
+            skillContent = content.slice(frontmatterMatch[0].length).trim();
+        }
+        else {
+            // No frontmatter, entire content is the skill content
+            skillContent = content.trim();
+        }
+        // Normalize metadata
+        const normalizedMetadata = normalizeMetadata(metadata);
+        // Derive name from metadata or filename
+        const name = deriveName(normalizedMetadata, filename);
+        return {
+            name,
+            description: normalizedMetadata.description,
+            content: skillContent,
+            metadata: normalizedMetadata,
+        };
+    }
+    catch (error) {
+        throw new SkillLoaderError(`Failed to parse skill file${filename ? `: ${filename}` : ''}`, 'PARSE_ERROR', filename, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Normalize metadata, handling legacy field names.
+ */
+function normalizeMetadata(raw) {
+    const metadata = { ...raw };
+    // Support 'magnolia' as legacy field name for 'version'
+    if (metadata.magnolia && !metadata.version) {
+        metadata.version = String(metadata.magnolia);
+    }
+    // Ensure arrays are properly typed
+    if (metadata.targets && !Array.isArray(metadata.targets)) {
+        metadata.targets = [String(metadata.targets)];
+    }
+    if (metadata.tags && !Array.isArray(metadata.tags)) {
+        metadata.tags = [String(metadata.tags)];
+    }
+    if (metadata.requires && !Array.isArray(metadata.requires)) {
+        metadata.requires = [String(metadata.requires)];
+    }
+    // Ensure priority is a number
+    if (metadata.priority !== undefined) {
+        metadata.priority = Number(metadata.priority) || 0;
+    }
+    return metadata;
+}
+/**
+ * Derive the skill name from metadata or filename.
+ */
+function deriveName(metadata, filename) {
+    // Use explicit name from metadata if provided
+    if (metadata.name && typeof metadata.name === 'string') {
+        return metadata.name;
+    }
+    // Derive from filename
+    if (filename) {
+        // Remove extension(s) like .prompt.md
+        return filename
+            .replace(/\.prompt\.md$/i, '')
+            .replace(/\.md$/i, '')
+            .replace(/\.[^.]+$/, '');
+    }
+    // Fallback to 'unnamed'
+    return 'unnamed';
+}
+/**
+ * Create a skill programmatically.
+ *
+ * @param name - Unique identifier for the skill
+ * @param content - The prompt content
+ * @param metadata - Optional metadata for filtering
+ * @returns A Skill object
+ */
+export function createSkill(name, content, metadata) {
+    return {
+        name,
+        description: metadata?.description,
+        content: content.trim(),
+        metadata: normalizeMetadata(metadata || {}),
+    };
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

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

package/dist/sources/directory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @magnolia/skill-loader - Directory Source Loader
+ *
+ * Loads skills from a directory using glob patterns.
+ */
+import { Skill } from '../types.js';
+/** Default pattern for skill files (recursive to support subdirectories) */
+export declare const DEFAULT_PATTERN = "**/*.prompt.md";
+/**
+ * Load skills from a directory.
+ *
+ * @param dirPath - Path to the directory
+ * @param pattern - Glob pattern for matching files (default: '*.prompt.md')
+ * @returns Array of parsed Skills
+ * @throws SkillLoaderError if directory cannot be read
+ */
+export declare function loadSkillsFromDirectory(dirPath: string, pattern?: string): Promise<Skill[]>;
+//# sourceMappingURL=directory.d.ts.map

package/dist/sources/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/sources/directory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,EAAoB,MAAM,aAAa,CAAC;AAGtD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAwB,GAChC,OAAO,CAAC,KAAK,EAAE,CAAC,CAkDlB"}

package/dist/sources/directory.js

@@ -0,0 +1,57 @@
+/**
+ * @magnolia/skill-loader - Directory Source Loader
+ *
+ * Loads skills from a directory using glob patterns.
+ */
+import { glob } from 'glob';
+import { join, isAbsolute } from 'node:path';
+import { SkillLoaderError } from '../types.js';
+import { loadSkillFromFile } from './file.js';
+/** Default pattern for skill files (recursive to support subdirectories) */
+export const DEFAULT_PATTERN = '**/*.prompt.md';
+/**
+ * Load skills from a directory.
+ *
+ * @param dirPath - Path to the directory
+ * @param pattern - Glob pattern for matching files (default: '*.prompt.md')
+ * @returns Array of parsed Skills
+ * @throws SkillLoaderError if directory cannot be read
+ */
+export async function loadSkillsFromDirectory(dirPath, pattern = DEFAULT_PATTERN) {
+    try {
+        // Construct the full glob pattern
+        const fullPattern = isAbsolute(pattern)
+            ? pattern
+            : join(dirPath, pattern);
+        // Find matching files
+        const files = await glob(fullPattern, {
+            nodir: true,
+            absolute: true,
+        });
+        // Load each file
+        const skills = [];
+        const errors = [];
+        for (const file of files) {
+            try {
+                const skill = await loadSkillFromFile(file);
+                skills.push(skill);
+            }
+            catch (error) {
+                // Collect errors but continue loading other files
+                errors.push(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        // If all files failed to load, throw an error
+        if (errors.length > 0 && skills.length === 0) {
+            throw new SkillLoaderError(`Failed to load any skills from directory: ${dirPath}`, 'SOURCE_ERROR', dirPath, errors[0]);
+        }
+        return skills;
+    }
+    catch (error) {
+        if (error instanceof SkillLoaderError) {
+            throw error;
+        }
+        throw new SkillLoaderError(`Failed to read directory: ${dirPath}`, 'SOURCE_ERROR', dirPath, error instanceof Error ? error : undefined);
+    }
+}
+//# sourceMappingURL=directory.js.map

package/dist/sources/directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../../src/sources/directory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAS,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAe,EACf,UAAkB,eAAe;IAEjC,IAAI,CAAC;QACH,kCAAkC;QAClC,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;YACrC,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAE3B,sBAAsB;QACtB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE;YACpC,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;QAEH,iBAAiB;QACjB,MAAM,MAAM,GAAY,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAY,EAAE,CAAC;QAE3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC5C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,kDAAkD;gBAClD,MAAM,CAAC,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,8CAA8C;QAC9C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,gBAAgB,CACxB,6CAA6C,OAAO,EAAE,EACtD,cAAc,EACd,OAAO,EACP,MAAM,CAAC,CAAC,CAAC,CACV,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,IAAI,gBAAgB,CACxB,6BAA6B,OAAO,EAAE,EACtC,cAAc,EACd,OAAO,EACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/sources/file.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @magnolia/skill-loader - File Source Loader
+ *
+ * Loads a single skill from a file.
+ */
+import { Skill } from '../types.js';
+/**
+ * Load a single skill from a file.
+ *
+ * @param filePath - Path to the skill file
+ * @returns The parsed Skill
+ * @throws SkillLoaderError if file cannot be read or parsed
+ */
+export declare function loadSkillFromFile(filePath: string): Promise<Skill>;
+//# sourceMappingURL=file.d.ts.map

package/dist/sources/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/sources/file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,EAAoB,MAAM,aAAa,CAAC;AAGtD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAiBxE"}

package/dist/sources/file.js

@@ -0,0 +1,30 @@
+/**
+ * @magnolia/skill-loader - File Source Loader
+ *
+ * Loads a single skill from a file.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { SkillLoaderError } from '../types.js';
+import { parseSkillFile } from '../parser.js';
+/**
+ * Load a single skill from a file.
+ *
+ * @param filePath - Path to the skill file
+ * @returns The parsed Skill
+ * @throws SkillLoaderError if file cannot be read or parsed
+ */
+export async function loadSkillFromFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        const filename = basename(filePath);
+        return parseSkillFile(content, filename);
+    }
+    catch (error) {
+        if (error instanceof SkillLoaderError) {
+            throw error;
+        }
+        throw new SkillLoaderError(`Failed to load skill file: ${filePath}`, 'SOURCE_ERROR', filePath, error instanceof Error ? error : undefined);
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/sources/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/sources/file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAS,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,IAAI,gBAAgB,CACxB,8BAA8B,QAAQ,EAAE,EACxC,cAAc,EACd,QAAQ,EACR,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/sources/inline.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @magnolia/skill-loader - Inline Source Handler
+ *
+ * Handles inline skill arrays (passthrough).
+ */
+import { Skill } from '../types.js';
+/**
+ * Process inline skills.
+ * This is essentially a passthrough but validates the skills array.
+ *
+ * @param skills - Array of skills
+ * @returns The same array of skills
+ */
+export declare function processInlineSkills(skills: Skill[]): Skill[];
+//# sourceMappingURL=inline.d.ts.map

package/dist/sources/inline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../src/sources/inline.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAS5D"}

package/dist/sources/inline.js

@@ -0,0 +1,21 @@
+/**
+ * @magnolia/skill-loader - Inline Source Handler
+ *
+ * Handles inline skill arrays (passthrough).
+ */
+/**
+ * Process inline skills.
+ * This is essentially a passthrough but validates the skills array.
+ *
+ * @param skills - Array of skills
+ * @returns The same array of skills
+ */
+export function processInlineSkills(skills) {
+    // Validate that each item has required fields
+    return skills.filter((skill) => {
+        return (typeof skill.name === 'string' &&
+            skill.name.length > 0 &&
+            typeof skill.content === 'string');
+    });
+}
+//# sourceMappingURL=inline.js.map

package/dist/sources/inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../src/sources/inline.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,8CAA8C;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC7B,OAAO,CACL,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;YAC9B,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;YACrB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAClC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/sources/url.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @magnolia/skill-loader - URL Source Loader
+ *
+ * Loads skills from a remote URL (Phase 2 feature).
+ */
+import { Skill } from '../types.js';
+/**
+ * Load skills from a remote URL.
+ *
+ * The URL should return either:
+ * - A single skill file (markdown with frontmatter)
+ * - A JSON array of Skill objects
+ *
+ * @param url - URL to fetch skills from
+ * @param headers - Optional headers for the request
+ * @returns Array of parsed Skills
+ * @throws SkillLoaderError if fetch fails or response is invalid
+ */
+export declare function loadSkillsFromUrl(url: string, headers?: Record<string, string>): Promise<Skill[]>;
+//# sourceMappingURL=url.d.ts.map

package/dist/sources/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/sources/url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAoB,MAAM,aAAa,CAAC;AAGtD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,KAAK,EAAE,CAAC,CAoElB"}

package/dist/sources/url.js

@@ -0,0 +1,65 @@
+/**
+ * @magnolia/skill-loader - URL Source Loader
+ *
+ * Loads skills from a remote URL (Phase 2 feature).
+ */
+import { SkillLoaderError } from '../types.js';
+import { parseSkillFile } from '../parser.js';
+/**
+ * Load skills from a remote URL.
+ *
+ * The URL should return either:
+ * - A single skill file (markdown with frontmatter)
+ * - A JSON array of Skill objects
+ *
+ * @param url - URL to fetch skills from
+ * @param headers - Optional headers for the request
+ * @returns Array of parsed Skills
+ * @throws SkillLoaderError if fetch fails or response is invalid
+ */
+export async function loadSkillsFromUrl(url, headers) {
+    try {
+        const response = await fetch(url, {
+            headers: {
+                Accept: 'application/json, text/markdown, text/plain',
+                ...headers,
+            },
+        });
+        if (!response.ok) {
+            throw new SkillLoaderError(`Failed to fetch skills from URL: ${url} (${response.status})`, 'SOURCE_ERROR', url);
+        }
+        const contentType = response.headers.get('content-type') || '';
+        const text = await response.text();
+        // Try to parse as JSON first
+        if (contentType.includes('application/json')) {
+            try {
+                const data = JSON.parse(text);
+                // Could be an array of skills or a single skill
+                if (Array.isArray(data)) {
+                    return data;
+                }
+                // Single skill object
+                if (data.name && data.content) {
+                    return [data];
+                }
+                throw new SkillLoaderError(`Invalid JSON response from URL: ${url}`, 'PARSE_ERROR', url);
+            }
+            catch (error) {
+                if (error instanceof SkillLoaderError) {
+                    throw error;
+                }
+                throw new SkillLoaderError(`Failed to parse JSON from URL: ${url}`, 'PARSE_ERROR', url, error instanceof Error ? error : undefined);
+            }
+        }
+        // Parse as markdown with frontmatter
+        const skill = parseSkillFile(text, url);
+        return [skill];
+    }
+    catch (error) {
+        if (error instanceof SkillLoaderError) {
+            throw error;
+        }
+        throw new SkillLoaderError(`Failed to load skills from URL: ${url}`, 'SOURCE_ERROR', url, error instanceof Error ? error : undefined);
+    }
+}
+//# sourceMappingURL=url.js.map

package/dist/sources/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/sources/url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAS,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,OAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE;gBACP,MAAM,EAAE,6CAA6C;gBACrD,GAAG,OAAO;aACX;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,gBAAgB,CACxB,oCAAoC,GAAG,KAAK,QAAQ,CAAC,MAAM,GAAG,EAC9D,cAAc,EACd,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAEnC,6BAA6B;QAC7B,IAAI,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAE9B,gDAAgD;gBAChD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxB,OAAO,IAAe,CAAC;gBACzB,CAAC;gBAED,sBAAsB;gBACtB,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBAC9B,OAAO,CAAC,IAAa,CAAC,CAAC;gBACzB,CAAC;gBAED,MAAM,IAAI,gBAAgB,CACxB,mCAAmC,GAAG,EAAE,EACxC,aAAa,EACb,GAAG,CACJ,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;oBACtC,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,MAAM,IAAI,gBAAgB,CACxB,kCAAkC,GAAG,EAAE,EACvC,aAAa,EACb,GAAG,EACH,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;YACJ,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACxC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,IAAI,gBAAgB,CACxB,mCAAmC,GAAG,EAAE,EACxC,cAAc,EACd,GAAG,EACH,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @magnolia/skill-loader - Type Definitions
+ *
+ * This module defines all the core types for the skill-loader library.
+ */
+/**
+ * Metadata for filtering and selecting skills.
+ */
+export interface SkillMetadata {
+    /** Target platforms/frameworks this skill applies to */
+    targets?: string[];
+    /** Version constraint (semver range) */
+    version?: string;
+    /** Legacy field name for version (supports 'magnolia' during transition) */
+    magnolia?: string;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Required field types - skill only included when these are detected */
+    requires?: string[];
+    /** Priority for ordering (higher = earlier in output) */
+    priority?: number;
+    /** Custom metadata (extensible) */
+    [key: string]: unknown;
+}
+/**
+ * A skill is a structured prompt with metadata for conditional inclusion.
+ */
+export interface Skill {
+    /** Unique identifier for the skill */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** The prompt content (markdown, text, or structured) */
+    content: string;
+    /** Metadata for filtering and selection */
+    metadata: SkillMetadata;
+}
+/**
+ * The context provided when loading skills, used for filtering.
+ */
+export interface SkillContext {
+    /** Target platform: 'freemarker', 'spa', 'react', 'vue', 'angular', etc. */
+    target?: string;
+    /** Product/platform version (e.g., '6.3.0') */
+    version?: string;
+    /** Detected field types in the current context */
+    detectedFieldTypes?: string[];
+    /** Tags to require (skills must have at least one) */
+    requiredTags?: string[];
+    /** Tags to exclude (skills with these tags are filtered out) */
+    excludedTags?: string[];
+    /** Custom context properties (matched against skill metadata) */
+    [key: string]: unknown;
+}
+/**
+ * Skill sources - where skills can be loaded from.
+ */
+export type SkillSource = {
+    type: 'directory';
+    path: string;
+    pattern?: string;
+} | {
+    type: 'file';
+    path: string;
+} | {
+    type: 'inline';
+    skills: Skill[];
+} | {
+    type: 'url';
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    type: 'custom';
+    loader: () => Promise<Skill[]>;
+};
+/**
+ * Options for the SkillLoader constructor.
+ */
+export interface SkillLoaderOptions {
+    /** Custom filter function applied after standard filtering */
+    customFilter?: (skill: Skill, context: SkillContext) => boolean;
+    /** Custom sort function for ordering skills */
+    customSort?: (a: Skill, b: Skill) => number;
+    /** Cache TTL in milliseconds (default: 0 = no expiry) */
+    cacheTtl?: number;
+    /** File pattern for directory sources (default: '*.prompt.md') */
+    defaultPattern?: string;
+}
+/**
+ * Options for generating combined prompts from skills.
+ */
+export interface PromptOptions {
+    /** Separator between skill contents (default: '\n\n---\n\n') */
+    separator?: string;
+    /** Include skill name as header (default: true) */
+    includeHeaders?: boolean;
+    /** Header format (default: '## {name}') */
+    headerFormat?: string;
+    /** Maximum total length (truncates if exceeded) */
+    maxLength?: number;
+}
+/**
+ * Error class for skill loader errors.
+ */
+export declare class SkillLoaderError extends Error {
+    code: 'PARSE_ERROR' | 'SOURCE_ERROR' | 'FILTER_ERROR';
+    source?: string;
+    cause?: Error;
+    constructor(message: string, code: 'PARSE_ERROR' | 'SOURCE_ERROR' | 'FILTER_ERROR', source?: string, cause?: Error);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,21 @@
+/**
+ * @magnolia/skill-loader - Type Definitions
+ *
+ * This module defines all the core types for the skill-loader library.
+ */
+/**
+ * Error class for skill loader errors.
+ */
+export class SkillLoaderError extends Error {
+    code;
+    source;
+    cause;
+    constructor(message, code, source, cause) {
+        super(message);
+        this.name = 'SkillLoaderError';
+        this.code = code;
+        this.source = source;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgHH;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,IAAI,CAAkD;IACtD,MAAM,CAAU;IACP,KAAK,CAAS;IAEvB,YACE,OAAe,EACf,IAAqD,EACrD,MAAe,EACf,KAAa;QAEb,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@magnolia/skill-loader",
+  "version": "0.1.0-preview.1",
+  "description": "A Node.js library for loading, filtering, and managing AI prompt skills",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "lint": "eslint src tests",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "magnolia",
+    "skills",
+    "prompts",
+    "ai",
+    "llm",
+    "mcp"
+  ],
+  "author": "Magnolia International Ltd.",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/magnolia-cms/magnolia-mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "glob": "^11.0.0",
+    "semver": "^7.6.0",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.0",
+    "@types/semver": "^7.5.8",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.0",
+    "ts-jest": "^29.1.4",
+    "typescript": "^5.4.5"
+  }
+}