fraim-hub 2.0.289 → 2.0.290

package/dist/src/ai-hub/desktop-launcher.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const electron_1 = require("electron");
+const path_1 = __importDefault(require("path"));
+const hub_app_materializer_1 = require("./hub-app-materializer");
+// Issue #1415: this is the packaged Electron `main` entry (see packages/fraim-hub/package.json
+// `"main"`). It is deliberately thin and changes rarely: its only job is to resolve which version
+// of the actual Hub application (the code in desktop-main.ts) to run — the latest published to
+// npm, materializing it once per machine if not already cached — and hand off to it. The native
+// installer only ever needs to ship a new build of this file and the Electron shell itself;
+// every ordinary `fraim-hub` release reaches an already-installed user the moment this
+// resolution runs on their next launch, with no new installer download.
+const BUNDLED_ENTRY_PATH = path_1.default.join(__dirname, 'desktop-main.js');
+async function bootstrapFrom(entryPath) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const entry = require(entryPath);
+    await entry.bootstrap();
+}
+async function launch() {
+    // Issue #1415: deterministic escape hatch for integration testing — skips the real npm
+    // resolution (and its dependence on whatever happens to be published at test time) so a test can
+    // prove the Electron main-process boot chain itself (resolveHubAppEntry -> require -> bootstrap
+    // -> healthy server) without a network round-trip. Not used in any real launch path; mirrors the
+    // existing `FRAIM_INSTALLER_LIFECYCLE_TEST` kill-switch pattern already used for testability.
+    const resolved = process.env.FRAIM_HUB_SKIP_MATERIALIZE === '1'
+        ? { entryPath: BUNDLED_ENTRY_PATH, source: 'bundled', version: electron_1.app.getVersion() }
+        : await (0, hub_app_materializer_1.resolveHubAppEntry)({
+            bundledVersion: electron_1.app.getVersion(),
+            bundledEntryPath: BUNDLED_ENTRY_PATH,
+            onProgress: (message) => console.log(`[fraim-hub-launcher] ${message}`),
+        }).catch((error) => {
+            // resolveHubAppEntry is designed to never throw (every failure mode falls back internally),
+            // but a launch must survive even a bug in that resolution rather than fail here.
+            console.error('[fraim-hub-launcher] resolution failed unexpectedly; using the bundled build:', error);
+            return { entryPath: BUNDLED_ENTRY_PATH, source: 'bundled', version: electron_1.app.getVersion() };
+        });
+    console.log(`[fraim-hub-launcher] running FRAIM Hub ${resolved.version} (${resolved.source})`);
+    try {
+        await bootstrapFrom(resolved.entryPath);
+    }
+    catch (error) {
+        if (resolved.entryPath === BUNDLED_ENTRY_PATH)
+            throw error;
+        // A materialized copy that fails to load (corrupt cache, an ABI mismatch some future
+        // dependency introduces) must not strand the user on a broken launch — fall back to the
+        // build that shipped with this installer, which is always known-good for this Electron binary.
+        console.error(`[fraim-hub-launcher] materialized FRAIM Hub ${resolved.version} failed to load; falling back to the bundled build:`, error);
+        await bootstrapFrom(BUNDLED_ENTRY_PATH);
+    }
+}
+if (process.versions.electron && process.type !== 'renderer') {
+    launch().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        try {
+            electron_1.dialog.showErrorBox('FRAIM Hub failed to start', error instanceof Error ? error.message : String(error));
+        }
+        catch {
+            // dialog can be unavailable this early in rare startup failures; the console error above
+            // is the fallback record.
+        }
+        electron_1.app.exit(1);
+    });
+}

package/dist/src/ai-hub/desktop-main.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.launchDesktopShell = launchDesktopShell;
+exports.bootstrap = bootstrap;
 const electron_1 = require("electron");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -20,6 +21,7 @@ const server_2 = require("../first-run/server");
 const session_service_1 = require("../first-run/session-service");
 const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const desktop_auto_updater_1 = require("./desktop-auto-updater");
+const hub_app_materializer_1 = require("./hub-app-materializer");
 // Keep installed, running, and user-pinned Windows shortcuts grouped under the
 // stable identity declared in packages/fraim-hub/package.json.
 electron_1.app.setAppUserModelId('ai.fraim.hub');
@@ -73,7 +75,7 @@ function configurePackagedFraimRuntime() {
     if (!electron_1.app.isPackaged && process.env.FRAIM_DESKTOP_FIRST_RUN !== '1')
         return;
     process.env.FRAIM_PACKAGED_CLI_EXECUTABLE = process.execPath;
-    process.env.FRAIM_PACKAGED_CLI_SCRIPT = path_1.default.join(electron_1.app.getAppPath(), 'node_modules', 'fraim', 'bin', 'fraim.js');
+    process.env.FRAIM_PACKAGED_CLI_SCRIPT = (0, hub_app_materializer_1.resolvePackagedCliScriptPath)(__dirname);
     (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
 }
 function shouldShowEmbeddedFirstRun() {
@@ -133,11 +135,39 @@ async function configureAutoUpdater() {
     });
     return result.action === 'installing';
 }
