fraim 2.0.100

package/dist/src/core/utils/local-registry-resolver.js

@@ -0,0 +1,616 @@
+"use strict";
+/**
+ * LocalRegistryResolver
+ *
+ * Resolves registry file requests by checking for local overrides first,
+ * then falling back to remote registry. Handles inheritance via InheritanceParser.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRegistryResolver = void 0;
+const fs = __importStar(require("fs"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const inheritance_parser_1 = require("./inheritance-parser");
+const job_parser_1 = require("./job-parser");
+const project_fraim_paths_1 = require("./project-fraim-paths");
+class LocalRegistryResolver {
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.remoteContentResolver = options.remoteContentResolver;
+        this.parser = new inheritance_parser_1.InheritanceParser(options.maxDepth);
+        this.shouldFilter = options.shouldFilter;
+    }
+    /**
+     * Check if a local override exists for the given path
+     */
+    hasLocalOverride(path) {
+        return (0, fs_1.existsSync)(this.getOverridePath(path));
+    }
+    /**
+     * Find the actual relative path for a registry item by searching subdirectories.
+     * Returns '{type}/{category}/{name}.md' or '{type}/{name}.md'.
+     */
+    async findRegistryPath(type, name) {
+        const baseName = `${name}.md`;
+        const searchDirs = [type];
+        for (const dir of searchDirs) {
+            // Check literal path first
+            const literal = `${dir}/${baseName}`;
+            if (this.hasLocalOverride(literal))
+                return literal;
+            // Deep search
+            const fullBaseDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', dir);
+            const found = this.searchFileRecursively(fullBaseDir, baseName);
+            if (found) {
+                // Convert absolute back to relative
+                const rel = found.replace(/\\/g, '/');
+                const dirMarker = `/${dir}/`;
+                if (rel.includes(dirMarker)) {
+                    return rel.substring(rel.indexOf(dirMarker) + 1);
+                }
+            }
+        }
+        return `${type}/${name}.md`;
+    }
+    searchFileRecursively(dir, fileName) {
+        if (!(0, fs_1.existsSync)(dir))
+            return null;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                const found = this.searchFileRecursively(fullPath, fileName);
+                if (found)
+                    return found;
+            }
+            else if (entry.name === fileName) {
+                return fullPath;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a locally synced skill/rule file exists for the given registry path.
+     */
+    hasSyncedLocalFile(path) {
+        const syncedPath = this.getSyncedFilePath(path);
+        return !!syncedPath && (0, fs_1.existsSync)(syncedPath);
+    }
+    /**
+     * Get the full path to a local override file
+     */
+    getOverridePath(path) {
+        const normalized = path.replace(/\\/g, '/').replace(/^\/+/, '');
+        // Personal overrides are in fraim/personalized-employee/
+        // We don't need a redundant 'registry/' subfolder here as the path already includes type (e.g. jobs/)
+        return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', normalized);
+    }
+    /**
+     * Get the full path to a locally synced FRAIM file when available.
+     * Skills and rules are synced under role-based folders:
+     * - skills/* -> fraim/ai-employee/skills/*
+     * - rules/*  -> fraim/ai-employee/rules/*
+     */
+    getSyncedFilePath(path) {
+        const normalizedPath = path.replace(/\\/g, '/').replace(/^\/+/, '');
+        // 1. Workflows: workflows/[role]/path -> fraim/[role]/workflows/path
+        if (normalizedPath.startsWith('workflows/')) {
+            const parts = normalizedPath.split('/');
+            if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
+                const role = parts[1];
+                const subPath = parts.slice(2).join('/');
+                return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'workflows', subPath);
+            }
+            // Fallback: Try ai-employee and ai-manager if no role prefix
+            const subPath = normalizedPath.substring('workflows/'.length);
+            const employeePath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'workflows', subPath);
+            if (fs.existsSync(employeePath))
+                return employeePath;
+            const managerPath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-manager', 'workflows', subPath);
+            if (fs.existsSync(managerPath))
+                return managerPath;
+            // Fallback for non-role-prefixed direct workspace paths
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, normalizedPath);
+        }
+        // 2. Jobs: jobs/[role]/path -> fraim/[role]/jobs/path
+        if (normalizedPath.startsWith('jobs/')) {
+            const parts = normalizedPath.split('/');
+            if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
+                const role = parts[1];
+                const subPath = parts.slice(2).join('/');
+                return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'jobs', subPath);
+            }
+            // Fallback: Try ai-employee and ai-manager if no role prefix
+            const subPath = normalizedPath.substring('jobs/'.length);
+            const employeePath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'jobs', subPath);
+            if (fs.existsSync(employeePath))
+                return employeePath;
+            const managerPath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-manager', 'jobs', subPath);
+            if (fs.existsSync(managerPath))
+                return managerPath;
+            // Fallback
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, normalizedPath);
+        }
+        // 3. Rules: [role]/rules/path -> fraim/[role]/rules/path
+        if (normalizedPath.includes('/rules/')) {
+            const role = normalizedPath.includes('/ai-manager/') ? 'ai-manager' : 'ai-employee';
+            // Extract the part after "rules/"
+            const rulesIdx = normalizedPath.indexOf('rules/');
+            const subPath = normalizedPath.substring(rulesIdx + 'rules/'.length);
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'rules', subPath);
+        }
+        // 4. Skills: skills/path -> fraim/ai-employee/skills/path (default to ai-employee)
+        if (normalizedPath.startsWith('skills/')) {
+            const subPath = normalizedPath.substring('skills/'.length);
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'skills', subPath);
+        }
+        // 5. Rules: rules/path -> fraim/ai-employee/rules/path (default to ai-employee)
+        if (normalizedPath.startsWith('rules/')) {
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', normalizedPath);
+        }
+        return null;
+    }
+    /**
+     * Read local override file content
+     */
+    readLocalOverride(path) {
+        try {
+            return (0, fs_1.readFileSync)(this.getOverridePath(path), 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read local override: ${path}. ${error.message}`);
+        }
+    }
+    /**
+     * Read locally synced skill/rule file content.
+     */
+    readSyncedLocalFile(path) {
+        const syncedPath = this.getSyncedFilePath(path);
+        if (!syncedPath || !(0, fs_1.existsSync)(syncedPath)) {
+            return null;
+        }
+        try {
+            const content = (0, fs_1.readFileSync)(syncedPath, 'utf-8');
+            if (this.shouldFilter && this.shouldFilter(content)) {
+                return null;
+            }
+            return content;
+        }
+        catch {
+            return null;
+        }
+    }
+    normalizeRegistryPath(path) {
+        const normalized = path.trim().replace(/\\/g, '/').replace(/^\/+/, '');
+        return normalized.endsWith('.md') ? normalized : `${normalized}.md`;
+    }
+    stripTypePrefix(path) {
+        return path.replace(/^(jobs|workflows|skills|rules|templates)\//, '');
+    }
+    areEquivalentRegistryPaths(left, right) {
+        const normalizedLeft = this.normalizeRegistryPath(left);
+        const normalizedRight = this.normalizeRegistryPath(right);
+        const strippedLeft = this.stripTypePrefix(normalizedLeft);
+        const strippedRight = this.stripTypePrefix(normalizedRight);
+        return normalizedLeft === normalizedRight ||
+            strippedLeft === strippedRight ||
+            normalizedLeft.endsWith(`/${strippedRight}`) ||
+            normalizedRight.endsWith(`/${strippedLeft}`) ||
+            strippedLeft.endsWith(`/${strippedRight}`) ||
+            strippedRight.endsWith(`/${strippedLeft}`);
+    }
+    async fetchRemoteWithFallback(...paths) {
+        const candidates = new Set();
+        for (const path of paths) {
+            if (!path)
+                continue;
+            const normalized = this.normalizeRegistryPath(path);
+            candidates.add(normalized);
+            candidates.add(this.stripTypePrefix(normalized));
+        }
+        let lastError = null;
+        for (const candidate of candidates) {
+            try {
+                return await this.remoteContentResolver(candidate);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw lastError || new Error(`Failed to fetch remote content for ${paths.join(', ')}`);
+    }
+    stripMcpHeader(content) {
+        const trimmed = content.trimStart();
+        if (!trimmed.startsWith('#')) {
+            return content;
+        }
+        const separator = '\n---\n';
+        const separatorIndex = content.indexOf(separator);
+        if (separatorIndex === -1) {
+            return content;
+        }
+        const headerBlock = content.slice(0, separatorIndex);
+        if (!headerBlock.includes('** Path:**')) {
+            return content;
+        }
+        return content.slice(separatorIndex + separator.length).trimStart();
+    }
+    /**
+     * Resolve inheritance in local override content
+     */
+    async resolveInheritance(content, currentPath) {
+        // Check if content has imports
+        const parseResult = this.parser.parse(content);
+        if (!parseResult.hasImports) {
+            return { content, imports: [] };
+        }
+        // Resolve inheritance
+        try {
+            const resolved = await this.parser.resolve(content, currentPath, {
+                fetchParent: async (path) => {
+                    const normalized = this.normalizeRegistryPath(path);
+                    const normalizedCurrent = this.normalizeRegistryPath(currentPath);
+                    // If the import points back to the current file, skip local resolution and fetch
+                    // from the next layer (remote/global) instead.
+                    if (this.areEquivalentRegistryPaths(normalized, normalizedCurrent)) {
+                        return this.fetchRemoteWithFallback(normalizedCurrent, normalized);
+                    }
+                    // Otherwise, resolve through the normal local-first path.
+                    try {
+                        let targetPath = normalized;
+                        const hasKnownPrefix = targetPath.startsWith('jobs/') || targetPath.startsWith('workflows/') ||
+                            targetPath.startsWith('skills/') || targetPath.startsWith('rules/') || targetPath.startsWith('templates/');
+                        if (!hasKnownPrefix) {
+                            // Try to guess type from currentPath or just try jobs/workflows
+                            const type = normalizedCurrent.startsWith('jobs/') ? 'jobs' : (normalizedCurrent.startsWith('workflows/') ? 'workflows' : null);
+                            if (type) {
+                                try {
+                                    targetPath = await this.findRegistryPath(type, normalized.replace(/\.md$/, ''));
+                                }
+                                catch {
+                                    // Ignore and use original normalized
+                                }
+                            }
+                        }
+                        const res = await this.resolveFile(targetPath, {
+                            includeMetadata: false,
+                            stripMcpHeader: true
+                        });
+                        return res.content;
+                    }
+                    catch (error) {
+                        throw error;
+                    }
+                },
+                maxDepth: 5
+            });
+            return {
+                content: resolved,
+                imports: parseResult.imports
+            };
+        }
+        catch (error) {
+            if (error instanceof inheritance_parser_1.InheritanceError) {
+                throw error;
+            }
+            throw new Error(`Failed to resolve inheritance for ${currentPath}: ${error.message}`);
+        }
+    }
+    /**
+     * Generate metadata comment for resolved content
+     */
+    generateMetadata(result) {
+        if (result.source === 'remote') {
+            return '';
+        }
+        if (result.inherited && result.imports && result.imports.length > 0) {
+            return `<!-- 📝 Using local override (inherited from: ${result.imports.join(', ')}) -->\n\n`;
+        }
+        return `<!-- 📝 Using local override -->\n\n`;
+    }
+    /**
+     * Resolve a registry file request
+     *
+     * Resolution order:
+     * 1. Check for local override in fraim/personalized-employee/
+     * 2. If found, read and resolve inheritance
+     * 3. If not found, fetch from remote
+     *
+     * @param path - Registry path (e.g., "workflows/product-building/spec.md")
+     * @returns Resolved file with metadata
+     */
+    async resolveFile(path, options = {}) {
+        const includeMetadata = options.includeMetadata ?? true;
+        const stripMcpHeader = options.stripMcpHeader ?? false;
+        // Check for local override
+        if (!this.hasLocalOverride(path)) {
+            const syncedLocalContent = this.readSyncedLocalFile(path);
+            if (syncedLocalContent !== null) {
+                return {
+                    content: syncedLocalContent,
+                    source: 'local',
+                    inherited: false
+                };
+            }
+            // No useful override or synced content, fetch from remote
+            try {
+                const rawContent = await this.fetchRemoteWithFallback(path);
+                const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
+                return {
+                    content,
+                    source: 'remote',
+                    inherited: false
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch from remote: ${path}. ${error.message}`);
+            }
+        }
+        // Read local override
+        let localContent;
+        try {
+            localContent = this.readLocalOverride(path);
+            if (this.shouldFilter && this.shouldFilter(localContent)) {
+                console.warn(`[LocalRegistryResolver] Local override for ${path} filtered (e.g. stub), falling back to remote.`);
+                throw new Error('CONTENT_FILTERED');
+            }
+        }
+        catch (error) {
+            // If local read fails, fall back to remote
+            console.warn(`Local override read failed, falling back to remote: ${path}`);
+            const rawContent = await this.fetchRemoteWithFallback(path);
+            const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Resolve inheritance
+        let resolved;
+        try {
+            resolved = await this.resolveInheritance(localContent, path);
+        }
+        catch (error) {
+            const rawContent = await this.fetchRemoteWithFallback(path);
+            const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Build result
+        const result = {
+            content: resolved.content,
+            source: 'local',
+            inherited: resolved.imports.length > 0,
+            imports: resolved.imports.length > 0 ? resolved.imports : undefined
+        };
+        // Add metadata comment
+        if (includeMetadata) {
+            const metadata = this.generateMetadata(result);
+            if (metadata) {
+                result.metadata = metadata;
+                result.content = metadata + result.content;
+            }
+        }
+        return result;
+    }
+    sanitizeIncludePath(path) {
+        const trimmed = path.trim().replace(/\\/g, '/');
+        if (!trimmed)
+            return null;
+        if (trimmed.includes('..'))
+            return null;
+        if (trimmed.startsWith('/'))
+            return null;
+        if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed))
+            return null;
+        return trimmed;
+    }
+    async resolveIncludesInternal(content, options) {
+        if (options.depth >= options.maxDepth) {
+            return content;
+        }
+        const includePattern = /\{\{include:([^}]+)\}\}/g;
+        const matches = Array.from(content.matchAll(includePattern));
+        if (matches.length === 0) {
+            return content;
+        }
+        const resolvedByPath = new Map();
+        for (const match of matches) {
+            const includePath = this.sanitizeIncludePath(match[1]);
+            if (!includePath)
+                continue;
+            if (resolvedByPath.has(includePath))
+                continue;
+            if (options.cache.has(includePath)) {
+                resolvedByPath.set(includePath, options.cache.get(includePath));
+                continue;
+            }
+            if (options.stack.has(includePath)) {
+                continue;
+            }
+            try {
+                options.stack.add(includePath);
+                const resolved = await this.resolveFile(includePath, {
+                    includeMetadata: false,
+                    stripMcpHeader: true
+                });
+                const resolvedContent = await this.resolveIncludesInternal(resolved.content, {
+                    depth: options.depth + 1,
+                    maxDepth: options.maxDepth,
+                    stack: options.stack,
+                    cache: options.cache
+                });
+                options.cache.set(includePath, resolvedContent);
+                resolvedByPath.set(includePath, resolvedContent);
+            }
+            catch (error) {
+                console.warn(`Failed to resolve include ${includePath}: ${error.message}`);
+            }
+            finally {
+                options.stack.delete(includePath);
+            }
+        }
+        return content.replace(includePattern, (fullMatch, includeRef) => {
+            const includePath = this.sanitizeIncludePath(includeRef);
+            if (!includePath)
+                return fullMatch;
+            return resolvedByPath.get(includePath) ?? fullMatch;
+        });
+    }
+    /**
+     * Resolve {{include:path}} directives using local override precedence:
+     * 1. fraim/personalized-employee/
+     * 2. remote resolver
+     */
+    async resolveIncludes(content, maxDepth = LocalRegistryResolver.MAX_INCLUDE_DEPTH) {
+        return this.resolveIncludesInternal(content, {
+            depth: 0,
+            maxDepth,
+            stack: new Set(),
+            cache: new Map()
+        });
+    }
+    /**
+     * Implement RegistryResolver: Resolve raw file content
+     */
+    async getFile(path) {
+        try {
+            const result = await this.resolveFile(path, {
+                includeMetadata: false,
+                stripMcpHeader: true
+            });
+            return result.content;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Implement RegistryResolver: Parse and resolve a job
+     */
+    async getJob(name) {
+        // Priority 1: personalized-employee/jobs/ (user override)
+        try {
+            const jobPath = await this.findRegistryPath('jobs', name);
+            if (this.hasLocalOverride(jobPath)) {
+                const resolved = await this.resolveFile(jobPath, {
+                    includeMetadata: false,
+                    stripMcpHeader: true
+                });
+                if (resolved) {
+                    return job_parser_1.JobParser.parseContent(resolved.content, name, jobPath);
+                }
+            }
+        }
+        catch {
+            // not in personalized-employee
+        }
+        // Priority 2: Remote (via resolveFile)
+        try {
+            const path = await this.findRegistryPath('jobs', name);
+            const resolved = await this.resolveFile(path, {
+                includeMetadata: false,
+                stripMcpHeader: true
+            });
+            if (resolved) {
+                return job_parser_1.JobParser.parseContent(resolved.content, name, path);
+            }
+        }
+        catch (err) {
+            // Not found in jobs
+        }
+        // Fallback for names that might already include type/category
+        try {
+            const finalPath = name.endsWith('.md') ? name : `${name}.md`;
+            const resolved = await this.resolveFile(finalPath, {
+                includeMetadata: false,
+                stripMcpHeader: true
+            });
+            return job_parser_1.JobParser.parseContent(resolved.content, name, finalPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Implement RegistryResolver: List available items
+     * Note: For proxy, this is a merged view of local and potentially remote.
+     * Remote discovery is handled separately in list_fraim_jobs.
+     */
+    async listItems(type) {
+        // Current LocalRegistryResolver doesn't maintain a full list of remote items,
+        // so it primarily returns local overrides.
+        const items = [];
+        const dirs = ['jobs'];
+        for (const dir of dirs) {
+            const localDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', dir);
+            if (fs.existsSync(localDir)) {
+                const relPaths = this.collectLocalMarkdownPaths(localDir);
+                for (const rel of relPaths) {
+                    items.push({
+                        name: rel.replace(/\.md$/, ''),
+                        path: `${dir}/${rel}`,
+                        type: 'job'
+                    });
+                }
+            }
+        }
+        return items;
+    }
+    collectLocalMarkdownPaths(dir, currentRel = '') {
+        const results = [];
+        if (!fs.existsSync(dir))
+            return results;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const rel = currentRel ? `${currentRel}/${entry.name}` : entry.name;
+            const full = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...this.collectLocalMarkdownPaths(full, rel));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(rel);
+            }
+        }
+        return results;
+    }
+}
+exports.LocalRegistryResolver = LocalRegistryResolver;
+LocalRegistryResolver.MAX_INCLUDE_DEPTH = 10;

package/dist/src/core/utils/object-utils.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestedValue = getNestedValue;
+/**
+ * Safely get a nested value from an object using a dot-path
+ */
+function getNestedValue(obj, path) {
+    if (!obj)
+        return undefined;
+    return path.split('.').reduce((current, key) => current && current[key] !== undefined ? current[key] : undefined, obj);
+}