fraim-framework 2.0.83 → 2.0.85

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

@@ -20,22 +20,54 @@ class LocalRegistryResolver {
      * Check if a local override exists for the given path
      */
     hasLocalOverride(path) {
-        const overridePath = this.getOverridePath(path);
-        const exists = (0, fs_1.existsSync)(overridePath);
-        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> ${overridePath} -> ${exists}`);
+        const primaryPath = this.getOverridePath(path);
+        const legacyPath = this.getLegacyOverridePath(path);
+        const exists = (0, fs_1.existsSync)(primaryPath) || (0, fs_1.existsSync)(legacyPath);
+        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> primary: ${primaryPath}, legacy: ${legacyPath}, exists: ${exists}`);
         return exists;
     }
+    /**
+     * 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) {
+        return (0, path_1.join)(this.workspaceRoot, '.fraim/personalized-employee', path);
+    }
+    /**
+     * Get the full path to a legacy local override file.
+     * Kept for backward compatibility while migrating to personalized-employee.
+     */
+    getLegacyOverridePath(path) {
         return (0, path_1.join)(this.workspaceRoot, '.fraim/overrides', path);
     }
+    /**
+     * 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(/^\/+/, '');
+        if (normalizedPath.startsWith('skills/')) {
+            return (0, path_1.join)(this.workspaceRoot, '.fraim/ai-employee', normalizedPath);
+        }
+        if (normalizedPath.startsWith('rules/')) {
+            return (0, path_1.join)(this.workspaceRoot, '.fraim/ai-employee', normalizedPath);
+        }
+        return null;
+    }
     /**
      * Read local override file content
      */
     readLocalOverride(path) {
-        const overridePath = this.getOverridePath(path);
+        const primaryPath = this.getOverridePath(path);
+        const overridePath = (0, fs_1.existsSync)(primaryPath) ? primaryPath : this.getLegacyOverridePath(path);
         try {
             return (0, fs_1.readFileSync)(overridePath, 'utf-8');
         }
@@ -43,6 +75,37 @@ class LocalRegistryResolver {
             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 {
+            return (0, fs_1.readFileSync)(syncedPath, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    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
      */
@@ -86,20 +149,32 @@ class LocalRegistryResolver {
      * Resolve a registry file request
      *
      * Resolution order:
-     * 1. Check for local override in .fraim/overrides/
-     * 2. If found, read and resolve inheritance
-     * 3. If not found, fetch from remote
+     * 1. Check for local override in .fraim/personalized-employee/
+     * 2. Fallback to .fraim/overrides/ (legacy)
+     * 3. If found, read and resolve inheritance
+     * 4. 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) {
+    async resolveFile(path, options = {}) {
         console.error(`[LocalRegistryResolver] ===== resolveFile called for: ${path} =====`);
+        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 override, fetch from remote
             try {
-                const content = await this.remoteContentResolver(path);
+                const rawContent = await this.remoteContentResolver(path);
+                const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
                 return {
                     content,
                     source: 'remote',
@@ -118,7 +193,8 @@ class LocalRegistryResolver {
         catch (error) {
             // If local read fails, fall back to remote
             console.warn(`Local override read failed, falling back to remote: ${path}`);
-            const content = await this.remoteContentResolver(path);
+            const rawContent = await this.remoteContentResolver(path);
+            const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
             return {
                 content,
                 source: 'remote',
@@ -154,12 +230,93 @@ class LocalRegistryResolver {
             imports: resolved.imports.length > 0 ? resolved.imports : undefined
         };
         // Add metadata comment
-        const metadata = this.generateMetadata(result);
-        if (metadata) {
-            result.metadata = metadata;
-            result.content = metadata + result.content;
+        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. .fraim/overrides/ (legacy)
+     * 3. remote resolver
+     */
+    async resolveIncludes(content, maxDepth = LocalRegistryResolver.MAX_INCLUDE_DEPTH) {
+        return this.resolveIncludesInternal(content, {
+            depth: 0,
+            maxDepth,
+            stack: new Set(),
+            cache: new Map()
+        });
+    }
 }
 exports.LocalRegistryResolver = LocalRegistryResolver;
+LocalRegistryResolver.MAX_INCLUDE_DEPTH = 10;

package/dist/src/core/utils/stub-generator.js

@@ -2,6 +2,48 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateWorkflowStub = generateWorkflowStub;
 exports.parseRegistryWorkflow = parseRegistryWorkflow;
+exports.generateJobStub = generateJobStub;
+exports.generateSkillStub = generateSkillStub;
+exports.generateRuleStub = generateRuleStub;
+exports.parseRegistryJob = parseRegistryJob;
+exports.parseRegistrySkill = parseRegistrySkill;
+exports.parseRegistryRule = parseRegistryRule;
+function extractSection(content, headingPatterns) {
+    for (const heading of headingPatterns) {
+        const pattern = new RegExp(`(?:^|\\n)#{2,3}\\s*${heading}\\s*\\n([\\s\\S]*?)(?=\\n#{2,3}\\s|$)`, 'i');
+        const match = content.match(pattern);
+        if (match?.[1]) {
+            const section = match[1].trim();
+            if (section.length > 0)
+                return section;
+        }
+    }
+    return null;
+}
+function extractLeadParagraph(content) {
+    const withoutFrontmatter = content.replace(/^---[\s\S]*?---\s*/m, '');
+    const lines = withoutFrontmatter.split(/\r?\n/);
+    const paragraphLines = [];
+    let started = false;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!started) {
+            if (!line || line.startsWith('#'))
+                continue;
+            if (line.startsWith('-') || /^\d+\./.test(line))
+                continue;
+            started = true;
+        }
+        if (!line)
+            break;
+        if (line.startsWith('#'))
+            break;
+        paragraphLines.push(line);
+    }
+    if (paragraphLines.length === 0)
+        return null;
+    return paragraphLines.join(' ').trim();
+}
 /**
  * Generates a lightweight markdown stub for a workflow.
  * These stubs are committed to the user's repo for discoverability.
@@ -33,3 +75,100 @@ function parseRegistryWorkflow(content) {
         : [];
     return { intent, principles };
 }
+/**
+ * Coaching stubs are discoverability artifacts and should be resolved with get_fraim_file.
+ */
+function generateJobStub(jobName, _jobPath, intent, outcome) {
+    return `# FRAIM Job: ${jobName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
+> This stub is for discoverability only. The actual job has multiple phases with
+> detailed steps, validation criteria, and required skills.
+>
+> To get full phase-by-phase instructions, call:
+> \`get_fraim_job({ job: "${jobName}" })\`
+>
+> Then follow all phases using \`seekMentoring\` at each phase transition.
+`;
+}
+/**
+ * Generates a lightweight markdown stub for a skill.
+ */
+function generateSkillStub(skillName, skillPath, intent, outcome) {
+    return `# FRAIM Skill: ${skillName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a skill stub for discoverability.
+> To retrieve the complete skill instructions, call:
+> \`get_fraim_file({ path: "skills/${skillPath}" })\`
+`;
+}
+/**
+ * Generates a lightweight markdown stub for a rule.
+ */
+function generateRuleStub(ruleName, rulePath, intent, outcome) {
+    return `# FRAIM Rule: ${ruleName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a rule stub for discoverability.
+> To retrieve the complete rule instructions, call:
+> \`get_fraim_file({ path: "rules/${rulePath}" })\`
+`;
+}
+/**
+ * Parses a job file from the registry to extract its intent and outcome for the stub.
+ */
+function parseRegistryJob(content) {
+    const intentMatch = content.match(/##\s*intent\s+([\s\S]*?)(?=\n##|$)/i);
+    const outcomeMatch = content.match(/##\s*outcome\s+([\s\S]*?)(?=\n##|$)/i);
+    const intent = intentMatch ? intentMatch[1].trim() : 'No intent defined.';
+    const outcome = outcomeMatch ? outcomeMatch[1].trim() : 'No outcome defined.';
+    return { intent, outcome };
+}
+/**
+ * Parses a skill file from the registry to extract intent and expected outcome for stubs.
+ */
+function parseRegistrySkill(content) {
+    const intent = extractSection(content, ['intent', 'skill intent']) ||
+        extractLeadParagraph(content) ||
+        'Apply the skill correctly using the provided inputs and constraints.';
+    const outcome = extractSection(content, ['outcome', 'expected behavior', 'skill output']) ||
+        'Produce the expected skill output while following skill guardrails.';
+    return { intent, outcome };
+}
+/**
+ * Parses a rule file from the registry to extract intent and expected behavior for stubs.
+ */
+function parseRegistryRule(content) {
+    const intent = extractSection(content, ['intent']) ||
+        extractLeadParagraph(content) ||
+        'Follow this rule when executing related FRAIM workflows and jobs.';
+    const outcome = extractSection(content, ['outcome', 'expected behavior', 'principles']) ||
+        'Consistently apply this rule throughout execution.';
+    return { intent, outcome };
+}

package/dist/src/core/utils/workflow-parser.js

@@ -13,7 +13,11 @@ class WorkflowParser {
     static parse(filePath) {
         if (!(0, fs_1.existsSync)(filePath))
             return null;
-        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        let content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        // Strip optional UTF-8 BOM so frontmatter regex remains stable across editors.
+        if (content.charCodeAt(0) === 0xfeff) {
+            content = content.slice(1);
+        }
         // Try to extract JSON Metadata (frontmatter)
         const metadataMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
         if (metadataMatch) {