fraim-framework 2.0.153 → 2.0.159

package/dist/src/core/fraim-config-schema.generated.js

@@ -142,6 +142,14 @@ exports.FRAIM_CONFIG_SCHEMA = {
                         }
                     }
                 },
+                "githubWorkflows": {
+                    "kind": "object",
+                    "properties": {
+                        "enabled": {
+                            "kind": "boolean"
+                        }
+                    }
+                },
                 "validation": {
                     "kind": "object",
                     "properties": {
@@ -198,6 +206,9 @@ exports.FRAIM_CONFIG_SCHEMA = {
                 },
                 "scoreThreshold": {
                     "kind": "number"
+                },
+                "globalPath": {
+                    "kind": "string"
                 }
             }
         },
@@ -262,6 +273,215 @@ exports.FRAIM_CONFIG_SCHEMA = {
                     ]
                 }
             }
+        },
+        "crm": {
+            "kind": "object",
+            "properties": {
+                "provider": {
+                    "kind": "enum",
+                    "values": [
+                        "salesforce",
+                        "customereq"
+                    ]
+                }
+            }
+        },
+        "integrations": {
+            "kind": "object",
+            "properties": {
+                "itsm": {
+                    "kind": "object",
+                    "properties": {
+                        "provider": {
+                            "kind": "enum",
+                            "values": [
+                                "servicenow"
+                            ]
+                        },
+                        "instanceUrl": {
+                            "kind": "string"
+                        }
+                    }
+                },
+                "identity": {
+                    "kind": "object",
+                    "properties": {
+                        "provider": {
+                            "kind": "enum",
+                            "values": [
+                                "microsoft365"
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "automation": {
+            "kind": "object",
+            "properties": {
+                "support": {
+                    "kind": "object",
+                    "properties": {
+                        "startMode": {
+                            "kind": "enum",
+                            "values": [
+                                "manual",
+                                "autonomous"
+                            ]
+                        },
+                        "defaultDecisionMode": {
+                            "kind": "enum",
+                            "values": [
+                                "hitl",
+                                "autonomous"
+                            ]
+                        },
+                        "contextResolver": {
+                            "kind": "object",
+                            "properties": {
+                                "scriptPath": {
+                                    "kind": "string"
+                                },
+                                "arguments": {
+                                    "kind": "array",
+                                    "element": {
+                                        "kind": "string"
+                                    }
+                                },
+                                "timeoutMs": {
+                                    "kind": "number"
+                                }
+                            }
+                        },
+                        "queue": {
+                            "kind": "object",
+                            "properties": {
+                                "provider": {
+                                    "kind": "enum",
+                                    "values": [
+                                        "servicenow",
+                                        "fixture"
+                                    ]
+                                },
+                                "table": {
+                                    "kind": "string"
+                                },
+                                "assignmentGroup": {
+                                    "kind": "string"
+                                },
+                                "claimField": {
+                                    "kind": "string"
+                                },
+                                "fixturePath": {
+                                    "kind": "string"
+                                },
+                                "eligibleStates": {
+                                    "kind": "array",
+                                    "element": {
+                                        "kind": "string"
+                                    }
+                                },
+                                "pollIntervalSeconds": {
+                                    "kind": "number"
+                                },
+                                "successState": {
+                                    "kind": "string"
+                                },
+                                "failureState": {
+                                    "kind": "string"
+                                },
+                                "closeState": {
+                                    "kind": "string"
+                                }
+                            }
+                        },
+                        "requestTypes": {
+                            "kind": "object",
+                            "properties": {
+                                "password_reset": {
+                                    "kind": "object",
+                                    "properties": {
+                                        "mode": {
+                                            "kind": "enum",
+                                            "values": [
+                                                "hitl",
+                                                "autonomous"
+                                            ]
+                                        },
+                                        "requireApprovalState": {
+                                            "kind": "string"
+                                        },
+                                        "selector": {
+                                            "kind": "object",
+                                            "properties": {
+                                                "shortDescriptionContains": {
+                                                    "kind": "array",
+                                                    "element": {
+                                                        "kind": "string"
+                                                    }
+                                                }
+                                            }
+                                        },
+                                        "microsoftPasswordReset": {
+                                            "kind": "object",
+                                            "properties": {
+                                                "resetType": {
+                                                    "kind": "enum",
+                                                    "values": [
+                                                        "temporary_generated",
+                                                        "temporary_provided",
+                                                        "permanent_provided"
+                                                    ]
+                                                },
+                                                "providedPasswordEnvVar": {
+                                                    "kind": "string"
+                                                },
+                                                "forceChangePasswordNextSignIn": {
+                                                    "kind": "boolean"
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                        "communication": {
+                            "kind": "object",
+                            "properties": {
+                                "channel": {
+                                    "kind": "enum",
+                                    "values": [
+                                        "email",
+                                        "sms",
+                                        "teams",
+                                        "manual-handoff"
+                                    ]
+                                },
+                                "deliveryMode": {
+                                    "kind": "enum",
+                                    "values": [
+                                        "direct",
+                                        "operator-relay"
+                                    ]
+                                },
+                                "recipientField": {
+                                    "kind": "enum",
+                                    "values": [
+                                        "requested_for",
+                                        "requested_by"
+                                    ]
+                                },
+                                "includeTemporaryPassword": {
+                                    "kind": "boolean"
+                                },
+                                "messageTemplate": {
+                                    "kind": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     },
     "required": true
@@ -302,6 +522,8 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "customizations.designSystem",
     "customizations.designSystem.path",
     "customizations.designSystem.brand",
+    "customizations.githubWorkflows",
+    "customizations.githubWorkflows.enabled",
     "customizations.validation",
     "customizations.validation.buildCommand",
     "customizations.validation.testSuiteCommand",
@@ -316,6 +538,7 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "learning",
     "learning.lastSynthesisDate",
     "learning.scoreThreshold",
+    "learning.globalPath",
     "customer-communication",
     "customer-communication.productName",
     "customer-communication.productUrl",
@@ -329,5 +552,48 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "stakeholderUpdate.cadence",
     "stakeholderUpdate.historyPath",
     "operatingReview",
-    "operatingReview.cadence"
+    "operatingReview.cadence",
+    "crm",
+    "crm.provider",
+    "integrations",
+    "integrations.itsm",
+    "integrations.itsm.provider",
+    "integrations.itsm.instanceUrl",
+    "integrations.identity",
+    "integrations.identity.provider",
+    "automation",
+    "automation.support",
+    "automation.support.startMode",
+    "automation.support.defaultDecisionMode",
+    "automation.support.contextResolver",
+    "automation.support.contextResolver.scriptPath",
+    "automation.support.contextResolver.arguments",
+    "automation.support.contextResolver.timeoutMs",
+    "automation.support.queue",
+    "automation.support.queue.provider",
+    "automation.support.queue.table",
+    "automation.support.queue.assignmentGroup",
+    "automation.support.queue.claimField",
+    "automation.support.queue.fixturePath",
+    "automation.support.queue.eligibleStates",
+    "automation.support.queue.pollIntervalSeconds",
+    "automation.support.queue.successState",
+    "automation.support.queue.failureState",
+    "automation.support.queue.closeState",
+    "automation.support.requestTypes",
+    "automation.support.requestTypes.password_reset",
+    "automation.support.requestTypes.password_reset.mode",
+    "automation.support.requestTypes.password_reset.requireApprovalState",
+    "automation.support.requestTypes.password_reset.selector",
+    "automation.support.requestTypes.password_reset.selector.shortDescriptionContains",
+    "automation.support.requestTypes.password_reset.microsoftPasswordReset",
+    "automation.support.requestTypes.password_reset.microsoftPasswordReset.resetType",
+    "automation.support.requestTypes.password_reset.microsoftPasswordReset.providedPasswordEnvVar",
+    "automation.support.requestTypes.password_reset.microsoftPasswordReset.forceChangePasswordNextSignIn",
+    "automation.support.communication",
+    "automation.support.communication.channel",
+    "automation.support.communication.deliveryMode",
+    "automation.support.communication.recipientField",
+    "automation.support.communication.includeTemporaryPassword",
+    "automation.support.communication.messageTemplate"
 ];

package/dist/src/core/utils/fraim-labels.js

@@ -0,0 +1,182 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAIM_STATUS_LABELS = exports.FRAIM_PHASE_LABELS = exports.LEGACY_FRAIM_STATUS_LABELS = void 0;
+exports.isFraimPhaseLabel = isFraimPhaseLabel;
+exports.isFraimStatusLabel = isFraimStatusLabel;
+exports.isLegacyFraimStatusLabel = isLegacyFraimStatusLabel;
+exports.normalizeFraimPhaseLabel = normalizeFraimPhaseLabel;
+exports.normalizeFraimStatusLabel = normalizeFraimStatusLabel;
+exports.partitionFraimLabels = partitionFraimLabels;
+exports.mergeFraimGitHubLabels = mergeFraimGitHubLabels;
+exports.applyIssueStatusTransition = applyIssueStatusTransition;
+exports.applyIssuePhaseTransition = applyIssuePhaseTransition;
+exports.applyIssuePhaseAndStatusTransition = applyIssuePhaseAndStatusTransition;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const REQUIRED_FRAIM_PHASE_LABELS = [
+    'phase:spec',
+    'phase:design',
+    'phase:tests',
+    'phase:impl'
+];
+const REQUIRED_FRAIM_STATUS_LABELS = [
+    'status:wip',
+    'status:needs-review',
+    'status:complete'
+];
+exports.LEGACY_FRAIM_STATUS_LABELS = [
+    'status:in-progress',
+    'status:design-review-passed'
+];
+function normalizeLabel(label) {
+    return label.trim().toLowerCase();
+}
+function findLabelsCatalogPath() {
+    let currentDir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const candidate = path_1.default.join(currentDir, 'labels.json');
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+        const parentDir = path_1.default.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    const cwdCandidate = path_1.default.join(process.cwd(), 'labels.json');
+    if (fs_1.default.existsSync(cwdCandidate)) {
+        return cwdCandidate;
+    }
+    throw new Error('labels.json not found; FRAIM GitHub label helpers require the repo label catalog.');
+}
+function loadCatalogLabels() {
+    const catalogPath = findLabelsCatalogPath();
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(catalogPath, 'utf8'));
+        return new Set(parsed
+            .map((entry) => (typeof entry?.name === 'string' ? normalizeLabel(entry.name) : ''))
+            .filter(Boolean));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read labels.json for FRAIM GitHub label helpers: ${message}`);
+    }
+}
+function requireCatalogLabels(expected, kind) {
+    const catalogLabels = loadCatalogLabels();
+    const missing = expected.filter((label) => !catalogLabels.has(label));
+    if (missing.length > 0) {
+        throw new Error(`labels.json is missing canonical FRAIM ${kind} labels: ${missing.join(', ')}`);
+    }
+    return expected;
+}
+exports.FRAIM_PHASE_LABELS = requireCatalogLabels(REQUIRED_FRAIM_PHASE_LABELS, 'phase');
+exports.FRAIM_STATUS_LABELS = requireCatalogLabels(REQUIRED_FRAIM_STATUS_LABELS, 'status');
+const FRAIM_PHASE_LABEL_SET = new Set(exports.FRAIM_PHASE_LABELS);
+const FRAIM_STATUS_LABEL_SET = new Set(exports.FRAIM_STATUS_LABELS);
+const LEGACY_FRAIM_STATUS_LABEL_SET = new Set(exports.LEGACY_FRAIM_STATUS_LABELS);
+function dedupeLabels(labels) {
+    const seen = new Set();
+    const deduped = [];
+    for (const rawLabel of labels) {
+        const trimmed = rawLabel.trim();
+        if (!trimmed)
+            continue;
+        const normalized = normalizeLabel(trimmed);
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        deduped.push(trimmed);
+    }
+    return deduped;
+}
+function mapLegacyStatus(label) {
+    const normalized = normalizeLabel(label);
+    switch (normalized) {
+        case 'status:in-progress':
+            return 'status:wip';
+        case 'status:design-review-passed':
+            return 'status:complete';
+        default:
+            return null;
+    }
+}
+function isFraimPhaseLabel(label) {
+    return FRAIM_PHASE_LABEL_SET.has(normalizeLabel(label));
+}
+function isFraimStatusLabel(label) {
+    return FRAIM_STATUS_LABEL_SET.has(normalizeLabel(label));
+}
+function isLegacyFraimStatusLabel(label) {
+    return LEGACY_FRAIM_STATUS_LABEL_SET.has(normalizeLabel(label));
+}
+function normalizeFraimPhaseLabel(label) {
+    const normalized = normalizeLabel(label);
+    if (!FRAIM_PHASE_LABEL_SET.has(normalized)) {
+        throw new Error(`Unsupported FRAIM phase label: ${label}`);
+    }
+    return normalized;
+}
+function normalizeFraimStatusLabel(label) {
+    const normalized = normalizeLabel(label);
+    if (FRAIM_STATUS_LABEL_SET.has(normalized)) {
+        return normalized;
+    }
+    const mappedLegacy = mapLegacyStatus(normalized);
+    if (mappedLegacy) {
+        return mappedLegacy;
+    }
+    throw new Error(`Unsupported FRAIM status label: ${label}`);
+}
+function partitionFraimLabels(labels) {
+    const nonFraimLabels = [];
+    const phaseLabels = [];
+    const statusLabels = [];
+    for (const label of dedupeLabels(labels)) {
+        if (isFraimPhaseLabel(label)) {
+            phaseLabels.push(normalizeFraimPhaseLabel(label));
+            continue;
+        }
+        if (isFraimStatusLabel(label) || isLegacyFraimStatusLabel(label)) {
+            statusLabels.push(normalizeFraimStatusLabel(label));
+            continue;
+        }
+        nonFraimLabels.push(label);
+    }
+    return {
+        nonFraimLabels,
+        phaseLabels,
+        statusLabels
+    };
+}
+function mergeFraimGitHubLabels(labels, updates) {
+    const { nonFraimLabels, phaseLabels, statusLabels } = partitionFraimLabels(labels);
+    const nextPhase = updates.phase
+        ? normalizeFraimPhaseLabel(updates.phase)
+        : phaseLabels[0];
+    const nextStatus = updates.status
+        ? normalizeFraimStatusLabel(updates.status)
+        : statusLabels[0];
+    const merged = [...nonFraimLabels];
+    if (nextPhase)
+        merged.push(nextPhase);
+    if (nextStatus)
+        merged.push(nextStatus);
+    return dedupeLabels(merged);
+}
+function applyIssueStatusTransition(labels, status) {
+    return mergeFraimGitHubLabels(labels, { status });
+}
+function applyIssuePhaseTransition(labels, phase) {
+    return mergeFraimGitHubLabels(labels, {
+        phase,
+        status: 'status:wip'
+    });
+}
+function applyIssuePhaseAndStatusTransition(labels, phase, status) {
+    return mergeFraimGitHubLabels(labels, { phase, status });
+}

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

@@ -32,11 +32,32 @@ function isExplicitLocalRepoPath(repoUrl) {
         trimmed.startsWith('../') ||
         trimmed.startsWith('file://'));
 }
+function readExplicitPortFromEnv() {
+    for (const value of [
+        process.env.PLAYWRIGHT_FRAIM_MCP_PORT,
+        process.env.PLAYWRIGHT_WEBSITE_PORT,
+        process.env.FRAIM_MCP_PORT,
+        process.env.PORT,
+        process.env.WEBSITES_PORT
+    ]) {
+        const port = Number(value);
+        if (Number.isFinite(port) && port > 0) {
+            return port;
+        }
+    }
+    return null;
+}
 /**
  * Gets a unique port based on the current git branch name (if it's an issue branch)
  * Default to 15302 if not on an issue branch
  */
 function getPort() {
+    // Explicit runtime ports must win so tests and subprocesses all resolve the
+    // same active server instead of drifting back to a branch-derived default.
+    const explicitPort = readExplicitPortFromEnv();
+    if (explicitPort) {
+        return explicitPort;
+    }
     try {
         const branchName = process.env.FRAIM_BRANCH || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
         // Match issue-123 or 123-feature-name or feature/123-name
@@ -50,7 +71,7 @@ function getPort() {
     catch (e) {
         // Silently fail and use default
     }
-    return Number(process.env.PORT) || Number(process.env.WEBSITES_PORT) || Number(process.env.FRAIM_MCP_PORT) || 15302;
+    return 15302;
 }
 /**
  * Determines the database name based on the git branch

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

@@ -9,7 +9,12 @@ exports.workspaceFraimExists = workspaceFraimExists;
 exports.getWorkspaceConfigPath = getWorkspaceConfigPath;
 exports.getWorkspaceFraimPath = getWorkspaceFraimPath;
 exports.getWorkspaceFraimDisplayPath = getWorkspaceFraimDisplayPath;
+exports.getUserFraimDisplayPath = getUserFraimDisplayPath;
 exports.getUserFraimDirPath = getUserFraimDirPath;
+exports.getUserFraimLearningsDir = getUserFraimLearningsDir;
+exports.getWorkspaceLearningsDir = getWorkspaceLearningsDir;
+exports.getConfiguredPortableLearningsDir = getConfiguredPortableLearningsDir;
+exports.getConfiguredPortableLearningsDisplayPath = getConfiguredPortableLearningsDisplayPath;
 exports.getEffectiveFraimDir = getEffectiveFraimDir;
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -24,6 +29,9 @@ exports.WORKSPACE_SYNCED_CONTENT_DIRS = [
 function normalizeRelativePath(relativePath) {
     return relativePath.replace(/^[\\/]+/, '').replace(/[\\/]+/g, '/');
 }
+function normalizeDisplayPath(fullPath) {
+    return fullPath.replace(/\\/g, '/');
+}
 function getWorkspaceFraimDir(projectRoot = process.cwd()) {
     return (0, path_1.join)(projectRoot, exports.WORKSPACE_FRAIM_DIRNAME);
 }
@@ -42,6 +50,10 @@ function getWorkspaceFraimDisplayPath(relativePath = '') {
         ? `${exports.WORKSPACE_FRAIM_DIRNAME}/${normalized}`
         : `${exports.WORKSPACE_FRAIM_DIRNAME}/`;
 }
+function getUserFraimDisplayPath(relativePath = '') {
+    const normalized = normalizeRelativePath(relativePath);
+    return normalized.length > 0 ? `~/.fraim/${normalized}` : '~/.fraim/';
+}
 /**
  * Get the user-level FRAIM directory (~/.fraim/).
  * Can be overridden with FRAIM_USER_DIR env var for testing.
@@ -49,6 +61,52 @@ function getWorkspaceFraimDisplayPath(relativePath = '') {
 function getUserFraimDirPath() {
     return process.env.FRAIM_USER_DIR || (0, path_1.join)(os_1.default.homedir(), '.fraim');
 }
+function getUserFraimLearningsDir() {
+    return (0, path_1.join)(getUserFraimDirPath(), 'personalized-employee', 'learnings');
+}
+function getWorkspaceLearningsDir(projectRoot = process.cwd()) {
+    return getWorkspaceFraimPath(projectRoot, 'personalized-employee', 'learnings');
+}
+function resolveConfiguredLearningGlobalPath(rawPath) {
+    if (typeof rawPath !== 'string')
+        return null;
+    const trimmed = rawPath.trim();
+    if (!trimmed)
+        return null;
+    if (/^[a-z]+:\/\//i.test(trimmed))
+        return null;
+    if (trimmed.startsWith('~')) {
+        const homeRelative = trimmed.slice(1).replace(/^[\\/]+/, '');
+        return (0, path_1.normalize)((0, path_1.join)(os_1.default.homedir(), homeRelative));
+    }
+    if (!(0, path_1.isAbsolute)(trimmed))
+        return null;
+    return (0, path_1.normalize)(trimmed);
+}
+function readWorkspaceConfig(projectRoot) {
+    try {
+        const configPath = getWorkspaceConfigPath(projectRoot);
+        if (!(0, fs_1.existsSync)(configPath))
+            return null;
+        return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getConfiguredPortableLearningsDir(projectRoot = process.cwd()) {
+    const config = readWorkspaceConfig(projectRoot);
+    const configured = resolveConfiguredLearningGlobalPath(config?.learning?.globalPath);
+    return configured || getUserFraimLearningsDir();
+}
+function getConfiguredPortableLearningsDisplayPath(projectRoot = process.cwd()) {
+    const config = readWorkspaceConfig(projectRoot);
+    const configured = resolveConfiguredLearningGlobalPath(config?.learning?.globalPath);
+    if (configured) {
+        return normalizeDisplayPath(configured);
+    }
+    return getUserFraimDisplayPath('personalized-employee/learnings').replace(/\/$/, '');
+}
 /**
  * Determine the effective FRAIM content root directory.
  *

package/dist/src/first-run/types.js

@@ -60,7 +60,7 @@ function createInitialRows() {
         { id: 'node', label: 'Node.js', status: 'pending', verb: "we'll install" },
         { id: 'git', label: 'git', status: 'pending', verb: "we'll install", optional: true },
         { id: 'fraim', label: 'FRAIM', status: 'pending', verb: "we'll set up FRAIM" },
-        { id: 'agent', label: 'AI Employees', status: 'pending', verb: "we'll check for AI Employees" },
+        { id: 'agent', label: 'Execution surfaces', status: 'pending', verb: "we'll detect execution surfaces" },
     ];
 }
 /**