fraim-framework 2.0.122 → 2.0.124

package/dist/src/ai-hub/server.js

@@ -0,0 +1,307 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiHubServer = void 0;
+exports.findAvailablePort = findAvailablePort;
+const express_1 = __importDefault(require("express"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const net_1 = __importDefault(require("net"));
+const crypto_1 = require("crypto");
+const child_process_1 = require("child_process");
+const catalog_1 = require("./catalog");
+const hosts_1 = require("./hosts");
+const preferences_1 = require("./preferences");
+class AiHubRunRegistry {
+    constructor() {
+        this.runs = new Map();
+        this.children = new Map();
+    }
+    listLatest() {
+        return [...this.runs.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+    }
+    get(runId) {
+        return this.runs.get(runId);
+    }
+    create(run, child) {
+        this.runs.set(run.id, run);
+        this.children.set(run.id, child);
+        return run;
+    }
+    update(runId, updater) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            throw new Error(`Run ${runId} not found`);
+        }
+        updater(run);
+        run.updatedAt = new Date().toISOString();
+        return run;
+    }
+    dispose(runId) {
+        this.children.delete(runId);
+    }
+}
+function ensureDirectoryPath(projectPath) {
+    const trimmed = (projectPath || '').trim();
+    if (!trimmed) {
+        throw new Error('Project path is required.');
+    }
+    const resolved = path_1.default.resolve(trimmed);
+    const stat = fs_1.default.existsSync(resolved) ? fs_1.default.statSync(resolved) : null;
+    if (!stat || !stat.isDirectory()) {
+        throw new Error('Project path must point to an existing directory.');
+    }
+    return resolved;
+}
+class AiHubServer {
+    constructor(options = {}) {
+        this.app = (0, express_1.default)();
+        this.runRegistry = new AiHubRunRegistry();
+        this.projectPath = options.projectPath || process.cwd();
+        this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
+        this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
+        this.app.use(express_1.default.json());
+        this.app.use('/ai-hub', express_1.default.static(resolveAiHubPublicDir()));
+        this.app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', service: 'fraim-ai-hub' });
+        });
+        this.registerRoutes();
+    }
+    getApp() {
+        return this.app;
+    }
+    async start(port) {
+        await new Promise((resolve, reject) => {
+            this.httpServer = this.app.listen(port, '127.0.0.1');
+            this.httpServer.once('listening', () => resolve());
+            this.httpServer.once('error', (error) => reject(error));
+        });
+    }
+    async stop() {
+        if (!this.httpServer)
+            return;
+        await new Promise((resolve, reject) => {
+            this.httpServer.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+        this.httpServer = undefined;
+    }
+    bootstrapResponse(projectPath) {
+        const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
+        const preferences = this.preferencesStore.load(normalizedProjectPath);
+        const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
+        const jobs = (0, catalog_1.discoverEmployeeJobs)(normalizedProjectPath);
+        const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath);
+        return {
+            title: 'Visa AI Hub',
+            project,
+            preferences,
+            categories: (0, catalog_1.getAiHubCategories)(),
+            jobs,
+            managerTemplates,
+            employees: this.hostRuntime.detectEmployees(),
+            activeRun: this.runRegistry.listLatest(),
+        };
+    }
+    registerRoutes() {
+        this.app.get('/api/ai-hub/bootstrap', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? req.query.projectPath
+                : this.projectPath;
+            res.json(this.bootstrapResponse(projectPath));
+        });
+        this.app.post('/api/ai-hub/project-path/pick', (_req, res) => {
+            try {
+                const projectPath = pickProjectPath();
+                if (!projectPath) {
+                    return res.status(204).end();
+                }
+                return res.json({ path: projectPath });
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open the folder picker.' });
+            }
+        });
+        this.app.post('/api/ai-hub/runs', (req, res) => {
+            try {
+                const projectPath = ensureDirectoryPath(req.body.projectPath || this.projectPath);
+                const hostId = req.body.hostId;
+                const jobId = req.body.jobId;
+                const message = (req.body.message || '').trim();
+                if (hostId !== 'codex' && hostId !== 'claude') {
+                    throw new Error('Choose an available employee before starting a job.');
+                }
+                if (!jobId) {
+                    throw new Error('Choose a FRAIM job before starting a run.');
+                }
+                if (!message) {
+                    throw new Error('Coach your employee before starting the run.');
+                }
+                const employee = this.hostRuntime.detectEmployees().find((entry) => entry.id === hostId);
+                if (!employee?.available) {
+                    throw new Error(`${employee?.label || 'Selected employee'} is not available on this machine.`);
+                }
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    jobId,
+                    hostId,
+                    projectPath,
+                    status: 'running',
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                    messages: [(0, hosts_1.createHubMessage)('manager', message)],
+                    events: [(0, hosts_1.createHubEvent)('system', `Starting ${hostId} in ${projectPath}`)],
+                };
+                this.runRegistry.create(run, {});
+                const child = this.hostRuntime.startRun(hostId, projectPath, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            if (event.message)
+                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                            if (event.raw)
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        });
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        this.runRegistry.dispose(run.id);
+                    },
+                });
+                this.runRegistry.create(run, child);
+                const existingPreferences = this.preferencesStore.load(projectPath);
+                this.preferencesStore.remember({
+                    ...existingPreferences,
+                    projectPath,
+                    employeeId: hostId,
+                    recentJobIds: existingPreferences.recentJobIds,
+                }, jobId);
+                res.status(201).json(run);
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not start run.' });
+            }
+        });
+        this.app.post('/api/ai-hub/runs/:runId/messages', (req, res) => {
+            try {
+                const run = this.runRegistry.get(req.params.runId);
+                if (!run) {
+                    return res.status(404).json({ error: 'Run not found.' });
+                }
+                if (!run.sessionId) {
+                    return res.status(409).json({ error: 'This run does not have a resumable host session yet.' });
+                }
+                const message = (req.body.message || '').trim();
+                if (!message) {
+                    return res.status(400).json({ error: 'Coach your employee before sending the next turn.' });
+                }
+                this.runRegistry.update(run.id, (current) => {
+                    current.status = 'running';
+                    current.messages.push((0, hosts_1.createHubMessage)('manager', message));
+                });
+                this.runRegistry.create(run, {});
+                const child = this.hostRuntime.continueRun(run.hostId, run.projectPath, run.sessionId, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            if (event.message)
+                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                            if (event.raw)
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        });
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        this.runRegistry.dispose(run.id);
+                    },
+                });
+                this.runRegistry.create(run, child);
+                res.json(this.runRegistry.get(run.id));
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not continue run.' });
+            }
+        });
+        this.app.get('/api/ai-hub/runs/:runId', (req, res) => {
+            const run = this.runRegistry.get(req.params.runId);
+            if (!run) {
+                return res.status(404).json({ error: 'Run not found.' });
+            }
+            return res.json(run);
+        });
+    }
+}
+exports.AiHubServer = AiHubServer;
+async function findAvailablePort(preferredPort) {
+    let port = preferredPort;
+    while (port < preferredPort + 20) {
+        const available = await new Promise((resolve) => {
+            const server = net_1.default.createServer();
+            server.once('error', () => resolve(false));
+            server.once('listening', () => {
+                server.close(() => resolve(true));
+            });
+            server.listen(port, '127.0.0.1');
+        });
+        if (available)
+            return port;
+        port += 1;
+    }
+    throw new Error(`No free loopback port found near ${preferredPort}.`);
+}
+function resolveAiHubPublicDir() {
+    const candidates = [
+        path_1.default.resolve(process.cwd(), 'public/ai-hub'),
+        path_1.default.resolve(__dirname, '..', '..', 'public/ai-hub'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'public/ai-hub'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error('Could not locate public/ai-hub assets.');
+}
+function pickProjectPath() {
+    if (process.platform === 'win32') {
+        const script = [
+            'Add-Type -AssemblyName System.Windows.Forms',
+            '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.ShowNewFolderButton = $false',
+            'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
+            '  Write-Output $dialog.SelectedPath',
+            '}',
+        ].join('; ');
+        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-Command', script], {
+            encoding: 'utf8',
+        });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    }
+    if (process.platform === 'darwin') {
+        const result = (0, child_process_1.spawnSync)('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'], {
+            encoding: 'utf8',
+        });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    }
+    const result = (0, child_process_1.spawnSync)('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'], {
+        encoding: 'utf8',
+    });
+    return result.status === 0 ? result.stdout.trim() || null : null;
+}

