fraim-framework 2.0.124 → 2.0.126

package/dist/src/local-mcp-server/codex-token-adapter.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Codex Token Adapter — Issue #330 / R1.3
+ *
+ * Reads Codex CLI's per-session JSONL log at
+ * `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`, sums
+ * cumulative per-turn token counts, and converts to USD via the static
+ * price table.
+ *
+ * Verified against Codex CLI 0.125.0 session files. Token counts live at
+ * `event_msg.payload.info.total_token_usage.{input_tokens, output_tokens,
+ * cached_input_tokens, reasoning_output_tokens}`. Model lives on
+ * `turn_context.payload.model` (latest turn wins).
+ *
+ * Compliance: only counter values + model identifier exit this module.
+ * Prompt content, file paths, and other JSONL fields are explicitly
+ * dropped so PII never enters telemetry (C1).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureCodexSnapshot = captureCodexSnapshot;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const agent_token_prices_js_1 = require("./agent-token-prices.js");
+/**
+ * Read the Codex session file and produce a TokenSnapshot. Returns null
+ * (with optional log warning) if the file is missing, unreadable, or
+ * contains no token_count events.
+ */
+async function captureCodexSnapshot(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 250;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    const file = opts.sessionFile ?? findLatestSessionFile(opts.sessionsRoot);
+    if (!file) {
+        opts.log?.('codex adapter: no session file found in ~/.codex/sessions');
+        return null;
+    }
+    let contents;
+    try {
+        contents = await fs.promises.readFile(file, 'utf8');
+    }
+    catch (err) {
+        opts.log?.(`codex adapter: cannot read ${file}: ${err.message}`);
+        return null;
+    }
+    let model = null;
+    let sessionId = null;
+    // Codex `total_token_usage` is cumulative; we use the highest seen
+    // (= most-recent cumulative) so partial reads during an active write
+    // don't regress.
+    let lastInput = 0;
+    let lastOutput = 0;
+    let lastCacheRead = 0;
+    let lastReasoningOutput = 0;
+    let foundAny = false;
+    const lines = contents.split('\n');
+    for (const line of lines) {
+        if (Date.now() > deadline) {
+            opts.log?.(`codex adapter: timeout after ${timeoutMs}ms; partial result`);
+            break;
+        }
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue; // skip malformed lines
+        }
+        if (!row || typeof row !== 'object')
+            continue;
+        // session_meta carries session id (model is not on this event).
+        if (row.type === 'session_meta' && row.payload && typeof row.payload === 'object') {
+            if (typeof row.payload.id === 'string')
+                sessionId = row.payload.id;
+            continue;
+        }
+        // turn_context carries the active model. Latest turn wins.
+        if (row.type === 'turn_context' && row.payload && typeof row.payload === 'object') {
+            if (typeof row.payload.model === 'string')
+                model = row.payload.model;
+            continue;
+        }
+        // event_msg with payload.type === 'token_count' carries cumulative usage.
+        if (row.type === 'event_msg' && row.payload && row.payload.type === 'token_count') {
+            const info = row.payload.info;
+            if (info && typeof info === 'object' && info.total_token_usage && typeof info.total_token_usage === 'object') {
+                const t = info.total_token_usage;
+                const i = numberOrZero(t.input_tokens);
+                const o = numberOrZero(t.output_tokens);
+                const cr = numberOrZero(t.cached_input_tokens);
+                const r = numberOrZero(t.reasoning_output_tokens);
+                if (i > lastInput)
+                    lastInput = i;
+                if (o > lastOutput)
+                    lastOutput = o;
+                if (cr > lastCacheRead)
+                    lastCacheRead = cr;
+                if (r > lastReasoningOutput)
+                    lastReasoningOutput = r;
+                foundAny = true;
+            }
+        }
+    }
+    if (!foundAny)
+        return null;
+    // Reasoning-output tokens are billed as output tokens by OpenAI today;
+    // fold them into the output count so the cost computation lines up
+    // with the user's bill.
+    const counts = {
+        inputTokens: lastInput,
+        outputTokens: lastOutput + lastReasoningOutput,
+        cacheReadTokens: lastCacheRead,
+        cacheCreationTokens: 0,
+    };
+    const costUsd = (0, agent_token_prices_js_1.computeCostUsd)('codex', model ?? undefined, counts);
+    // C1 — only the listed fields exit this module. No spread of row data,
+    // no prompt/content fields, no file paths.
+    return {
+        inputTokens: counts.inputTokens,
+        outputTokens: counts.outputTokens,
+        cacheReadTokens: counts.cacheReadTokens,
+        cacheCreationTokens: counts.cacheCreationTokens,
+        costUsd,
+        claudeSessionId: sessionId,
+        model,
+        capturedAt: new Date(),
+    };
+}
+function numberOrZero(v) {
+    return typeof v === 'number' && isFinite(v) ? v : 0;
+}
+/**
+ * Find the most recently modified `rollout-*.jsonl` under
+ * `~/.codex/sessions/YYYY/MM/DD/`. Returns null if the directory does not
+ * exist or is empty.
+ */
+function findLatestSessionFile(sessionsRoot) {
+    try {
+        const root = sessionsRoot ?? path.join(os.homedir(), '.codex', 'sessions');
+        if (!fs.existsSync(root))
+            return null;
+        let latestPath = null;
+        let latestMtime = 0;
+        // Walk YYYY / MM / DD / rollout-*.jsonl. Bounded to three levels so
+        // a stray symlink can't blow up the scan.
+        const years = safeReaddir(root);
+        for (const year of years) {
+            const yearDir = path.join(root, year);
+            if (!isDirectory(yearDir))
+                continue;
+            for (const month of safeReaddir(yearDir)) {
+                const monthDir = path.join(yearDir, month);
+                if (!isDirectory(monthDir))
+                    continue;
+                for (const day of safeReaddir(monthDir)) {
+                    const dayDir = path.join(monthDir, day);
+                    if (!isDirectory(dayDir))
+                        continue;
+                    for (const entry of safeReaddir(dayDir)) {
+                        if (!entry.endsWith('.jsonl'))
+                            continue;
+                        const full = path.join(dayDir, entry);
+                        try {
+                            const stat = fs.statSync(full);
+                            if (stat.mtimeMs > latestMtime) {
+                                latestMtime = stat.mtimeMs;
+                                latestPath = full;
+                            }
+                        }
+                        catch { /* skip unreadable */ }
+                    }
+                }
+            }
+        }
+        return latestPath;
+    }
+    catch {
+        return null;
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -222,12 +222,19 @@ function readFrontmatter(content) {
     }
     return frontmatter;
 }
+function isRetrospectiveSynthesized(value) {
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    return normalized !== 'false' && normalized !== 'no' && normalized !== '0' && normalized !== 'null';
+}
 function isUnsynthesizedRetrospective(filePath) {
     try {
         const content = (0, fs_1.readFileSync)(filePath, 'utf8');
         const frontmatter = readFrontmatter(content);
-        const synthesized = frontmatter.synthesized?.toLowerCase();
-        return synthesized !== 'true' && synthesized !== 'yes';
+        return !isRetrospectiveSynthesized(frontmatter.synthesized);
     }
     catch {
         return false;
@@ -340,7 +347,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
         if (l2PrefPresent)
             section += `\`${LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
         if (l2CoachPresent)
-            section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (manager-facing; all entries)\n`;
         if (l2ValidatedPresent)
             section += `\`${LEARNINGS_REL}/org-validated-patterns.md\`  (entries above score threshold)\n`;
         const l2DormantTotal = (l2MistakeStats?.dormant || 0) + (l2ValidatedStats?.dormant || 0);
@@ -354,7 +361,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
         if (l1PrefPresent)
             section += `\`${LEARNINGS_REL}/${resolvedUserId}-preferences.md\`  (all entries)\n`;
         if (l1CoachPresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (manager-facing; all entries)\n`;
         if (l1MistakePresent)
             section += `\`${LEARNINGS_REL}/${resolvedUserId}-mistake-patterns.md\`  (entries above score threshold)\n`;
         if (l1ValidatedPresent)
@@ -371,7 +378,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
             section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
         }
         if (l0RetroCount > 0) {
-            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with \`synthesized: false\` or missing\n`;
+            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with unsynthesized or missing \`synthesized\` frontmatter\n`;
         }
         section += '\n';
     }
@@ -381,20 +388,26 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     const backlogTriggered = totalL0 >= BACKLOG_MIN || (oldestAgeDays >= OLDEST_AGE_DAYS_TRIGGER && totalL0 > 0);
     if (forJob) {
         if (hasL2 || hasL1) {
-            section += 'Use the relevant patterns, preferences, and coaching signals in this job.\n';
+            section += 'Use the relevant patterns and preferences in this job.\n';
+            if (l1CoachPresent || l2CoachPresent) {
+                section += 'Treat manager-coaching as feedback for how the manager should continue or improve managing AI, not as agent instruction.\n';
+            }
         }
         if (backlogTriggered) {
             section += '\n';
-            section += `Warning: ${totalL0} unprocessed signals pending. Consider running \`end-of-day-debrief\` before starting today's work.\n`;
+            section += `Warning: ${totalL0} unprocessed signals pending. Consider running \`sleep-on-learnings\` before starting today's work.\n`;
             section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }
     else {
         section += 'Use this synthesized learning context throughout the session.\n';
+        if (l1CoachPresent || l2CoachPresent) {
+            section += 'Manager-coaching entries are manager-facing feedback, not instructions for the AI to follow.\n';
+        }
         if (backlogTriggered) {
             section += '\n';
             section += `Warning: synthesis overdue with ${totalL0} unprocessed signals.\n`;
-            section += 'Run `end-of-day-debrief` before starting today\'s work.\n';
+            section += 'Run `sleep-on-learnings` before starting today\'s work.\n';
             section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }

package/dist/src/local-mcp-server/stdio-server.js

@@ -33,6 +33,7 @@ const quality_evidence_1 = require("../core/quality-evidence");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
 const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
+const token_adapter_registry_js_1 = require("./token-adapter-registry.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
 /**
  * Handle template substitution logic separately for better testability
@@ -617,9 +618,10 @@ class FraimLocalMCPServer {
                 // Fall back to config if git fails
                 repoUrl = this.config?.repository?.url || '';
             }
+            const workspaceLabel = (0, path_1.parse)(projectDir).base || 'workspace';
             if (!repoUrl) {
-                this.log('No git repository found and no config available');
-                return null;
+                this.log(`No git repository found; falling back to workspace folder label: ${workspaceLabel}`);
+                repoUrl = workspaceLabel;
             }
             // Parse repository identity from URL
             let name = '';
@@ -646,6 +648,9 @@ class FraimLocalMCPServer {
                 name = segments[segments.length - 1] || '';
                 namespace = segments.slice(0, -1).join('/');
             }
+            else if (!repoUrl.includes('/') && !repoUrl.includes('\\') && !repoUrl.includes('://')) {
+                name = repoUrl;
+            }
             else if (this.config?.repository) {
                 // Fall back to config if URL parsing fails
                 owner = this.config.repository.owner || '';
@@ -1503,6 +1508,11 @@ class FraimLocalMCPServer {
                     this.engine.setMachineInfo(this.machineInfo);
                     this.engine.setRepoInfo(this.repoInfo);
                 }
+                // Issue #330: capture agent identity on the usage collector so every
+                // queued event is attributed without re-reading args downstream.
+                if (this.usageCollector && this.agentInfo) {
+                    this.usageCollector.setAgent(this.agentInfo.name ?? null, this.agentInfo.model ?? null);
+                }
                 // In a proxy setup, the remote server resolves the API key ID during event upload.
                 // No local resolution needed.
                 // Update the request with injected info
@@ -1989,17 +1999,28 @@ class FraimLocalMCPServer {
                 const afterCount = this.usageCollector.getEventCount();
                 if (afterCount > beforeCount) {
                     this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
-                    // Fetch token snapshot from OTLP receiver for seekMentoring calls
+                    // Issue #330: pluggable token capture by agent.
                     if (toolName === 'seekMentoring') {
                         try {
-                            const snapshot = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(undefined, (msg) => this.log(`📊 ${msg}`));
-                            if (snapshot) {
-                                this.usageCollector.attachTokenSnapshot(snapshot);
-                                this.log(`📊 🔢 Token snapshot attached (input=${snapshot.inputTokens}, output=${snapshot.outputTokens}, session=${snapshot.claudeSessionId})`);
+                            const agentName = this.agentInfo?.name;
+                            const agentModel = this.agentInfo?.model;
+                            const adapter = (0, token_adapter_registry_js_1.resolveTokenAdapter)(agentName);
+                            const result = await adapter.capture({
+                                agent: agentName,
+                                model: agentModel,
+                                log: (msg) => this.log(`📊 ${msg}`),
+                            });
+                            if (result.snapshot) {
+                                this.usageCollector.attachTokenSnapshot(result.snapshot);
+                                this.log(`📊 🔢 Token snapshot attached via ${adapter.id} adapter (input=${result.snapshot.inputTokens}, output=${result.snapshot.outputTokens})`);
+                            }
+                            else if (result.reason) {
+                                this.usageCollector.attachCaptureUnavailable(result.reason);
+                                this.log(`📊 ℹ️ Token capture unavailable (${result.reason}) for adapter ${adapter.id}`);
                             }
                         }
                         catch (err) {
-                            this.log(`📊 ⚠️ Token snapshot fetch failed (non-blocking): ${err.message}`);
+                            this.log(`📊 ⚠️ Token snapshot capture failed (non-blocking): ${err.message}`);
                         }
                     }
                 }

package/dist/src/local-mcp-server/token-adapter-registry.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Token Adapter Registry — Issue #330 / R1.1, R1.4, R1.5
+ *
+ * Pluggable dispatch by agent name. Each adapter implements
+ * `capture(ctx)` returning either a `TokenSnapshot` or `null` plus a
+ * typed reason (`tokenCaptureUnavailableReason`) so the UI can explain
+ * coverage gaps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenAdapter = resolveTokenAdapter;
+const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
+const codex_token_adapter_js_1 = require("./codex-token-adapter.js");
+const claudeCodeAdapter = {
+    id: 'claude-code',
+    async capture(ctx) {
+        const snap = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(ctx.agentSessionId, ctx.log);
+        if (snap)
+            return { snapshot: snap };
+        return { snapshot: null, reason: 'otlp_receiver_unreachable' };
+    },
+};
+const codexAdapter = {
+    id: 'codex',
+    async capture(ctx) {
+        try {
+            const snap = await (0, codex_token_adapter_js_1.captureCodexSnapshot)({ log: ctx.log });
+            if (snap)
+                return { snapshot: snap };
+            return { snapshot: null, reason: 'codex_session_log_not_found' };
+        }
+        catch (err) {
+            ctx.log?.(`codex adapter threw: ${err.message}`);
+            return { snapshot: null, reason: 'codex_adapter_error' };
+        }
+    },
+};
+const nullAdapterFor = (canonicalAgent) => ({
+    id: 'null',
+    async capture() {
+        return { snapshot: null, reason: `agent_not_supported:${canonicalAgent}` };
+    },
+});
+/**
+ * Map of canonical agent ids to adapters. Keys are lower-cased.
+ * Aliases (e.g. "claude" → claude-code) are handled in the resolver below.
+ */
+const ADAPTERS = {
+    'claude-code': claudeCodeAdapter,
+    'claude': claudeCodeAdapter,
+    'codex': codexAdapter,
+};
+/**
+ * Resolve an adapter by agent.name (case-insensitive). Always returns
+ * an adapter — falls back to a null adapter that reports
+ * "agent_not_supported:<name>".
+ */
+function resolveTokenAdapter(agentName) {
+    const canonical = (agentName || 'unknown').toLowerCase().trim();
+    const adapter = ADAPTERS[canonical];
+    if (adapter)
+        return adapter;
+    return nullAdapterFor(canonical || 'unknown');
+}

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

@@ -14,6 +14,9 @@ class UsageCollector {
         this.events = [];
         this.userId = null;
         this.repoIdentifier = null;
+        // Issue #330: per-session agent attribution captured at fraim_connect.
+        this.agentName = null;
+        this.agentModel = null;
     }
     static resolveMentoringJobName(args) {
         if (!args || typeof args !== 'object') {
@@ -40,6 +43,16 @@ class UsageCollector {
     setRepoIdentifier(repoIdentifier) {
         this.repoIdentifier = repoIdentifier;
     }
+    /**
+     * Capture the agent identity at fraim_connect time so subsequent events
+     * can be attributed to the right agent without re-reading args.
+     */
+    setAgent(name, model) {
+        this.agentName = name ? name.toLowerCase() : null;
+        this.agentModel = model || null;
+    }
+    getAgentName() { return this.agentName; }
+    getAgentModel() { return this.agentModel; }
     /**
      * Collect MCP tool call event
      */
@@ -67,6 +80,8 @@ class UsageCollector {
             success,
             category: parsed.category,
             repoIdentifier: this.repoIdentifier || undefined,
+            agentName: this.agentName || undefined,
+            agentModel: this.agentModel || undefined,
             args: Object.keys(analyticsArgs).length > 0 ? analyticsArgs : undefined
         };
         this.events.push(event);
@@ -178,6 +193,16 @@ class UsageCollector {
             this.events[this.events.length - 1].tokenSnapshot = snapshot;
         }
     }
+    /**
+     * Issue #330: when a token capture adapter returns null, record the
+     * typed reason on the most recently queued event so the dashboard
+     * can explain coverage gaps to the user.
+     */
+    attachCaptureUnavailable(reason) {
+        if (this.events.length > 0) {
+            this.events[this.events.length - 1].tokenCaptureUnavailableReason = reason;
+        }
+    }
     /**
      * Get current event count
      */

package/index.js

@@ -1,85 +1,85 @@
 #!/usr/bin/env node
-
-/**
- * FRAIM Framework - Smart Entry Point
- * This file handles both production (dist/) and development (src/) environments.
- */
-
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-
-/**
- * Runs the CLI using either the compiled JS or the source TS via tsx
- */
-function runCLI() {
-    const distPath = path.join(__dirname, 'dist', 'src', 'cli', 'fraim.js');
-    const srcPath = path.join(__dirname, 'src', 'cli', 'fraim.ts');
-
-    // 1. Check if we have a compiled version (Production / CI)
-    if (fs.existsSync(distPath)) {
-        require(distPath);
-        return;
-    }
-
-    // 2. Explicitly fail in production if dist/ is missing
-    if (process.env.NODE_ENV === 'production') {
-        console.error('❌ FRAIM Error: Production build (dist/) not found.');
-        console.error('In production environments, you must run the compiled version.');
-        console.error(`Expected: ${distPath}`);
-        process.exit(1);
-    }
-
-    // 3. Fallback to source version using tsx (Development)
-    if (fs.existsSync(srcPath)) {
-        // We use spawnSync to run tsx so we don't have to require it in memory
-        // if it's not needed, and it handles the process arguments correctly.
-        // 
-        // IMPORTANT FIX: Directory names with spaces and dashes (e.g., "FRAIM - Issue 166")
-        // cause argument parsing issues on Windows when shell: true is used.
-        // Without quoting, a path like "C:\...\FRAIM - Issue 166\src\cli\fraim.ts" gets
-        // split into multiple arguments, with the dash interpreted as a command flag,
-        // resulting in "error: unknown command '-'".
-        // 
-        // Solution: On Windows with shell: true, quote paths containing spaces.
-        // On Unix with shell: false, pass the path unquoted (spawnSync handles it correctly).
-        const isWindows = process.platform === 'win32';
-
-        // On Windows with shell, quote paths with spaces to prevent shell misinterpretation
-        // On Unix without shell, pass path as-is (spawnSync handles spaces correctly)
-        const processedSrcPath = (isWindows && srcPath.includes(' '))
-            ? `"${srcPath}"`
-            : srcPath;
-
-        const result = spawnSync(
-            'npx',
-            ['tsx', processedSrcPath, ...process.argv.slice(2)],
-            {
-                stdio: 'inherit',
-                shell: isWindows, // Windows needs shell for npx, Unix doesn't
-                windowsHide: true
-            }
-        );
-        process.exit(result.status || 0);
-    }
-
-    console.error('❌ FRAIM Error: Could not find CLI entry point.');
-    console.error('Expected one of:');
-    console.error(` - ${distPath}`);
-    console.error(` - ${srcPath}`);
-    process.exit(1);
-}
-
-// Global programmatic exports
-module.exports = {
-    FRAIM_INFO: {
-        name: 'FRAIM',
-        version: '2.0.98',
-        repository: 'https://github.com/mathursrus/FRAIM'
-    }
-};
-
-// If this file is run directly (via npx or global link), run the CLI
-if (require.main === module) {
-    runCLI();
+
+/**
+ * FRAIM Framework - Smart Entry Point
+ * This file handles both production (dist/) and development (src/) environments.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+/**
+ * Runs the CLI using either the compiled JS or the source TS via tsx
+ */
+function runCLI() {
+    const distPath = path.join(__dirname, 'dist', 'src', 'cli', 'fraim.js');
+    const srcPath = path.join(__dirname, 'src', 'cli', 'fraim.ts');
+
+    // 1. Check if we have a compiled version (Production / CI)
+    if (fs.existsSync(distPath)) {
+        require(distPath);
+        return;
+    }
+
+    // 2. Explicitly fail in production if dist/ is missing
+    if (process.env.NODE_ENV === 'production') {
+        console.error('❌ FRAIM Error: Production build (dist/) not found.');
+        console.error('In production environments, you must run the compiled version.');
+        console.error(`Expected: ${distPath}`);
+        process.exit(1);
+    }
+
+    // 3. Fallback to source version using tsx (Development)
+    if (fs.existsSync(srcPath)) {
+        // We use spawnSync to run tsx so we don't have to require it in memory
+        // if it's not needed, and it handles the process arguments correctly.
+        // 
+        // IMPORTANT FIX: Directory names with spaces and dashes (e.g., "FRAIM - Issue 166")
+        // cause argument parsing issues on Windows when shell: true is used.
+        // Without quoting, a path like "C:\...\FRAIM - Issue 166\src\cli\fraim.ts" gets
+        // split into multiple arguments, with the dash interpreted as a command flag,
+        // resulting in "error: unknown command '-'".
+        // 
+        // Solution: On Windows with shell: true, quote paths containing spaces.
+        // On Unix with shell: false, pass the path unquoted (spawnSync handles it correctly).
+        const isWindows = process.platform === 'win32';
+
+        // On Windows with shell, quote paths with spaces to prevent shell misinterpretation
+        // On Unix without shell, pass path as-is (spawnSync handles spaces correctly)
+        const processedSrcPath = (isWindows && srcPath.includes(' '))
+            ? `"${srcPath}"`
+            : srcPath;
+
+        const result = spawnSync(
+            'npx',
+            ['tsx', processedSrcPath, ...process.argv.slice(2)],
+            {
+                stdio: 'inherit',
+                shell: isWindows, // Windows needs shell for npx, Unix doesn't
+                windowsHide: true
+            }
+        );
+        process.exit(result.status || 0);
+    }
+
+    console.error('❌ FRAIM Error: Could not find CLI entry point.');
+    console.error('Expected one of:');
+    console.error(` - ${distPath}`);
+    console.error(` - ${srcPath}`);
+    process.exit(1);
+}
+
+// Global programmatic exports
+module.exports = {
+    FRAIM_INFO: {
+        name: 'FRAIM',
+        version: '2.0.98',
+        repository: 'https://github.com/mathursrus/FRAIM'
+    }
+};
+
+// If this file is run directly (via npx or global link), run the CLI
+if (require.main === module) {
+    runCLI();
 }