fraim-framework 2.0.87 → 2.0.89

package/dist/src/core/utils/server-startup.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPortConflictError = createPortConflictError;
+exports.startListening = startListening;
+exports.logStartupError = logStartupError;
+function createPortConflictError(port) {
+    const error = new Error(`Port ${port} is already in use. Another process is already listening on http://localhost:${port}. Stop that process or set FRAIM_MCP_PORT/PORT to a different port.`);
+    error.code = 'EADDRINUSE';
+    return error;
+}
+async function startListening(app, port, onListening) {
+    await new Promise((resolve, reject) => {
+        const server = app.listen(port);
+        server.once('listening', () => {
+            onListening();
+            resolve();
+        });
+        server.once('error', (error) => {
+            if (error?.code === 'EADDRINUSE') {
+                reject(createPortConflictError(port));
+                return;
+            }
+            reject(error);
+        });
+    });
+}
+function logStartupError(error) {
+    const maybePortError = error;
+    if (maybePortError?.code === 'EADDRINUSE') {
+        console.error(`[FRAIM PORT] ${maybePortError.message}`);
+        return;
+    }
+    console.error('❌ Failed to start FRAIM MCP Server:', error);
+}

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

@@ -8,6 +8,7 @@ exports.generateRuleStub = generateRuleStub;
 exports.parseRegistryJob = parseRegistryJob;
 exports.parseRegistrySkill = parseRegistrySkill;
 exports.parseRegistryRule = parseRegistryRule;
+const STUB_MARKER = '<!-- FRAIM_DISCOVERY_STUB -->';
 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');
