fraim 2.0.100

package/dist/src/core/utils/project-fraim-migration.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_WORKSPACE_FRAIM_DIRNAME = void 0;
+exports.migrateLegacyProjectFraimDir = migrateLegacyProjectFraimDir;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("./project-fraim-paths");
+exports.LEGACY_WORKSPACE_FRAIM_DIRNAME = '.fraim';
+const MIGRATABLE_LEGACY_ENTRIES = [
+    'config.json',
+    'personalized-employee'
+];
+const PRUNABLE_LEGACY_SYNCED_ENTRIES = [
+    'ai-employee',
+    'ai-manager',
+    'docs',
+    'jobs',
+    'workflows'
+];
+function getLegacyWorkspaceFraimDir(projectRoot) {
+    return path_1.default.join(projectRoot, exports.LEGACY_WORKSPACE_FRAIM_DIRNAME);
+}
+function areFilesEqual(leftPath, rightPath) {
+    try {
+        return fs_1.default.readFileSync(leftPath, 'utf8') === fs_1.default.readFileSync(rightPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+}
+function removeDirectoryIfEmpty(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return;
+    }
+    const entries = fs_1.default.readdirSync(dirPath);
+    if (entries.length === 0) {
+        fs_1.default.rmdirSync(dirPath);
+    }
+}
+function isDirectoryEmpty(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return true;
+    }
+    return fs_1.default.readdirSync(dirPath).length === 0;
+}
+function moveOrMergePath(sourcePath, targetPath, relativePath, result) {
+    if (!fs_1.default.existsSync(sourcePath)) {
+        return;
+    }
+    const sourceStats = fs_1.default.statSync(sourcePath);
+    if (!fs_1.default.existsSync(targetPath)) {
+        fs_1.default.mkdirSync(path_1.default.dirname(targetPath), { recursive: true });
+        fs_1.default.renameSync(sourcePath, targetPath);
+        result.migratedPaths.push(relativePath.replace(/\\/g, '/'));
+        return;
+    }
+    const targetStats = fs_1.default.statSync(targetPath);
+    if (sourceStats.isDirectory() && targetStats.isDirectory()) {
+        for (const entry of fs_1.default.readdirSync(sourcePath, { withFileTypes: true })) {
+            moveOrMergePath(path_1.default.join(sourcePath, entry.name), path_1.default.join(targetPath, entry.name), path_1.default.posix.join(relativePath.replace(/\\/g, '/'), entry.name), result);
+        }
+        removeDirectoryIfEmpty(sourcePath);
+        return;
+    }
+    if (!sourceStats.isDirectory() && !targetStats.isDirectory() && areFilesEqual(sourcePath, targetPath)) {
+        fs_1.default.unlinkSync(sourcePath);
+        return;
+    }
+    result.conflictPaths.push(relativePath.replace(/\\/g, '/'));
+}
+function migrateLegacyProjectFraimDir(projectRoot = process.cwd()) {
+    const workspaceDirPath = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
+    const legacyDirPath = getLegacyWorkspaceFraimDir(projectRoot);
+    const result = {
+        legacyDirPath,
+        workspaceDirPath,
+        legacyDirFound: fs_1.default.existsSync(legacyDirPath),
+        migratedPaths: [],
+        prunedLegacyPaths: [],
+        conflictPaths: [],
+        legacyDirReadyForDeletion: false
+    };
+    if (!result.legacyDirFound) {
+        return result;
+    }
+    fs_1.default.mkdirSync(workspaceDirPath, { recursive: true });
+    for (const entry of MIGRATABLE_LEGACY_ENTRIES) {
+        moveOrMergePath(path_1.default.join(legacyDirPath, entry), path_1.default.join(workspaceDirPath, entry), entry, result);
+    }
+    for (const entry of PRUNABLE_LEGACY_SYNCED_ENTRIES) {
+        const legacyEntryPath = path_1.default.join(legacyDirPath, entry);
+        if (!fs_1.default.existsSync(legacyEntryPath)) {
+            continue;
+        }
+        fs_1.default.rmSync(legacyEntryPath, { recursive: true, force: true });
+        result.prunedLegacyPaths.push(entry);
+    }
+    result.legacyDirReadyForDeletion = result.conflictPaths.length === 0 && isDirectoryEmpty(legacyDirPath);
+    return result;
+}