package/dist/src/ai-hub/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubCommand = void 0;
+const commander_1 = require("commander");
+const server_1 = require("../../ai-hub/server");
+const git_utils_1 = require("../../core/utils/git-utils");
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+function resolveElectronBinary() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require('electron');
+    }
+    catch {
+        return null;
+    }
+}
+function resolveDesktopEntry() {
+    const candidates = [
+        path_1.default.resolve(__dirname, '..', '..', 'ai-hub', 'desktop-main.js'),
+        path_1.default.resolve(process.cwd(), 'dist', 'src', 'ai-hub', 'desktop-main.js'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            fs_1.default.accessSync(candidate);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function openDesktopWindow(projectPath, preferredPort) {
+    const electronBinary = resolveElectronBinary();
+    const desktopEntry = resolveDesktopEntry();
+    if (!electronBinary || !desktopEntry) {
+        return false;
+    }
+    const child = (0, child_process_1.spawn)(electronBinary, [desktopEntry, '--project-path', projectPath, '--port', String(preferredPort)], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    return true;
+}
+function openBrowser(url) {
+    if (process.platform === 'win32') {
+        const child = (0, child_process_1.spawn)('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return;
+    }
+    if (process.platform === 'darwin') {
+        const child = (0, child_process_1.spawn)('open', [url], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return;
+    }
+    const child = (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+exports.hubCommand = new commander_1.Command('hub')
+    .description('Start the Visa AI Hub local companion for running FRAIM jobs through Codex or Claude Code')
+    .option('--port <port>', 'Preferred local port for the hub', (value) => Number(value), 43091)
+    .option('--project-path <path>', 'Initial project path for job discovery', process.cwd())
+    .option('--no-open', 'Do not open the hub after startup')
+    .option('--browser', 'Open in the default browser instead of the desktop shell')
+    .action(async (options) => {
+    const preferredPort = options.port || (0, git_utils_1.getPort)() + 100;
+    const projectPath = path_1.default.resolve(options.projectPath || process.cwd());
+    if (options.open) {
+        const openedDesktop = !options.browser && openDesktopWindow(projectPath, preferredPort);
+        if (!openedDesktop) {
+            const port = await (0, server_1.findAvailablePort)(preferredPort);
+            const server = new server_1.AiHubServer({ projectPath });
+            await server.start(port);
+            const url = `http://127.0.0.1:${port}/ai-hub/`;
+            console.log(`Visa AI Hub running at ${url}`);
+            console.log(`Project path: ${projectPath}`);
+            openBrowser(url);
+            return;
+        }
+        console.log('Visa AI Hub desktop shell launched.');
+        console.log(`Project path: ${projectPath}`);
+        return;
+    }
+    const port = await (0, server_1.findAvailablePort)(preferredPort);
+    const server = new server_1.AiHubServer({ projectPath });
+    await server.start(port);
+    const url = `http://127.0.0.1:${port}/ai-hub/`;
+    console.log(`Visa AI Hub running at ${url}`);
+    console.log(`Project path: ${projectPath}`);
+});

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

@@ -74,7 +74,7 @@ const promptForFraimKey = async () => {
         process.exit(1);
     }
     console.log(chalk_1.default.blue('🔑 FRAIM Key Setup'));
-    console.log('FRAIM requires a valid API key to access workflows and features.\n');
+    console.log('FRAIM requires a valid API key to access jobs and features.\n');
     let key = null;
     let attempts = 0;
     const maxAttempts = 3;
@@ -149,7 +149,7 @@ const promptForMode = async () => {
             {
                 title: 'Conversational Mode',
                 value: 'conversational',
-                description: 'AI workflows only, no platform integration required'
+                description: 'AI jobs only, no platform integration required'
             }
         ],
         initial: 0
@@ -160,7 +160,7 @@ const promptForMode = async () => {
     }
     if (response.mode === 'conversational') {
         console.log(chalk_1.default.blue('\n✓ Conversational mode selected'));
-        console.log(chalk_1.default.gray('  You can use FRAIM workflows without platform credentials.'));
+        console.log(chalk_1.default.gray('  You can use FRAIM jobs without platform credentials.'));
         console.log(chalk_1.default.gray('  Platform features (issues, PRs) will be unavailable.\n'));
     }
     else if (response.mode === 'split') {
@@ -584,7 +584,7 @@ const runSetup = async (options) => {
         });
         if (mode === 'conversational' && Object.keys(mcpTokens).length === 0) {
             console.log(chalk_1.default.yellow('ℹ️  Conversational mode: Configuring MCP servers without platform integration'));
-            console.log(chalk_1.default.gray('   FRAIM workflows will work, but platform-specific features will be unavailable\n'));
+            console.log(chalk_1.default.gray('   FRAIM jobs will work, but platform-specific features will be unavailable\n'));
         }
         try {
             // Build providerConfigs map from configs
@@ -668,7 +668,7 @@ const runSetup = async (options) => {
     console.log(chalk_1.default.white('  layer of your AI-powered work at once: AI agents become an'));
     console.log(chalk_1.default.white('  accountable workforce, you become a capable AI manager, and'));
     console.log(chalk_1.default.white('  your leadership gains clear optics on AI proficiency.'));
-    console.log(chalk_1.default.gray('\n  60+ jobs across engineering, marketing, fundraising,'));
+    console.log(chalk_1.default.gray('\n  120+ jobs across engineering, marketing, fundraising,'));
     console.log(chalk_1.default.gray('  legal, product, hiring, customer development, and more.'));
     // Show which IDEs were configured and how to use FRAIM in each
     const { detectInstalledIDEs: detectIDEs } = await Promise.resolve().then(() => __importStar(require('../setup/ide-detector')));

package/dist/src/cli/fraim.js

@@ -50,6 +50,7 @@ const list_overridable_1 = require("./commands/list-overridable");
 const login_1 = require("./commands/login");
 const mcp_1 = require("./commands/mcp");
 const migrate_project_fraim_1 = require("./commands/migrate-project-fraim");
+const hub_1 = require("./commands/hub");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
@@ -89,6 +90,7 @@ program.addCommand(list_overridable_1.listOverridableCommand);
 program.addCommand(login_1.loginCommand);
 program.addCommand(mcp_1.mcpCommand);
 program.addCommand(migrate_project_fraim_1.migrateProjectFraimCommand);
+program.addCommand(hub_1.hubCommand);
 // Wait for async command initialization before parsing
 (async () => {
     // Import the initialization promise from setup command

package/dist/src/cli/setup/user-level-sync.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureUserLevelDirectories = ensureUserLevelDirectories;
+exports.ensureUserLevelDependencies = ensureUserLevelDependencies;
 exports.syncUserLevelArtifacts = syncUserLevelArtifacts;
 /**
  * User-Level FRAIM Setup
@@ -23,8 +24,19 @@ exports.syncUserLevelArtifacts = syncUserLevelArtifacts;
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const script_sync_utils_1 = require("../utils/script-sync-utils");
+/**
+ * Curated list of npm runtime dependencies that user-level scripts in
+ * ~/.fraim/scripts/ require at runtime. Keep this list narrow — only add deps
+ * that are actually `require()`d by a script in registry/scripts/.
+ *
+ * Tracked in FRAIM #301 (author-audio first-run failure).
+ */
+const USER_LEVEL_RUNTIME_DEPS = {
+    'node-edge-tts': '*', // used by scripts/author-audio.js
+};
 /**
  * Ensure the user-level FRAIM directory structure exists.
  * Creates personalized-employee dirs for user-level overrides.
@@ -44,6 +56,52 @@ function ensureUserLevelDirectories(userFraimDir) {
         }
     }
 }
+/**
+ * Ensure the curated set of npm runtime dependencies is installed under
+ * ~/.fraim/node_modules/. Maintains ~/.fraim/package.json so the deps survive
+ * a re-sync, and only runs `npm install` when something is actually missing.
+ *
+ * Soft-fails (yellow warning, no throw) if npm is unavailable or install
+ * errors — setup must not break because a downstream script's dep couldn't
+ * be installed.
+ */
+function ensureUserLevelDependencies(userFraimDir) {
+    const baseDir = userFraimDir || (0, script_sync_utils_1.getUserFraimDir)();
+    const pkgPath = path_1.default.join(baseDir, 'package.json');
+    const nodeModulesDir = path_1.default.join(baseDir, 'node_modules');
+    let pkg = {};
+    if (fs_1.default.existsSync(pkgPath)) {
+        try {
+            pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+        }
+        catch {
+            // Corrupt package.json — overwrite below rather than crash.
+            pkg = {};
+        }
+    }
+    pkg.name = pkg.name || 'fraim-user-runtime';
+    pkg.private = true;
+    pkg.dependencies = { ...(pkg.dependencies || {}), ...USER_LEVEL_RUNTIME_DEPS };
+    fs_1.default.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+    const missing = Object.keys(USER_LEVEL_RUNTIME_DEPS).filter((dep) => !fs_1.default.existsSync(path_1.default.join(nodeModulesDir, dep)));
+    if (missing.length === 0) {
+        return;
+    }
+    console.log(chalk_1.default.blue(`📦 Installing user-level runtime dependencies (${missing.join(', ')})...`));
+    try {
+        (0, child_process_1.execSync)('npm install --no-audit --no-fund --no-save --no-package-lock --omit=dev', {
+            cwd: baseDir,
+            stdio: 'pipe',
+        });
+        console.log(chalk_1.default.green(`✅ Installed: ${missing.join(', ')}`));
+    }
+    catch (error) {
+        const stderr = error?.stderr?.toString?.() || error?.message || 'unknown error';
+        console.log(chalk_1.default.yellow(`⚠️  Could not install user-level deps (${missing.join(', ')}): ${stderr.split('\n')[0]}`));
+        console.log(chalk_1.default.gray(`   Skills that depend on these will surface a clear error when invoked.`));
+        console.log(chalk_1.default.gray(`   To retry manually: cd ${baseDir} && npm install`));
+    }
+}
 /**
  * Set up the user-level FRAIM directory.
  * Creates the personalized-employee structure so FRAIM works outside any project.
@@ -55,5 +113,6 @@ async function syncUserLevelArtifacts(userFraimDir) {
     console.log(chalk_1.default.blue('📦 Setting up user-level FRAIM directory...'));
     console.log(chalk_1.default.gray(`   Target: ${baseDir}`));
     ensureUserLevelDirectories(baseDir);
+    ensureUserLevelDependencies(baseDir);
     console.log(chalk_1.default.green('✅ User-level FRAIM directory ready'));
 }