fraim 2.0.289 → 2.0.290

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",
-  "version": "2.0.289",
+  "version": "2.0.290",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -46,6 +46,7 @@
     "cors": "^2.8.5",
     "dotenv": "^16.4.7",
     "express": "^5.2.1",
+    "extract-zip": "^2.0.1",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",
@@ -55,6 +56,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"