package/dist/src/core/utils/project-fraim-paths.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_SYNCED_CONTENT_DIRS = exports.WORKSPACE_FRAIM_DIRNAME = void 0;
+exports.getWorkspaceFraimDir = getWorkspaceFraimDir;
+exports.workspaceFraimExists = workspaceFraimExists;
+exports.getWorkspaceConfigPath = getWorkspaceConfigPath;
+exports.getWorkspaceFraimPath = getWorkspaceFraimPath;
+exports.getWorkspaceFraimDisplayPath = getWorkspaceFraimDisplayPath;
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.WORKSPACE_FRAIM_DIRNAME = 'fraim';
+exports.WORKSPACE_SYNCED_CONTENT_DIRS = [
+    'workflows',
+    'ai-employee',
+    'ai-manager',
+    'docs'
+];
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/^[\\/]+/, '').replace(/[\\/]+/g, '/');
+}
+function getWorkspaceFraimDir(projectRoot = process.cwd()) {
+    return (0, path_1.join)(projectRoot, exports.WORKSPACE_FRAIM_DIRNAME);
+}
+function workspaceFraimExists(projectRoot = process.cwd()) {
+    return (0, fs_1.existsSync)(getWorkspaceFraimDir(projectRoot));
+}
+function getWorkspaceConfigPath(projectRoot = process.cwd()) {
+    return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), 'config.json');
+}
+function getWorkspaceFraimPath(projectRoot = process.cwd(), ...parts) {
+    return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), ...parts);
+}
+function getWorkspaceFraimDisplayPath(relativePath = '') {
+    const normalized = normalizeRelativePath(relativePath);
+    return normalized.length > 0
+        ? `${exports.WORKSPACE_FRAIM_DIRNAME}/${normalized}`
+        : `${exports.WORKSPACE_FRAIM_DIRNAME}/`;
+}

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectProvider = detectProvider;
+/**
+ * Detect git provider from URL
+ */
+function detectProvider(url) {
+    if (!url)
+        return 'github';
+    const normalized = url.toLowerCase();
+    if (normalized.includes('gitlab.com') || normalized.includes('gitlab.')) {
+        return 'gitlab';
+    }
+    if (normalized.includes('dev.azure.com') || normalized.includes('visualstudio.com')) {
+        return 'ado';
+    }
+    return 'github';
+}

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateJobStub = generateJobStub;
+exports.generateSkillStub = generateSkillStub;
+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');
+        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();
+}
+/**
+ * Coaching stubs are discoverability artifacts and should be resolved with get_fraim_file.
+ */
+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.
+> 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, 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) {
+    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, 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.';
+    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 skillInput = extractSection(content, ['skill input', 'input', 'intent', 'skill intent']) ||
+        extractLeadParagraph(content) ||
+        '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 for stubs.
+ */
+function parseRegistryRule(content) {
+    const intent = extractSection(content, ['intent']) ||
+        extractLeadParagraph(content) ||
+        'Follow this rule when executing related FRAIM workflows and jobs.';
+    return { intent };
+}

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

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 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');
+        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(filePath, content, metadataBlock.metadata, metadataBlock.bodyStartIndex);
+        }
+        return this.parseSimpleWorkflow(filePath, content);
+    }
+    static parsePhaseBasedWorkflow(filePath, content, metadata, bodyStartIndex) {
+        const contentAfterMetadata = content.substring(bodyStartIndex).trim();
+        const firstPhaseIndex = contentAfterMetadata.search(/^##\s+Phase:/m);
+        let overview = '';
+        let restOfContent = '';
+        if (firstPhaseIndex !== -1) {
+            overview = contentAfterMetadata.substring(0, firstPhaseIndex).trim();
+            restOfContent = contentAfterMetadata.substring(firstPhaseIndex);
+        }
+        else {
+            overview = contentAfterMetadata;
+        }
+        const phases = new Map();
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
+        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();
+            const id = firstLine.split(/[ (]/)[0].trim().toLowerCase();
+            phases.set(id, `## Phase: ${section.trim()}`);
+        }
+        return {
+            metadata,
+            overview,
+            phases,
+            isSimple: false,
+            path: filePath
+        };
+    }
+    static parseSimpleWorkflow(filePath, content) {
+        const workflowName = (0, path_1.basename)(filePath, '.md');
+        const metadata = {
+            name: workflowName
+        };
+        return {
+            metadata,
+            overview: content.trim(),
+            phases: new Map(),
+            isSimple: true,
+            path: filePath
+        };
+    }
+    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;
+    }
+    static extractDescription(filePath) {
+        const wf = this.parse(filePath);
+        if (!wf)
+            return '';
+        const intentMatch = wf.overview.match(/## Intent\s+([\s\S]+?)(?:\r?\n##|$)/);
+        if (intentMatch)
+            return intentMatch[1].trim().split(/\r?\n/)[0];
+        const firstPara = wf.overview.split(/\r?\n/).find(l => l.trim() !== '' && !l.startsWith('#'));
+        return firstPara ? firstPara.trim() : '';
+    }
+}
+exports.WorkflowParser = WorkflowParser;