-function checkForUpdateAfterSecondInstance() {
+// Issue #1415: a second-instance activation (the user re-clicking the icon while the Hub is
+// already running) is the common case once login-item autostart + hide-to-tray keep the Hub
+// resident for days, and it is the one launch-shaped event where the desktop-launcher.ts
+// materializer never gets a chance to run — bootstrap() has already won the single-instance lock
+// by the time it fires. Without this check, an already-running Hub could only ever pick up a new
+// `fraim-hub` release through the slower electron-updater feed below, which is the exact lagging
+// signal #1415 was filed about. `getFraimVersion()` (not `app.getVersion()`) is compared, because
+// it resolves from wherever the currently-running code actually lives — the bundled app.asar or a
+// previously materialized copy — while `app.getVersion()` always names the former.
+async function checkForHubAppUpdateOnSecondInstance() {
+    const runningVersion = (0, version_utils_1.getFraimVersion)();
+    const resolved = await (0, hub_app_materializer_1.resolveHubAppEntry)({
+        bundledVersion: runningVersion,
+        bundledEntryPath: __filename,
+    });
+    if (resolved.version === runningVersion)
+        return false;
+    console.log(`[fraim] newer FRAIM Hub ${resolved.version} available (was running ${runningVersion}); restarting to apply it`);
+    electron_1.app.relaunch();
+    electron_1.app.quit();
+    return true;
+}
+// Issue #1415: shared by both re-launch-shaped events on an already-running Hub — Windows/Linux's
+// `second-instance` (a new process lost the single-instance lock) and macOS's `activate` (the
+// Dock icon click that never spawns a new process at all, so `second-instance` never fires there).
+// Before this, neither path re-checked npm-latest, only the older, slower electron-updater feed.
+function checkForRelaunchAttemptUpdate() {
     if (!electron_1.app.isPackaged || process.env.FRAIM_INSTALLER_LIFECYCLE_TEST === '1')
         return;
-    void configureAutoUpdater().catch((err) => {
-        console.warn('[fraim] second-instance update check failed:', err);
+    void checkForHubAppUpdateOnSecondInstance()
+        .then((restarting) => (restarting ? undefined : configureAutoUpdater().then(() => undefined)))
+        .catch((err) => {
+        console.warn('[fraim] relaunch-attempt update check failed:', err);
     });
 }
 // ---------------------------------------------------------------------------
@@ -469,6 +499,9 @@ async function launchDesktopShell(options) {
 // ---------------------------------------------------------------------------
 // Bootstrap
 // ---------------------------------------------------------------------------
+// Issue #1415: exported so `desktop-launcher.ts` can `require()` this module (whether the copy
+// bundled in this installer or a materialized npm-latest copy) and invoke bootstrap explicitly,
+// instead of relying on the module's own top-level self-execution below.
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
     applyUserDataOverride();
@@ -483,7 +516,7 @@ async function bootstrap() {
         return;
     }
     electron_1.app.on('second-instance', () => {
-        void electron_1.app.whenReady().then(checkForUpdateAfterSecondInstance);
+        void electron_1.app.whenReady().then(checkForRelaunchAttemptUpdate);
         if (mainWindow) {
             mainWindow.show();
             mainWindow.focus();
@@ -508,7 +541,10 @@ async function bootstrap() {
             return;
     }
     electron_1.app.on('activate', () => {
-        // macOS: clicking dock icon re-shows the window
+        // macOS: clicking dock icon re-shows the window. Unlike Windows/Linux, this never spawns a
+        // second process (so 'second-instance' never fires here) — it is macOS's equivalent
+        // relaunch-attempt event, so it gets the same npm-latest re-check (#1415).
+        checkForRelaunchAttemptUpdate();
         if (mainWindow) {
             mainWindow.show();
             mainWindow.focus();
@@ -533,7 +569,12 @@ async function bootstrap() {
     });
     await launchDesktopShell(options);
 }
-if (process.versions.electron && process.type !== 'renderer') {
+// Issue #1415: self-execution is now gated on `require.main === module` in addition to the
+// existing Electron-main-process check, so `desktop-launcher.ts` requiring this file (bundled or
+// materialized) does not double-run bootstrap — the launcher calls the exported `bootstrap`
+// explicitly instead. Direct invocation (`npm run hub:desktop`, Electron-launching test suites)
+// is unaffected: this file is still `require.main` in that case.
+if (require.main === module && process.versions.electron && process.type !== 'renderer') {
     bootstrap().catch(async (error) => {
         console.error(error instanceof Error ? error.message : error);
         await stopServerOnce();

package/dist/src/ai-hub/hub-app-materializer.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUB_APP_ENTRY_RELATIVE = exports.HUB_APP_PACKAGE_NAME = void 0;
+exports.resolvePackagedCliScriptPath = resolvePackagedCliScriptPath;
+exports.planHubAppMaterialization = planHubAppMaterialization;
+exports.resolveHubAppCacheDir = resolveHubAppCacheDir;
+exports.isHubAppCacheComplete = isHubAppCacheComplete;
+exports.listCachedHubAppVersions = listCachedHubAppVersions;
+exports.ensureMaterializedHubApp = ensureMaterializedHubApp;
+exports.resolveHubAppEntry = resolveHubAppEntry;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const semver_1 = __importDefault(require("semver"));
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const hub_latest_version_1 = require("./hub-latest-version");
+const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
+// Issue #1415: a packaged FRAIM Hub install can already be behind npm's published "latest" the
+// moment it is downloaded, and its own electron-updater feed (#1387) only advances once a full
+// signed desktop build has finished — which happens on a much slower cadence than npm publishes.
+// This module reconciles the two: on every launch, resolve the version actually published to npm
+// (`fraim-hub` and `fraim` are lockstep-versioned, so `hub-latest-version.ts`'s existing 5-minute-
+// cached npm lookup is reused rather than duplicated), materialize that version's application code
+// once per machine (mirroring `electron-dist.ts`'s "extract once, reuse forever" shared-dist
+// pattern), and hand back the entry point to run. The Electron shell itself — installed once via
+// the native installer — never needs a new install for an ordinary `fraim-hub` point release; only
+// the application payload this module resolves does.
+//
+// The decision (`planHubAppMaterialization`) is a pure function so the whole staleness/cache/
+// offline matrix is unit-testable without touching npm, disk, or Electron — the same separation
+// `hub-launch-decision.ts` (#755) and `desktop-auto-updater.ts` (#1387) already established for
+// this exact class of problem.
+exports.HUB_APP_PACKAGE_NAME = 'fraim-hub';
+/** Relative path, from a materialized (or bundled) package root, to the Electron main entry. */
+exports.HUB_APP_ENTRY_RELATIVE = path_1.default.join('dist', 'src', 'ai-hub', 'desktop-main.js');
+/**
+ * Where the packaged CLI/MCP shim (`ensureFraimMcpLatestLauncher()`) should find `fraim`'s CLI
+ * script, derived from `desktop-main.ts`'s own directory (`<packageRoot>/dist/src/ai-hub/`) rather
+ * than Electron's `app.getAppPath()`. `desktop-launcher.ts` may have loaded `desktop-main.js` from a
+ * materialized `fraim-hub@<latest>` copy under `~/.fraim/bin/hub-app/<version>/` rather than from
+ * the original app.asar, and `app.getAppPath()` always names the latter regardless of which copy is
+ * actually running. `moduleDir` tracks whichever copy is really executing. Kept in this
+ * Electron-free module (rather than inlined in `desktop-main.ts`) so it is unit-testable without an
+ * Electron `app` object.
+ */
+function resolvePackagedCliScriptPath(moduleDir) {
+    return path_1.default.join(moduleDir, '..', '..', '..', 'node_modules', 'fraim', 'bin', 'fraim.js');
+}
+function pickNewestComplete(cachedVersions) {
+    const versions = cachedVersions.filter((entry) => entry.complete).map((entry) => entry.version);
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((newest, candidate) => (semver_1.default.gt(candidate, newest) ? candidate : newest));
+}
+/**
+ * Decide whether to run a cached materialized version, materialize a new one, or fall back to the
+ * version bundled with this installer. Pure: no fs, no network, no Electron.
+ */
+function planHubAppMaterialization(input) {
+    const { bundledVersion, latestPublishedVersion, cachedVersions } = input;
+    if (latestPublishedVersion === null) {
+        const newestCached = pickNewestComplete(cachedVersions);
+        if (newestCached) {
+            return {
+                action: 'use-cached',
+                version: newestCached,
+                reason: 'npm registry unreachable; reusing the newest complete cached version',
+            };
+        }
+        return {
+            action: 'use-bundled',
+            version: bundledVersion,
+            reason: 'npm registry unreachable and no cached version available; falling back to the version bundled with this installer',
+        };
+    }
+    if (latestPublishedVersion === bundledVersion) {
+        return {
+            action: 'use-bundled',
+            version: bundledVersion,
+            reason: 'the installed shell already matches the latest published version',
+        };
+    }
+    const alreadyMaterialized = cachedVersions.some((entry) => entry.complete && entry.version === latestPublishedVersion);
+    if (alreadyMaterialized) {
+        return {
+            action: 'use-cached',
+            version: latestPublishedVersion,
+            reason: 'latest published version is already materialized on disk',
+        };
+    }
+    return {
+        action: 'materialize',
+        version: latestPublishedVersion,
+        reason: `latest published version ${latestPublishedVersion} is not yet materialized`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Cache directory layout: ~/.fraim/bin/hub-app/<version>/
+// ---------------------------------------------------------------------------
+// Same shape as an npm version, optionally with a prerelease/build suffix. Anchoring on this
+// before ever joining a version into a path means a hostile string (`../../..`, an absolute path)
+// can never escape the versioned cache directory.
+const SAFE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function assertPathSafeVersion(version) {
+    if (!SAFE_VERSION.test(version)) {
+        throw new Error(`Refusing to use "${version}" as a fraim-hub version: expected an exact release such as 2.0.290.`);
+    }
+    return version;
+}
+function resolveHubAppCacheDir(version, fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)()) {
+    return path_1.default.join(fraimDir, 'bin', 'hub-app', assertPathSafeVersion(version));
+}
+/** Whether `dir` holds a complete materialized install for exactly `version`. */
+function isHubAppCacheComplete(dir, version) {
+    try {
+        const recorded = fs_1.default.readFileSync(path_1.default.join(dir, 'version'), 'utf8').trim();
+        if (recorded !== version)
+            return false;
+        return fs_1.default.existsSync(path_1.default.join(dir, exports.HUB_APP_ENTRY_RELATIVE));
+    }
+    catch {
+        return false;
+    }
+}
+/** Every version directory under the cache root that is a complete, trustworthy install. */
+function listCachedHubAppVersions(fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)()) {
+    const root = path_1.default.join(fraimDir, 'bin', 'hub-app');
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const versions = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !semver_1.default.valid(entry.name))
+            continue;
+        if (isHubAppCacheComplete(path_1.default.join(root, entry.name), entry.name)) {
+            versions.push({ version: entry.name, complete: true });
+        }
+    }
+    return versions;
+}
+/**
+ * Default installer: `npm install fraim-hub@<version>` into a scratch prefix, then flatten the
+ * installed package up to `destDir` so callers can treat `destDir` itself as the package root
+ * (`destDir/dist/...`), with the package's own dependencies left as siblings under
+ * `destDir/node_modules/` where Node's module resolution finds them from any depth under `destDir`.
+ * A fresh, empty `--prefix` install of a single package has nothing to conflict with, so npm hoists
+ * every dependency to that top level; nothing here relies on nested-dependency resolution.
+ *
+ * The `npm` executable itself is resolved via `ensureManagedNpm()` (system PATH, an already-managed
+ * runtime, or a freshly downloaded one) rather than assumed present on PATH — a genuinely GUI-only
+ * install (native installer only, no CLI ever run) has neither system npm nor FRAIM's own managed
+ * one, since first-run's embedded-desktop path only needs Electron's own bundled Node for its own
+ * purposes and never downloads a standalone npm (see managed-node-runtime.ts's own header comment).
+ */
+// Node's spawnSync fails with EINVAL when a `.cmd` shim (npm's own launcher on Windows) is
+// invoked directly without a shell — the same issue `fraim-mcp-latest-launcher.ts` already works
+// around for `npm`/`npx`. Mirrors that exact fix: run through cmd.exe with args quoted, rather
+// than inventing a different approach for this second call site.
+function quoteCmdArg(arg) {
+    return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+function runNpmInstall(npmPath, args) {
+    if (process.platform !== 'win32') {
+        return (0, child_process_1.spawnSync)(npmPath, args, { encoding: 'utf8' });
+    }
+    return (0, child_process_1.spawnSync)(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', [quoteCmdArg(npmPath), ...args.map(quoteCmdArg)].join(' ')], { encoding: 'utf8' });
+}
+const defaultInstallPackage = async (version, destDir) => {
+    fs_1.default.mkdirSync(destDir, { recursive: true });
+    const npm = await (0, managed_node_runtime_1.ensureManagedNpm)();
+    const result = runNpmInstall(npm.npmPath, ['install', `${exports.HUB_APP_PACKAGE_NAME}@${version}`, '--no-save', '--omit=dev', '--prefix', destDir]);
+    if (result.status !== 0) {
+        const detail = result.stderr || result.stdout || result.error?.message || 'unknown error';
+        throw new Error(`npm install ${exports.HUB_APP_PACKAGE_NAME}@${version} failed via ${npm.source} npm (exit ${result.status}): ${detail}`);
+    }
+    const installedRoot = path_1.default.join(destDir, 'node_modules', exports.HUB_APP_PACKAGE_NAME);
+    if (!fs_1.default.existsSync(installedRoot)) {
+        throw new Error(`npm install ${exports.HUB_APP_PACKAGE_NAME}@${version} did not produce ${installedRoot}`);
+    }
+    for (const entry of fs_1.default.readdirSync(installedRoot)) {
+        const from = path_1.default.join(installedRoot, entry);
+        const to = path_1.default.join(destDir, entry);
+        if (entry === 'node_modules' && fs_1.default.existsSync(to)) {
+            // Only reachable if npm nested a dependency inside fraim-hub's own node_modules despite the
+            // empty prefix (a version conflict with itself is not possible, but defend anyway): merge
+            // child-by-child rather than clobbering the siblings already hoisted to destDir/node_modules.
+            for (const nested of fs_1.default.readdirSync(from)) {
+                fs_1.default.renameSync(path_1.default.join(from, nested), path_1.default.join(to, nested));
+            }
+        }
+        else {
+            fs_1.default.renameSync(from, to);
+        }
+    }
+    fs_1.default.rmSync(installedRoot, { recursive: true, force: true });
+};
+/**
+ * Return the entry path for `version`, materializing it first if it is not already a complete
+ * cache entry. Returns immediately (no npm invocation) when a complete entry already exists.
+ */
+async function ensureMaterializedHubApp(version, options = {}) {
+    const fraimDir = options.fraimDir ?? (0, project_fraim_paths_1.getUserFraimDirPath)();
+    const installPackage = options.installPackage ?? defaultInstallPackage;
+    const destDir = resolveHubAppCacheDir(version, fraimDir);
+    const entryPath = path_1.default.join(destDir, exports.HUB_APP_ENTRY_RELATIVE);
+    if (isHubAppCacheComplete(destDir, version)) {
+        return entryPath;
+    }
+    const stagingDir = `${destDir}.staging-${process.pid}`;
+    fs_1.default.mkdirSync(path_1.default.dirname(destDir), { recursive: true });
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    try {
+        await installPackage(version, stagingDir);
+        // Written only on success, after the installer's own work, so a throw never leaves a staging
+        // tree that could be mistaken for complete.
+        fs_1.default.writeFileSync(path_1.default.join(stagingDir, 'version'), version, 'utf8');
+        if (!isHubAppCacheComplete(stagingDir, version)) {
+            throw new Error(`materialized ${exports.HUB_APP_PACKAGE_NAME}@${version} is missing ${exports.HUB_APP_ENTRY_RELATIVE}; refusing to promote an incomplete install`);
+        }
+        // A concurrent launch may have finished materializing the same version already; the winner
+        // keeps its copy rather than being clobbered by this one (mirrors electron-dist.ts).
+        if (!isHubAppCacheComplete(destDir, version)) {
+            fs_1.default.rmSync(destDir, { recursive: true, force: true });
+            try {
+                fs_1.default.renameSync(stagingDir, destDir);
+            }
+            catch (error) {
+                if (!isHubAppCacheComplete(destDir, version))
+                    throw error;
+            }
+        }
+    }
+    finally {
+        fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    }
+    return entryPath;
+}
+/**
+ * Resolve which `desktop-main.js` to run: the latest published version, materializing it first if
+ * needed, or the bundled build when npm is unreachable, already current, or materialization fails
+ * for any reason. A materialization failure must never block a launch — it always falls back to
+ * the bundled copy rather than propagating.
+ */
+async function resolveHubAppEntry(options) {
+    const fraimDir = options.fraimDir ?? (0, project_fraim_paths_1.getUserFraimDirPath)();
+    const getLatest = options.getLatestPublishedVersion ?? hub_latest_version_1.getLatestPublishedVersion;
+    const cachedVersions = listCachedHubAppVersions(fraimDir);
+    let latestPublishedVersion;
+    try {
+        latestPublishedVersion = await getLatest();
+    }
+    catch {
+        latestPublishedVersion = null;
+    }
+    const plan = planHubAppMaterialization({
+        bundledVersion: options.bundledVersion,
+        latestPublishedVersion,
+        cachedVersions,
+    });
+    if (plan.action === 'use-bundled') {
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: plan.version };
+    }
+    if (plan.action === 'use-cached') {
+        return {
+            entryPath: path_1.default.join(resolveHubAppCacheDir(plan.version, fraimDir), exports.HUB_APP_ENTRY_RELATIVE),
+            source: 'cached',
+            version: plan.version,
+        };
+    }
+    try {
+        options.onProgress?.(`Fetching FRAIM Hub ${plan.version}...`);
+        const entryPath = await ensureMaterializedHubApp(plan.version, { fraimDir, installPackage: options.installPackage });
+        return { entryPath, source: 'cached', version: plan.version };
+    }
+    catch {
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: options.bundledVersion };
+    }
+}

package/dist/src/cli/utils/managed-node-runtime.js

@@ -0,0 +1,269 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANAGED_NODE_VERSION = void 0;
+exports.npmExecutableName = npmExecutableName;
+exports.nodeExecutableName = nodeExecutableName;
+exports.findExecutableOnPath = findExecutableOnPath;
+exports.hasWorkingNodeAndNpm = hasWorkingNodeAndNpm;
+exports.isManagedNodeVersionComplete = isManagedNodeVersionComplete;
+exports.nodeVersionedDirName = nodeVersionedDirName;
+exports.ensureManagedNpm = ensureManagedNpm;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const https_1 = __importDefault(require("https"));
+const crypto_1 = __importDefault(require("crypto"));
+const managed_agent_paths_1 = require("./managed-agent-paths");
+// Issue #1415 (extended): a genuinely GUI-only FRAIM Hub install — the native installer
+// downloaded from the website, never a CLI — has no working `npm`/`npx` anywhere. First-run's
+// `embeddedDesktop` branch (session-service.ts) deliberately skips installing one (it only needs
+// Electron's own bundled Node for FRAIM's own CLI/MCP shim, via ELECTRON_RUN_AS_NODE), and the
+// separate CLI installer's portable-Node bootstrap (scripts/installer/fraim-install-win.template.cmd)
+// never runs for a desktop-only user. That left two features silently unable to do their real job
+// on such a machine: `hub-app-materializer.ts`'s npm install (this issue), and agent-CLI
+// installation (`managed-agent-install.ts`), which also shells out to a bare `npm`.
+//
+// This module is the one place that guarantees a real, usable `npm`/`node` exists, for both
+// consumers: prefer whatever is already on system PATH (common for technical users), then an
+// already-downloaded managed runtime (shared with the CLI installer's `~/.fraim/node/` convention
+// via `managed-agent-paths.ts` — reused, not duplicated, so a user who has ever run the `fraim` CLI
+// never pays for a second download), and only download a portable Node.js distribution from
+// nodejs.org as a last resort.
+//
+// `~/.fraim/node/` is a *shared* directory — it already holds agent-CLI shims and their own
+// `node_modules/` (managed-agent-install.ts) — not a directory this module exclusively owns like
+// `electron-dist.ts` owns its versioned Electron dist. So the extract-once-reuse-forever,
+// staging-then-atomic-rename transaction that pattern established is applied here to just the one
+// versioned subfolder a Node.js archive naturally extracts as (`node-v<version>-<platform>-<arch>/`,
+// exactly what `getPortableNodeBinPath()` already knows how to find), never to the shared root
+// itself — so a concurrent or failed download can never disturb sibling content already there.
+exports.MANAGED_NODE_VERSION = '20.11.1'; // matches NODE_VERSION in fraim-install-win.template.cmd
+function npmExecutableName(platform = process.platform) {
+    return platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+function nodeExecutableName(platform = process.platform) {
+    return platform === 'win32' ? 'node.exe' : 'node';
+}
+/** First executable named `name` found by walking `pathValue`'s directories, or null. */
+function findExecutableOnPath(name, pathValue = process.env.PATH) {
+    for (const dir of (pathValue ?? '').split(path_1.default.delimiter).filter(Boolean)) {
+        const candidate = path_1.default.join(dir, name);
+        try {
+            if (fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // Unreadable entry — treat as absent, not fatal.
+        }
+    }
+    return null;
+}
+/** Whether `dir` already has a real, runnable node+npm — any version; this function's job is "a working npm", not "this exact one". */
+function hasWorkingNodeAndNpm(dir, platform = process.platform) {
+    return fs_1.default.existsSync(path_1.default.join(dir, npmExecutableName(platform))) && fs_1.default.existsSync(path_1.default.join(dir, nodeExecutableName(platform)));
+}
+/** Whether `dir` (a specific versioned bin dir) holds a complete extraction for exactly `version`. */
+function isManagedNodeVersionComplete(dir, version, platform = process.platform) {
+    try {
+        const recorded = fs_1.default.readFileSync(path_1.default.join(dir, 'fraim-managed-node-version'), 'utf8').trim();
+        return recorded === version && hasWorkingNodeAndNpm(dir, platform);
+    }
+    catch {
+        return false;
+    }
+}
+function nodePlatformName(platform) {
+    if (platform === 'darwin')
+        return 'darwin';
+    if (platform === 'win32')
+        return 'win';
+    return 'linux';
+}
+function nodeArchiveExtension(platform) {
+    return platform === 'win32' ? 'zip' : 'tar.gz';
+}
+// `request.version` is always `MANAGED_NODE_VERSION` today, but it is a public option on
+// `ensureManagedNpm`, and this string is joined into a filesystem path below (`nodeRoot/<this>`)
+// that a failed extraction's cleanup recursively deletes. Anchoring on an exact-release shape
+// before it ever reaches a path, same guard shape as `hub-app-materializer.ts`'s
+// `assertPathSafeVersion`, so a hostile or malformed override can never escape `nodeRoot`.
+const SAFE_NODE_VERSION = /^\d+\.\d+\.\d+$/;
+function assertPathSafeNodeVersion(version) {
+    if (!SAFE_NODE_VERSION.test(version)) {
+        throw new Error(`Refusing to use "${version}" as a managed Node.js version: expected an exact release such as 20.11.1.`);
+    }
+    return version;
+}
+/** The exact folder name Node's own official archive extracts as — also this module's versioned subfolder name under the shared `~/.fraim/node/` root. */
+function nodeVersionedDirName(request) {
+    return `node-v${assertPathSafeNodeVersion(request.version)}-${nodePlatformName(request.platform)}-${request.arch}`;
+}
+function nodeArchiveFileName(request) {
+    return `${nodeVersionedDirName(request)}.${nodeArchiveExtension(request.platform)}`;
+}
+function nodeDistBaseUrl(version) {
+    return `https://nodejs.org/dist/v${version}`;
+}
+function httpsGetBuffer(url) {
+    return new Promise((resolve, reject) => {
+        https_1.default.get(url, { headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } }, (res) => {
+            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                httpsGetBuffer(res.headers.location).then(resolve, reject);
+                return;
+            }
+            if (res.statusCode !== 200) {
+                res.resume();
+                reject(new Error(`GET ${url} failed: HTTP ${res.statusCode}`));
+                return;
+            }
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks)));
+            res.on('error', reject);
+        }).on('error', reject);
+    });
+}
+function httpsDownloadToFile(url, destPath) {
+    return new Promise((resolve, reject) => {
+        const file = fs_1.default.createWriteStream(destPath);
+        https_1.default.get(url, { headers: { 'user-agent': 'fraim-hub-managed-node-runtime' } }, (res) => {
+            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                file.close();
+                httpsDownloadToFile(res.headers.location, destPath).then(resolve, reject);
+                return;
+            }
+            if (res.statusCode !== 200) {
+                res.resume();
+                file.close();
+                reject(new Error(`GET ${url} failed: HTTP ${res.statusCode}`));
+                return;
+            }
+            res.pipe(file);
+            file.on('finish', () => file.close(() => resolve()));
+        }).on('error', (err) => {
+            file.close();
+            reject(err);
+        });
+    });
+}
+/**
+ * Verify `filePath` against the sha256 line naming `fileName` in the release's own
+ * `SHASUMS256.txt` — the same integrity check `@electron/get` performs for Electron zips
+ * (`electron-dist.ts`), applied to Node's own equivalent publishing convention.
+ */
+async function verifyNodeArchiveChecksum(filePath, fileName, version) {
+    const shasums = (await httpsGetBuffer(`${nodeDistBaseUrl(version)}/SHASUMS256.txt`)).toString('utf8');
+    const line = shasums.split('\n').find((entry) => entry.trim().endsWith(fileName));
+    if (!line) {
+        throw new Error(`SHASUMS256.txt for Node v${version} has no entry for ${fileName}; refusing to trust an unverified download`);
+    }
+    const expected = line.trim().split(/\s+/)[0];
+    const actual = crypto_1.default.createHash('sha256').update(fs_1.default.readFileSync(filePath)).digest('hex');
+    if (actual !== expected) {
+        throw new Error(`checksum mismatch for ${fileName}: expected ${expected}, got ${actual}`);
+    }
+}
+const defaultDownloadNodeArchive = async (request) => {
+    const fileName = nodeArchiveFileName(request);
+    const url = `${nodeDistBaseUrl(request.version)}/${fileName}`;
+    const tempPath = path_1.default.join(os_1.default.tmpdir(), `fraim-managed-node-${process.pid}-${Date.now()}-${fileName}`);
+    await httpsDownloadToFile(url, tempPath);
+    try {
+        await verifyNodeArchiveChecksum(tempPath, fileName, request.version);
+    }
+    catch (error) {
+        fs_1.default.rmSync(tempPath, { force: true });
+        throw error;
+    }
+    return tempPath;
+};
+const defaultExtractNodeArchive = async (archivePath, destDir, request) => {
+    if (request.platform === 'win32') {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const extract = require('extract-zip');
+        await extract(archivePath, { dir: destDir });
+    }
+    else {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const tar = require('tar');
+        await tar.x({ file: archivePath, cwd: destDir });
+    }
+};
+/**
+ * Download and extract Node v`request.version` into `nodeRoot/<node-vX.Y.Z-platform-arch>/`,
+ * touching nothing else in `nodeRoot`. Staging-then-atomic-rename, scoped to just that one
+ * versioned subfolder (mirrors `electron-dist.ts`'s transaction, applied to a shared parent
+ * directory instead of one this module exclusively owns): a concurrent download that already
+ * finished is kept rather than clobbered, and a failed extraction never leaves a versioned
+ * subfolder behind that a later launch could mistake for complete.
+ */
+async function downloadAndPromoteVersionedNodeDir(args) {
+    const { nodeRoot, request, downloadArchive, extractArchive } = args;
+    const destDir = path_1.default.join(nodeRoot, nodeVersionedDirName(request));
+    const stagingDir = `${destDir}.staging-${process.pid}`;
+    fs_1.default.mkdirSync(nodeRoot, { recursive: true });
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    const archivePath = await downloadArchive(request);
+    try {
+        await extractArchive(archivePath, stagingDir, request);
+        // The archive's own top-level folder (matching nodeVersionedDirName) may land either as the
+        // extraction root itself (tar) or as one nested level inside it (some zip extractors preserve
+        // the archive's internal folder) — handle both without assuming either.
+        const nestedCandidate = path_1.default.join(stagingDir, nodeVersionedDirName(request));
+        const extractedRoot = fs_1.default.existsSync(nestedCandidate) ? nestedCandidate : stagingDir;
+        fs_1.default.writeFileSync(path_1.default.join(extractedRoot, 'fraim-managed-node-version'), request.version, 'utf8');
+        if (!isManagedNodeVersionComplete(extractedRoot, request.version, request.platform)) {
+            throw new Error(`extracted Node v${request.version} is missing ${npmExecutableName(request.platform)}/${nodeExecutableName(request.platform)}; refusing to promote an incomplete install`);
+        }
+        // A concurrent launch may have finished downloading the same version already; the winner
+        // keeps its copy rather than being clobbered by this one.
+        if (!isManagedNodeVersionComplete(destDir, request.version, request.platform)) {
+            fs_1.default.rmSync(destDir, { recursive: true, force: true });
+            try {
+                fs_1.default.renameSync(extractedRoot, destDir);
+            }
+            catch (error) {
+                if (!isManagedNodeVersionComplete(destDir, request.version, request.platform))
+                    throw error;
+            }
+        }
+    }
+    finally {
+        fs_1.default.rmSync(archivePath, { force: true });
+        fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    }
+    return destDir;
+}
+/**
+ * Resolve a working `npm` executable, preferring (in order): system PATH, an already-downloaded
+ * managed runtime (shared with the CLI installer's convention, any version — this function's job
+ * is "a working npm", not "this exact one"), or a freshly downloaded one. Only throws for a
+ * genuine download/extraction failure; callers should treat that as "materialization unavailable
+ * this launch," not a hard failure — never for "nothing found," which falls through to download.
+ */
+async function ensureManagedNpm(options = {}) {
+    const version = options.version ?? exports.MANAGED_NODE_VERSION;
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const systemNpm = findExecutableOnPath(npmExecutableName(platform), options.systemPath ?? process.env.PATH);
+    if (systemNpm) {
+        return { npmPath: systemNpm, binDir: path_1.default.dirname(systemNpm), source: 'system' };
+    }
+    const existingBinDir = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    if (hasWorkingNodeAndNpm(existingBinDir, platform)) {
+        return { npmPath: path_1.default.join(existingBinDir, npmExecutableName(platform)), binDir: existingBinDir, source: 'managed-existing' };
+    }
+    const request = { version, platform, arch };
+    options.onProgress?.('Preparing FRAIM\'s bundled Node.js runtime (one-time, ~30MB)...');
+    const binDir = await downloadAndPromoteVersionedNodeDir({
+        nodeRoot: (0, managed_agent_paths_1.getManagedNodeRoot)(),
+        request,
+        downloadArchive: options.downloadArchive ?? defaultDownloadNodeArchive,
+        extractArchive: options.extractArchive ?? defaultExtractNodeArchive,
+    });
+    options.onProgress?.('FRAIM Node.js runtime ready.');
+    return { npmPath: path_1.default.join(binDir, npmExecutableName(platform)), binDir, source: 'managed-downloaded' };
+}

package/dist/src/first-run/session-service.js

@@ -52,6 +52,7 @@ const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launche
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 const managed_agent_install_1 = require("../cli/utils/managed-agent-install");
+const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
 const types_1 = require("./types");
 Object.defineProperty(exports, "FIRST_RUN_ROW_IDS", { enumerable: true, get: function () { return types_1.FIRST_RUN_ROW_IDS; } });
 const install_state_1 = require("./install-state");
@@ -856,9 +857,18 @@ class FirstRunSessionService {
                     loginHint: `Sign in to ${option.label} to activate it. A terminal window will open with the sign-in command — complete sign-in there, then return here and click "Check if Ready".`,
                 };
             }
-            const outcome = await (0, managed_agent_install_1.installManagedAgent)({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, systemPath, { runProcess, commandVersion });
+            // Issue #1415 (extended): a genuinely GUI-only install (native installer only, no CLI ever
+            // run) has no working npm on `systemPath` at all — `installManagedAgent`'s "standard" attempt
+            // needs one to run `npm install -g <agent>` in the first place. Ensure one exists (system,
+            // already-managed, or freshly downloaded) and fold its directory into the PATH passed down,
+            // so the standard attempt can actually succeed instead of silently falling through.
+            const npm = await (0, managed_node_runtime_1.ensureManagedNpm)({
+                onProgress: (message) => appendInstallLog(`managed-node: ${message}`),
+            });
+            const pathWithNpm = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, [npm.binDir]);
+            const outcome = await (0, managed_agent_install_1.installManagedAgent)({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, pathWithNpm, { runProcess, commandVersion });
             if (outcome.outcome === 'standard' && outcome.npmGlobalBinDirs.length > 0) {
-                process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, outcome.npmGlobalBinDirs);
+                process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(pathWithNpm, outcome.npmGlobalBinDirs);
             }
             this.setAgentInstallStatus(agentId, 'needs-sign-in', `Sign in to ${option.label} to activate it.`);
             appendInstallLog(outcome.outcome === 'standard' ? `agent-installed-standard ${agentId}` : `agent-installed-managed ${agentId}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.289",
+  "version": "2.0.290",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -9,7 +9,7 @@
     "fraim-hub": "bin/fraim-hub.js",
     "fraim-hub-2": "bin/fraim-hub-2.js"
   },
-  "main": "dist/src/ai-hub/desktop-main.js",
+  "main": "dist/src/ai-hub/desktop-launcher.js",
   "scripts": {
     "build:windows-installer": "tsx ../../scripts/build-windows-hub-installer.ts",
     "build:macos-installer": "tsx ../../scripts/build-macos-hub-installer.ts",
@@ -48,6 +48,7 @@
     "dist/src/cli/utils/local-folder-sync.js",
     "dist/src/cli/utils/managed-agent-install.js",
     "dist/src/cli/utils/managed-agent-paths.js",
+    "dist/src/cli/utils/managed-node-runtime.js",
     "dist/src/cli/utils/org-publish.js",
     "dist/src/cli/utils/pack-git-publish.js",
     "dist/src/cli/utils/pack-home.js",
@@ -210,7 +211,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.289",
+    "fraim": "2.0.290",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",
@@ -220,6 +221,7 @@
     "selfsigned": "^5.5.0",
     "semver": "^7.7.4",
     "stripe": "^20.3.1",
+    "tar": "^7.4.3",
     "toml": "^3.0.0",
     "tree-kill": "^1.2.2",
     "xml2js": "^0.6.2"