@@ -49,10 +50,11 @@ function extractLeadParagraph(content) {
  * These stubs are committed to the user's repo for discoverability.
  */
 function generateWorkflowStub(workflowName, workflowPath, intent, principles) {
-    return `# FRAIM Workflow: ${workflowName}
-
-> [!IMPORTANT]
-> This is a **FRAIM-managed workflow stub**. 
+    return `${STUB_MARKER}
+# FRAIM Workflow: ${workflowName}
+
+> [!IMPORTANT]
+> This is a **FRAIM-managed workflow stub**. 
 > To load the full context (rules, templates, and execution steps), ask your AI agent to:
 > \`@fraim get_fraim_workflow("${workflowName}")\`
 >
@@ -78,16 +80,20 @@ function parseRegistryWorkflow(content) {
 /**
  * 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}
-
----
+function generateJobStub(jobName, _jobPath, intent, outcome, steps) {
+    return `${STUB_MARKER}
+# FRAIM Job: ${jobName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+## Steps
+${steps}
+
+---
 
 > [!IMPORTANT]
 > **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
@@ -103,72 +109,73 @@ ${outcome}
 /**
  * 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}" })\`
+function generateSkillStub(skillName, skillPath, skillInput, skillOutput) {
+    return `${STUB_MARKER}
+# FRAIM Skill: ${skillName}
+
+## Skill Input
+${skillInput}
+
+## Skill Output
+${skillOutput}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the skill.
+> All execution details must be fetched from MCP before use.
+> 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}" })\`
+function generateRuleStub(ruleName, rulePath, intent) {
+    return `${STUB_MARKER}
+# FRAIM Rule: ${ruleName}
+
+## Intent
+${intent}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the rule.
+> All rule details must be fetched from MCP before use.
+> 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.
+ * Parses a job file from the registry to extract its intent, outcome, and steps 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 stepsMatch = content.match(/##\s*steps\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 };
+    const steps = stepsMatch ? stepsMatch[1].trim() : 'Use get_fraim_job to retrieve the full phase-by-phase execution steps.';
+    return { intent, outcome, steps };
 }
 /**
  * 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']) ||
+    const skillInput = extractSection(content, ['skill input', 'input', '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 };
+        'Use this skill only when the task matches the skill trigger, context, and required inputs.';
+    const skillOutput = extractSection(content, ['skill output', 'output', 'outcome', 'expected behavior']) ||
+        'Produce the concrete deliverable or decision this skill is designed to return.';
+    return { skillInput, skillOutput };
 }
 /**
- * Parses a rule file from the registry to extract intent and expected behavior for stubs.
+ * Parses a rule file from the registry to extract intent 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 };
+    return { intent };
 }

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

@@ -4,45 +4,98 @@ exports.WorkflowParser = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 class WorkflowParser {
+    static extractMetadataBlock(content) {
+        const frontmatterMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+        if (frontmatterMatch) {
+            try {
+                return {
+                    state: 'valid',
+                    metadata: JSON.parse(frontmatterMatch[1]),
+                    bodyStartIndex: frontmatterMatch[0].length
+                };
+            }
+            catch {
+                return { state: 'invalid' };
+            }
+        }
+        const trimmedStart = content.search(/\S/);
+        if (trimmedStart === -1 || content[trimmedStart] !== '{') {
+            return { state: 'none' };
+        }
+        let depth = 0;
+        let inString = false;
+        let escaping = false;
+        for (let i = trimmedStart; i < content.length; i++) {
+            const ch = content[i];
+            if (inString) {
+                if (escaping) {
+                    escaping = false;
+                }
+                else if (ch === '\\') {
+                    escaping = true;
+                }
+                else if (ch === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+                continue;
+            }
+            if (ch === '{') {
+                depth++;
+                continue;
+            }
+            if (ch === '}') {
+                depth--;
+                if (depth === 0) {
+                    const bodyStartIndex = i + 1;
+                    const remainder = content.slice(bodyStartIndex).trimStart();
+                    // `{...}\n---` is usually malformed frontmatter, not bare JSON metadata.
+                    if (remainder.startsWith('---')) {
+                        return { state: 'none' };
+                    }
+                    try {
+                        return {
+                            state: 'valid',
+                            metadata: JSON.parse(content.slice(trimmedStart, bodyStartIndex)),
+                            bodyStartIndex
+                        };
+                    }
+                    catch {
+                        return { state: 'invalid' };
+                    }
+                }
+            }
+        }
+        return { state: 'none' };
+    }
     /**
      * Parse a workflow markdown file into a structured definition
-     * Supports two formats:
-     * 1. Phase-based workflows with JSON frontmatter (e.g., implement, spec)
-     * 2. Simple workflows without frontmatter (e.g., bootstrap workflows)
+     * Supports three formats:
+     * 1. Phase-based workflows with JSON frontmatter
+     * 2. Phase-based workflows with bare leading JSON metadata
+     * 3. Simple workflows without metadata
      */
     static parse(filePath) {
         if (!(0, fs_1.existsSync)(filePath))
             return null;
         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) {
-            // Phase-based workflow with frontmatter
-            return this.parsePhaseBasedWorkflow(filePath, content, metadataMatch);
+        const metadataBlock = this.extractMetadataBlock(content);
+        if (metadataBlock.state === 'invalid') {
+            return null;
         }
-        else {
-            // Simple workflow without frontmatter
-            return this.parseSimpleWorkflow(filePath, content);
+        if (metadataBlock.state === 'valid') {
+            return this.parsePhaseBasedWorkflow(filePath, content, metadataBlock.metadata, metadataBlock.bodyStartIndex);
         }
+        return this.parseSimpleWorkflow(filePath, content);
     }
-    /**
-     * Parse a phase-based workflow with JSON frontmatter
-     */
-    static parsePhaseBasedWorkflow(filePath, content, metadataMatch) {
-        let metadata;
-        try {
-            metadata = JSON.parse(metadataMatch[1]);
-        }
-        catch (e) {
-            console.error(`❌ Failed to parse JSON metadata in ${filePath}:`, e);
-            return null;
-        }
-        // Extract Overview (Content after metadata but before first phase header)
-        const contentAfterMetadata = content.substring(metadataMatch[0].length).trim();
+    static parsePhaseBasedWorkflow(filePath, content, metadata, bodyStartIndex) {
+        const contentAfterMetadata = content.substring(bodyStartIndex).trim();
         const firstPhaseIndex = contentAfterMetadata.search(/^##\s+Phase:/m);
         let overview = '';
         let restOfContent = '';
@@ -53,34 +106,28 @@ class WorkflowParser {
         else {
             overview = contentAfterMetadata;
         }
-        // Extract Phases (id -> content)
         const phases = new Map();
         const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
-        // Skip the first part (empty or overview overlap)
+        if (!metadata.phases) {
+            metadata.phases = {};
+        }
         for (let i = 1; i < phaseSections.length; i++) {
             const section = phaseSections[i];
             const sectionLines = section.split('\n');
             const firstLine = sectionLines[0].trim();
-            // Extract phase ID (slug before any (Phase X) or space)
             const id = firstLine.split(/[ (]/)[0].trim().toLowerCase();
-            // Store the whole section with header
             phases.set(id, `## Phase: ${section.trim()}`);
         }
         return {
             metadata,
             overview,
             phases,
-            isSimple: false
+            isSimple: false,
+            path: filePath
         };
     }
-    /**
-     * Parse a simple workflow without frontmatter (bootstrap-style)
-     */
     static parseSimpleWorkflow(filePath, content) {
-        // Extract workflow name from filename
         const workflowName = (0, path_1.basename)(filePath, '.md');
-        // For simple workflows, the entire content is the overview
-        // No phases, just execution steps
         const metadata = {
             name: workflowName
         };
@@ -88,28 +135,38 @@ class WorkflowParser {
             metadata,
             overview: content.trim(),
             phases: new Map(),
-            isSimple: true
+            isSimple: true,
+            path: filePath
         };
     }
-    /**
-     * Get just the overview for an agent starting a workflow
-     */
+    static parseContent(content, name, path) {
+        if (content.charCodeAt(0) === 0xfeff) {
+            content = content.slice(1);
+        }
+        const metadataBlock = this.extractMetadataBlock(content);
+        if (metadataBlock.state === 'invalid') {
+            return null;
+        }
+        if (metadataBlock.state === 'valid') {
+            return this.parsePhaseBasedWorkflow(path || `content:${name}`, content, metadataBlock.metadata, metadataBlock.bodyStartIndex);
+        }
+        return this.parseSimpleWorkflow(path || `content:${name}`, content);
+    }
+    static getOverviewFromContent(content, name) {
+        const wf = this.parseContent(content, name);
+        return wf ? wf.overview : null;
+    }
     static getOverview(filePath) {
         const wf = this.parse(filePath);
         return wf ? wf.overview : null;
     }
-    /**
-     * Extract description for listing workflows (intent or first para of overview)
-     */
     static extractDescription(filePath) {
         const wf = this.parse(filePath);
         if (!wf)
             return '';
-        // Try to find Intent section in overview
         const intentMatch = wf.overview.match(/## Intent\s+([\s\S]+?)(?:\r?\n##|$)/);
         if (intentMatch)
             return intentMatch[1].trim().split(/\r?\n/)[0];
-        // Fallback to first non-header line
         const firstPara = wf.overview.split(/\r?\n/).find(l => l.trim() !== '' && !l.startsWith('#'));
         return firstPara ? firstPara.trim() : '';
     }