fraim-framework 2.0.101 → 2.0.103

package/dist/src/cli/commands/init-project.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initProjectCommand = exports.runInitProject = void 0;
+exports.initProjectCommand = exports.runInitProject = exports.findProjectFile = void 0;
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -70,12 +70,41 @@ const checkGlobalSetup = () => {
         return { exists: true, mode: 'integrated', tokens: {} };
     }
 };
+// Robust path resolution utility - walks up directory tree to find target
+const findProjectFile = (filename) => {
+    let currentDir = __dirname;
+    // Walk up the directory tree to find the target file/directory
+    for (let i = 0; i < 10; i++) { // Limit to prevent infinite loop
+        const targetPath = path_1.default.join(currentDir, filename);
+        if (fs_1.default.existsSync(targetPath)) {
+            return targetPath;
+        }
+        const parentDir = path_1.default.dirname(currentDir);
+        if (parentDir === currentDir)
+            break; // Reached root
+        currentDir = parentDir;
+    }
+    // Fallback: try from process.cwd()
+    const cwdTarget = path_1.default.join(process.cwd(), filename);
+    if (fs_1.default.existsSync(cwdTarget)) {
+        return cwdTarget;
+    }
+    // Last resort: use relative path from __dirname
+    return path_1.default.join(__dirname, '..', '..', '..', filename);
+};
+exports.findProjectFile = findProjectFile;
+;
 const installGitHubWorkflows = (projectRoot) => {
     const workflowsDir = path_1.default.join(projectRoot, '.github', 'workflows');
-    const registryDir = fs_1.default.existsSync(path_1.default.join(__dirname, '..', '..', '..', 'registry'))
-        ? path_1.default.join(__dirname, '..', '..', '..', 'registry')
-        : path_1.default.join(__dirname, '..', '..', 'registry');
+    const registryDir = (0, exports.findProjectFile)('registry');
     const sourceDir = path_1.default.join(registryDir, 'github', 'workflows');
+    if (!fs_1.default.existsSync(sourceDir)) {
+        console.log(chalk_1.default.yellow(`Warning: GitHub workflows source directory not found: ${sourceDir}`));
+        console.log(chalk_1.default.gray(`Registry directory: ${registryDir}`));
+        console.log(chalk_1.default.gray(`Current __dirname: ${__dirname}`));
+        console.log(chalk_1.default.gray(`Process cwd: ${process.cwd()}`));
+        return;
+    }
     if (!fs_1.default.existsSync(workflowsDir)) {
         fs_1.default.mkdirSync(workflowsDir, { recursive: true });
     }
@@ -101,9 +130,10 @@ const createGitHubLabels = (projectRoot) => {
         console.log(chalk_1.default.gray('Install gh CLI to enable automatic label creation: https://cli.github.com/'));
         return;
     }
-    const labelsPath = path_1.default.join(__dirname, '..', '..', '..', 'labels.json');
+    const labelsPath = (0, exports.findProjectFile)('labels.json');
     if (!fs_1.default.existsSync(labelsPath)) {
         console.log(chalk_1.default.yellow('labels.json not found. Skipping label creation.'));
+        console.log(chalk_1.default.gray(`Searched from: ${__dirname}`));
         return;
     }
     try {

package/dist/src/cli/commands/setup.js

@@ -146,6 +146,33 @@ const promptForMode = async () => {
     }
     return response.mode;
 };
+/**
+ * Sanitize a token by removing control characters that cause JSON serialization issues
+ */
+const sanitizeToken = (token) => {
+    if (!token)
+        return token;
+    // Remove control characters (0x00-0x1F and 0x7F) that cause JSON escaping issues
+    // These characters are not valid in API tokens and are likely copy-paste artifacts
+    return token.replace(/[\x00-\x1F\x7F]/g, '');
+};
+/**
+ * Sanitize all tokens in a ProviderTokens object
+ */
+const sanitizeTokens = (tokens) => {
+    const sanitized = {};
+    Object.entries(tokens).forEach(([providerId, token]) => {
+        if (token) {
+            const originalToken = token;
+            const sanitizedToken = sanitizeToken(token);
+            if (originalToken !== sanitizedToken) {
+                console.log(chalk_1.default.yellow(`⚠️  Sanitized ${providerId} token: removed ${originalToken.length - sanitizedToken.length} control character(s)`));
+            }
+            sanitized[providerId] = sanitizedToken;
+        }
+    });
+    return sanitized;
+};
 const saveGlobalConfig = (fraimKey, mode, tokens, configs) => {
     const globalConfigDir = (0, script_sync_utils_1.getUserFraimDir)();
     const globalConfigPath = path_1.default.join(globalConfigDir, 'config.json');
@@ -162,6 +189,8 @@ const saveGlobalConfig = (fraimKey, mode, tokens, configs) => {
             // Ignore parse errors, will create new config
         }
     }
+    // Sanitize tokens before saving to prevent JSON serialization issues
+    const sanitizedTokens = sanitizeTokens(tokens);
     // Merge provider configs (e.g., jiraConfig)
     const providerConfigs = { ...(existingConfig.providerConfigs || {}) };
     Object.entries(configs).forEach(([providerId, config]) => {
@@ -176,7 +205,7 @@ const saveGlobalConfig = (fraimKey, mode, tokens, configs) => {
         mode: mode,
         tokens: {
             ...(existingConfig.tokens || {}),
-            ...tokens
+            ...sanitizedTokens
         },
         providerConfigs,
         configuredAt: new Date().toISOString(),
@@ -594,7 +623,7 @@ const runSetup = async (options) => {
     console.log(chalk_1.default.cyan('\n📝 For future projects:'));
     console.log(chalk_1.default.cyan('   1. cd into any project directory'));
     console.log(chalk_1.default.cyan('   2. Run: fraim init-project'));
-    console.log(chalk_1.default.cyan('   3. Tell your AI agent: "Onboard this project"'));
+    console.log(chalk_1.default.cyan('   3. Ask your AI agent: "FRAIM was just installed. Read the FRAIM docs, explain what it can do for me, then run project-onboarding."'));
     if (mode === 'integrated') {
         const allProviderIds = await (0, provider_registry_1.getAllProviderIds)();
         const unconfiguredProviders = allProviderIds.filter(id => !tokens[id]);

package/dist/src/cli/utils/agent-adapters.js

@@ -10,6 +10,7 @@ const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const START_MARKER = '<!-- FRAIM_AGENT_ADAPTER_START -->';
 const END_MARKER = '<!-- FRAIM_AGENT_ADAPTER_END -->';
 const CURSOR_RULE_PATH = path_1.default.join('.cursor', 'rules', 'fraim.mdc');
+const CLAUDE_FRAIM_COMMAND_PATH = path_1.default.join('.claude', 'commands', 'fraim.md');
 const CURSOR_FRONTMATTER = `---
 description: FRAIM discovery and execution contract
 alwaysApply: true
@@ -59,9 +60,14 @@ This repository uses FRAIM.
 - Skills under \`${employeeSkillsPath}/\` are reusable capabilities that jobs compose.
 - Rules under \`${employeeRulesPath}/\` are always-on constraints and conventions.
 - Repo-specific overrides and learning artifacts live under \`${personalizedRootPath}/\` and take precedence over synced baseline content.
-- Use stub filenames and summaries to discover what to invoke. Once you identify a relevant job, call \`get_fraim_job({ job: "<job-name>" })\`.
+- Before acting on any user request, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections to match the request to the right job.
+- Once you identify the relevant job, call \`get_fraim_job({ job: "<job-name>" })\` to get the full phased instructions.
 - For deeper capability detail, call \`get_fraim_file({ path: "skills/<category>/<skill-name>.md" })\` or \`get_fraim_file({ path: "rules/<category>/<rule-name>.md" })\`.
 - Read \`${projectRulesPath}\` if it exists before doing work.
+- When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
+
+> [!IMPORTANT]
+> **Job stubs are for discovery only.** When a user @mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
 `);
     const cursorManagedBody = buildManagedSection(`
 Use FRAIM as the repo's execution framework.
@@ -72,6 +78,7 @@ Use FRAIM as the repo's execution framework.
 - Rules are always-on constraints.
 - Repo-specific overrides and learnings under \`${personalizedRootPath}/\` take precedence.
 - Choose a relevant job from the stubs, then call \`get_fraim_job(...)\` for the full phased instructions.
+- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const copilotBody = buildManagedSection(`
 ## FRAIM
@@ -82,6 +89,7 @@ Use FRAIM as the repo's execution framework.
 - FRAIM rules are always-on constraints and conventions.
 - Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
 - Use the stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const fraimReadme = `# FRAIM Catalog
 
@@ -94,13 +102,26 @@ This directory is the repository-visible FRAIM surface.
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
 Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools.
+`;
+    const claudeCommand = `The user wants to run FRAIM. The requested job or topic is: $ARGUMENTS
+
+Follow this process:
+
+1. **If no argument was given** (the line above ends with ": "): scan all stub files under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\`. List each by filename and its Intent line. Ask the user which job they want to run, then proceed to step 2.
+
+2. **Find the job**: search \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` for a stub whose filename (without \`.md\`) matches or closely resembles the argument. Read the stub's Intent/Outcome to confirm it matches what the user wants.
+
+3. **Load the full job**: call \`get_fraim_job({ job: "<matched-job-name>" })\` — never execute from stub content.
+
+4. **Execute**: follow the phased instructions returned by \`get_fraim_job\`, using \`seekMentoring\` at phase transitions where indicated.
 `;
     return [
         { path: 'AGENTS.md', content: markdownBody },
         { path: 'CLAUDE.md', content: markdownBody },
         { path: path_1.default.join('.github', 'copilot-instructions.md'), content: copilotBody },
         { path: CURSOR_RULE_PATH, content: cursorManagedBody },
-        { path: path_1.default.join(project_fraim_paths_1.WORKSPACE_FRAIM_DIRNAME, 'README.md'), content: fraimReadme }
+        { path: path_1.default.join(project_fraim_paths_1.WORKSPACE_FRAIM_DIRNAME, 'README.md'), content: fraimReadme },
+        { path: CLAUDE_FRAIM_COMMAND_PATH, content: claudeCommand }
     ];
 }
 function ensureAgentAdapterFiles(projectRoot) {
@@ -114,7 +135,7 @@ function ensureAgentAdapterFiles(projectRoot) {
         const existing = fs_1.default.existsSync(fullPath) ? fs_1.default.readFileSync(fullPath, 'utf8') : '';
         const next = file.path === CURSOR_RULE_PATH
             ? mergeCursorRule(existing, file.content)
-            : file.path.endsWith('README.md')
+            : file.path.endsWith('README.md') || file.path === CLAUDE_FRAIM_COMMAND_PATH
                 ? file.content
                 : mergeManagedSection(existing, file.content);
         if (existing !== next) {

package/dist/src/cli/utils/version-utils.js

@@ -10,12 +10,11 @@ function getFraimVersion() {
     // Try reliable paths to find package.json relative to this file
     // locally: src/cli/utils/version-utils.ts -> package.json is ../../../package.json
     // dist: dist/src/cli/utils/version-utils.js -> package.json is ../../../../package.json
-    const possiblePaths = [
-        path_1.default.join(__dirname, '../../../package.json'), // Local dev (src)
-        path_1.default.join(__dirname, '../../../../package.json'), // Dist (dist/src)
-        path_1.default.join(process.cwd(), 'package.json') // Fallback to CWD
-    ];
-    for (const pkgPath of possiblePaths) {
+    // Traverse up from __dirname until we find fraim-framework's package.json.
+    // Fixed relative paths break when npx cache layouts differ across OS/npm versions.
+    let dir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path_1.default.join(dir, 'package.json');
         if (fs_1.default.existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf-8'));
@@ -27,6 +26,10 @@ function getFraimVersion() {
                 // Ignore parsing errors
             }
         }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break; // Reached filesystem root
+        dir = parent;
     }
-    return '1.0.0'; // Fallback
+    return 'unknown'; // Do not return a fake version — unknown is safer than misleading
 }

package/dist/src/local-mcp-server/usage-collector.js

@@ -4,11 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageCollector = void 0;
-const mongodb_1 = require("mongodb");
 const axios_1 = __importDefault(require("axios"));
-// A placeholder ObjectId used when the real API key ID is not yet known.
-// The server will override this with the correct ID from the authenticated API key.
-const PLACEHOLDER_API_KEY_ID = new mongodb_1.ObjectId('000000000000000000000000');
 /**
  * UsageCollector is responsible for collecting usage events from MCP tools
  * and formatting them for the analytics system.
@@ -16,7 +12,7 @@ const PLACEHOLDER_API_KEY_ID = new mongodb_1.ObjectId('000000000000000000000000'
 class UsageCollector {
     constructor() {
         this.events = [];
-        this.apiKeyId = null;
+        this.userId = null;
     }
     static resolveMentoringJobName(args) {
         if (!args || typeof args !== 'object') {
@@ -35,10 +31,10 @@ class UsageCollector {
         return 'unknown';
     }
     /**
-     * Set the API key ID for this session
+     * Set the user ID for this session
      */
-    setApiKeyId(apiKeyId) {
-        this.apiKeyId = apiKeyId;
+    setUserId(userId) {
+        this.userId = userId;
     }
     /**
      * Collect MCP tool call event
@@ -61,9 +57,8 @@ class UsageCollector {
         const event = {
             type: parsed.type,
             name: parsed.name,
-            // Use set apiKeyId if available, otherwise a placeholder.
-            // The server will override this with the correct ID from the authenticated API key.
-            apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
+            // Use set userId if available; the server will override with the authenticated userId.
+            userId: this.userId || 'unknown',
             sessionId,
             success,
             category: parsed.category,
@@ -83,9 +78,7 @@ class UsageCollector {
             type,
             name,
             category,
-            // Use set apiKeyId if available, otherwise a placeholder.
-            // The server will override this with the correct value from the auth token.
-            apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
+            userId: this.userId || 'unknown',
             sessionId,
             success,
             args

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.101",
+  "version": "2.0.103",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {