@rudderhq/agent-runtime-utils 0.4.6-canary.8 → 0.5.0

package/dist/server-utils.cli.js

@@ -6,6 +6,29 @@ import path from "node:path";
 import { defaultPathForPlatform, fileExists, quoteForCmd, resolveCommandPath, resolveSpawnTarget } from "./server-utils.instructions.js";
 import { appendWithCap, asString, buildManagedSkillOrigin, compactSkillText, DEFAULT_LOCAL_CLI_CREDENTIAL_HOME_ENTRIES, DEFAULT_LOCAL_CLI_OPERATOR_HOME_SHIM_COMMANDS, isChildProcessAlive, isMaintainerOnlySkillTarget, parseObject, readSkillMetadataFromDirectory, resolveInstalledEntryTarget, RUDDER_SKILL_ROOT_RELATIVE_CANDIDATES, runningProcesses, skillLocationLabel } from "./server-utils.process.js";
 const LOCAL_CLI_CREDENTIAL_AUTH_CHECK_TIMEOUT_MS = 3000;
+const RUDDER_DESKTOP_CLI_ENTRY_ENV = "RUDDER_DESKTOP_CLI_ENTRY";
+export const OPERATOR_INTERRUPT_ABORT_REASON_KIND = "operator_interrupt";
+export function createOperatorInterruptAbortReason(hardDeadlineMs) {
+    if (!Number.isFinite(hardDeadlineMs) || hardDeadlineMs <= 0) {
+        throw new RangeError("operator interrupt hardDeadlineMs must be a positive finite number");
+    }
+    return {
+        kind: OPERATOR_INTERRUPT_ABORT_REASON_KIND,
+        hardDeadlineMs: Math.max(1, Math.floor(hardDeadlineMs)),
+    };
+}
+function operatorInterruptHardDeadlineMs(reason) {
+    if (!reason || typeof reason !== "object" || Array.isArray(reason))
+        return null;
+    const candidate = reason;
+    if (candidate.kind !== OPERATOR_INTERRUPT_ABORT_REASON_KIND)
+        return null;
+    if (typeof candidate.hardDeadlineMs !== "number" || !Number.isFinite(candidate.hardDeadlineMs))
+        return null;
+    if (candidate.hardDeadlineMs <= 0)
+        return null;
+    return Math.max(1, Math.floor(candidate.hardDeadlineMs));
+}
 export function ensurePathInEnv(env) {
     if (typeof env.PATH === "string" && env.PATH.length > 0)
         return env;
@@ -26,7 +49,7 @@ export function prependPathEntry(env, entry) {
         [pathKey]: current.length > 0 ? `${entry}${delimiter}${current}` : entry,
     };
 }
-function killChildProcessTree(child, force) {
+export function killChildProcessTree(child, force) {
     if (process.platform === "win32" && typeof child.pid === "number" && child.pid > 0) {
         const args = ["/pid", String(child.pid), "/t"];
         if (force)
@@ -38,7 +61,39 @@ function killChildProcessTree(child, force) {
         killer.on("error", () => { });
         return;
     }
-    child.kill(force ? "SIGKILL" : "SIGTERM");
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (typeof child.pid === "number" && child.pid > 0) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // Fall back to the direct child if its process group is already gone.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // The process may have exited between the liveness check and signal.
+    }
+}
+function isChildProcessTreeAlive(child) {
+    if (process.platform === "win32")
+        return isChildProcessAlive(child);
+    const pid = child.pid;
+    if (typeof pid !== "number" || pid <= 0)
+        return false;
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? error.code : null;
+        if (code === "EPERM")
+            return true;
+        return isChildProcessAlive(child);
+    }
 }
 export async function findAncestorWithFile(startDir, relativePath, maxDepth = 12) {
     let current = path.resolve(startDir);
@@ -56,12 +111,69 @@ export async function findAncestorWithFile(startDir, relativePath, maxDepth = 12
 export function shellQuote(arg) {
     return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
+async function readPackageVersion(filePath, expectedName) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        if (expectedName && parsed.name !== expectedName)
+            return null;
+        return typeof parsed.version === "string" && parsed.version.trim().length > 0 ? parsed.version.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function cliVersionBesideEntry(cliEntry) {
+    const directory = path.dirname(cliEntry);
+    return await readPackageVersion(path.join(directory, "rudder-cli-package.json"), "@rudderhq/cli")
+        ?? await readPackageVersion(path.join(directory, "package.json"), "@rudderhq/cli");
+}
+async function resolveExplicitDesktopCliEntry(env = process.env) {
+    const configured = env[RUDDER_DESKTOP_CLI_ENTRY_ENV]?.trim();
+    if (!configured)
+        return null;
+    const cliEntry = path.resolve(configured);
+    return await fileExists(cliEntry) ? cliEntry : null;
+}
+async function resolveDesktopExecutableBesideCliEntry(cliEntry) {
+    const resourcesDir = path.dirname(path.dirname(cliEntry));
+    const appRoot = path.dirname(resourcesDir);
+    const executable = process.platform === "darwin"
+        ? path.join(appRoot, "MacOS", "Rudder")
+        : path.join(appRoot, process.platform === "win32" ? "Rudder.exe" : "Rudder");
+    return await fileExists(executable) ? executable : null;
+}
+export function resolveDesktopCliSpawnTarget(cliEntry, executable, platform = process.platform, nodeRunner = null) {
+    if (platform === "win32" && nodeRunner) {
+        return {
+            command: executable,
+            args: [nodeRunner],
+            env: { ELECTRON_RUN_AS_NODE: "1" },
+        };
+    }
+    return {
+        command: executable,
+        args: ["--desktop-cli"],
+    };
+}
 export async function resolveRudderCliShimTarget(moduleDir) {
+    const explicitDesktopCli = await resolveExplicitDesktopCliEntry();
+    if (explicitDesktopCli) {
+        const executable = await resolveDesktopExecutableBesideCliEntry(explicitDesktopCli) ?? process.execPath;
+        const nodeRunner = path.join(path.dirname(explicitDesktopCli), "desktop-cli-runner.js");
+        return {
+            ...resolveDesktopCliSpawnTarget(explicitDesktopCli, executable, process.platform, await fileExists(nodeRunner) ? nodeRunner : null),
+            provenance: "desktop_bundle",
+            version: await cliVersionBesideEntry(explicitDesktopCli),
+        };
+    }
     const packagedCli = await findAncestorWithFile(moduleDir, "desktop-cli.js");
     if (packagedCli) {
+        const runtimeMetadata = await findAncestorWithFile(moduleDir, "runtime.json");
         return {
             command: process.execPath,
             args: [packagedCli],
+            provenance: runtimeMetadata ? "external_runtime" : "desktop_bundle",
+            version: await cliVersionBesideEntry(packagedCli),
         };
     }
     const repoRoot = await findAncestorWithFile(moduleDir, path.join("cli", "src", "index.ts"));
@@ -74,6 +186,8 @@ export async function resolveRudderCliShimTarget(moduleDir) {
         return {
             command: process.execPath,
             args: [tsxEntry, cliSource],
+            provenance: "repo",
+            version: await readPackageVersion(path.join(rootDir, "cli", "package.json"), "@rudderhq/cli"),
         };
     }
     const builtCliEntry = path.join(rootDir, "cli", "dist", "index.js");
@@ -81,13 +195,15 @@ export async function resolveRudderCliShimTarget(moduleDir) {
         return {
             command: process.execPath,
             args: [builtCliEntry],
+            provenance: "repo",
+            version: await readPackageVersion(path.join(rootDir, "cli", "package.json"), "@rudderhq/cli"),
         };
     }
     return null;
 }
 export async function materializeRudderCliShim(target) {
     const hash = createHash("sha1")
-        .update(JSON.stringify({ command: target.command, args: target.args, platform: process.platform }))
+        .update(JSON.stringify({ command: target.command, args: target.args, env: target.env, platform: process.platform }))
         .digest("hex")
         .slice(0, 12);
     const shimDir = path.join(os.tmpdir(), "rudder-cli-shims", hash);
@@ -95,7 +211,8 @@ export async function materializeRudderCliShim(target) {
     if (process.platform === "win32") {
         const shimPath = path.join(shimDir, "rudder.cmd");
         const commandLine = [quoteForCmd(target.command), ...target.args.map(quoteForCmd), "%*"].join(" ");
-        await fs.writeFile(shimPath, `@echo off\r\n${commandLine}\r\n`, "utf8");
+        const electronNodeMode = target.env?.ELECTRON_RUN_AS_NODE === "1";
+        await fs.writeFile(shimPath, `@echo off\r\n${electronNodeMode ? "set \"ELECTRON_RUN_AS_NODE=1\"\r\n" : ""}${commandLine}\r\n`, "utf8");
         return shimPath;
     }
     const shimPath = path.join(shimDir, "rudder");
@@ -347,19 +464,31 @@ export function readRudderSkillSyncPreference(config) {
     };
 }
 export function canonicalizeDesiredRudderSkillReference(reference, availableEntries) {
-    const normalizedReference = reference.trim().toLowerCase().replace(/^rudder\/rudder\//, "rudder/");
+    const normalizedReference = reference.trim().toLowerCase();
     if (!normalizedReference)
         return "";
     const exactKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === normalizedReference);
     if (exactKey)
         return exactKey.key;
-    const byRuntimeName = availableEntries.filter((entry) => typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === normalizedReference);
+    if (normalizedReference === "rudder"
+        || normalizedReference === "rudder/rudder"
+        || normalizedReference === "bundled:rudder/rudder") {
+        const canonicalRudderDocsEntry = availableEntries.find((entry) => entry.key.trim().toLowerCase() === "rudder/rudder-docs"
+            || entry.key.trim().toLowerCase() === "bundled:rudder/rudder-docs"
+            || entry.runtimeName?.trim().toLowerCase() === "rudder-docs");
+        return canonicalRudderDocsEntry?.key ?? "rudder/rudder-docs";
+    }
+    const lookupReference = normalizedReference.replace(/^rudder\/rudder\//, "rudder/");
+    const legacyNestedKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === lookupReference);
+    if (legacyNestedKey)
+        return legacyNestedKey.key;
+    const byRuntimeName = availableEntries.filter((entry) => typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === lookupReference);
     if (byRuntimeName.length === 1)
         return byRuntimeName[0].key;
-    const slugMatches = availableEntries.filter((entry) => entry.key.trim().toLowerCase().split("/").pop() === normalizedReference);
+    const slugMatches = availableEntries.filter((entry) => entry.key.trim().toLowerCase().split("/").pop() === lookupReference);
     if (slugMatches.length === 1)
         return slugMatches[0].key;
-    return normalizedReference;
+    return lookupReference;
 }
 export function resolveRudderDesiredSkillNames(config, availableEntries) {
     const preference = readRudderSkillSyncPreference(config);
@@ -368,6 +497,14 @@ export function resolveRudderDesiredSkillNames(config, availableEntries) {
         .filter(Boolean);
     return Array.from(new Set(desiredSkills));
 }
+export function filterRudderDesiredSkillsForBrowserCapability(availableEntries, desiredSkills, browserEnabled) {
+    if (browserEnabled)
+        return [...desiredSkills];
+    const browserSkillKeys = new Set(availableEntries
+        .filter((entry) => entry.runtimeName?.trim().toLowerCase() === "browser")
+        .map((entry) => entry.key));
+    return desiredSkills.filter((skill) => !browserSkillKeys.has(skill));
+}
 export function writeRudderSkillSyncPreference(config, desiredSkills) {
     const next = { ...config };
     const raw = next.rudderSkillSync;
@@ -650,6 +787,120 @@ export async function ensureRudderSkillSymlink(source, target, linkSkill = (link
 export async function removeMaintainerOnlySkillSymlinks(skillsHome, allowedSkillNames) {
     return removeUnselectedRudderSkillSymlinks(skillsHome, allowedSkillNames);
 }
+function isFileSystemErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function sameFileSystemEntry(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+export async function cleanupLegacyRudderDocsManagedEntry(skillsHome, selectedEntries) {
+    const targetPath = path.join(path.resolve(skillsHome), "rudder");
+    const canonicalEntry = Array.from(selectedEntries).find((entry) => (entry.key === "rudder/rudder-docs" || entry.key === "bundled:rudder/rudder-docs")
+        && entry.runtimeName === "rudder-docs");
+    if (!canonicalEntry) {
+        return { state: "not_applicable", targetPath, legacySourcePath: null, kind: null };
+    }
+    const legacySourcePath = path.join(path.dirname(path.resolve(canonicalEntry.source)), "rudder");
+    let existing;
+    try {
+        existing = await fs.lstat(targetPath);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return { state: "absent", targetPath, legacySourcePath, kind: null };
+        }
+        return { state: "collision", targetPath, legacySourcePath, kind: "other" };
+    }
+    if (existing.isSymbolicLink()) {
+        const linkedPath = await fs.readlink(targetPath).catch(() => null);
+        if (linkedPath === null) {
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        const resolvedLinkedPath = path.resolve(path.dirname(targetPath), linkedPath);
+        if (resolvedLinkedPath !== legacySourcePath) {
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        try {
+            await fs.stat(resolvedLinkedPath);
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        catch (error) {
+            if (!isFileSystemErrorCode(error, "ENOENT")) {
+                return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+            }
+        }
+        // Ownership evidence is path-based, so revalidate inode, type, and target immediately before deletion.
+        const revalidated = await fs.lstat(targetPath).catch(() => null);
+        if (!revalidated?.isSymbolicLink() || !sameFileSystemEntry(existing, revalidated)) {
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        const revalidatedLink = await fs.readlink(targetPath).catch(() => null);
+        if (revalidatedLink === null
+            || path.resolve(path.dirname(targetPath), revalidatedLink) !== legacySourcePath) {
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        const finalEntry = await fs.lstat(targetPath).catch(() => null);
+        if (!finalEntry?.isSymbolicLink() || !sameFileSystemEntry(existing, finalEntry)) {
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        try {
+            await fs.stat(legacySourcePath);
+            return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+        }
+        catch (error) {
+            if (!isFileSystemErrorCode(error, "ENOENT")) {
+                return { state: "collision", targetPath, legacySourcePath, kind: "symlink" };
+            }
+        }
+        try {
+            await fs.unlink(targetPath);
+        }
+        catch (error) {
+            return {
+                state: "failed",
+                targetPath,
+                legacySourcePath,
+                kind: "symlink",
+                detail: `unlink failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        return { state: "removed", targetPath, legacySourcePath, kind: "symlink" };
+    }
+    if (existing.isDirectory()) {
+        const materializedSource = await readRudderMaterializedSkillSource(targetPath);
+        if (materializedSource === legacySourcePath) {
+            // A matching manifest can move with a replacement; inode and provenance must both remain stable.
+            const revalidated = await fs.lstat(targetPath).catch(() => null);
+            if (!revalidated?.isDirectory() || !sameFileSystemEntry(existing, revalidated)) {
+                return { state: "collision", targetPath, legacySourcePath, kind: "directory" };
+            }
+            const revalidatedSource = await readRudderMaterializedSkillSource(targetPath);
+            if (revalidatedSource !== legacySourcePath) {
+                return { state: "collision", targetPath, legacySourcePath, kind: "directory" };
+            }
+            const finalEntry = await fs.lstat(targetPath).catch(() => null);
+            if (!finalEntry?.isDirectory() || !sameFileSystemEntry(existing, finalEntry)) {
+                return { state: "collision", targetPath, legacySourcePath, kind: "directory" };
+            }
+            try {
+                await fs.rm(targetPath, { recursive: true, force: true });
+            }
+            catch (error) {
+                return {
+                    state: "failed",
+                    targetPath,
+                    legacySourcePath,
+                    kind: "directory",
+                    detail: `recursive removal failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            return { state: "removed", targetPath, legacySourcePath, kind: "directory" };
+        }
+        return { state: "collision", targetPath, legacySourcePath, kind: "directory" };
+    }
+    const kind = existing.isFile() ? "file" : "other";
+    return { state: "collision", targetPath, legacySourcePath, kind };
+}
 async function readRudderMaterializedSkillSource(target) {
     const manifestPath = path.join(target, ".rudder", "materialized-skill.json");
     const raw = await fs.readFile(manifestPath, "utf8").catch(() => null);
@@ -722,6 +973,7 @@ export async function runChildProcess(runId, command, args, opts) {
     const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
     return new Promise((resolve, reject) => {
         const rawMerged = { ...process.env, ...opts.env };
+        delete rawMerged.RUDDER_DESKTOP_CLI_ENTRY;
         const requestedHome = typeof opts.env.HOME === "string" && opts.env.HOME.trim().length > 0
             ? path.resolve(opts.env.HOME)
             : null;
@@ -777,6 +1029,7 @@ export async function runChildProcess(runId, command, args, opts) {
             }
             const child = spawn(target.command, target.args, {
                 cwd: opts.cwd,
+                detached: process.platform !== "win32",
                 env: mergedEnv,
                 shell: false,
                 stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
@@ -797,43 +1050,70 @@ export async function runChildProcess(runId, command, args, opts) {
             let stdout = "";
             let stderr = "";
             let logChain = Promise.resolve();
+            let operatorInterrupted = false;
+            let forceKillTimer = null;
+            let forceKillAt = Number.POSITIVE_INFINITY;
+            const clearForceKillTimer = () => {
+                if (forceKillTimer)
+                    clearTimeout(forceKillTimer);
+                forceKillTimer = null;
+                forceKillAt = Number.POSITIVE_INFINITY;
+            };
+            const scheduleForceKill = (delayMs) => {
+                const boundedDelayMs = Math.max(1, delayMs);
+                const killAt = Date.now() + boundedDelayMs;
+                if (forceKillTimer && forceKillAt <= killAt)
+                    return;
+                clearForceKillTimer();
+                forceKillAt = killAt;
+                forceKillTimer = setTimeout(() => {
+                    forceKillTimer = null;
+                    forceKillAt = Number.POSITIVE_INFINITY;
+                    if (isChildProcessTreeAlive(child)) {
+                        killChildProcessTree(child, true);
+                    }
+                }, boundedDelayMs);
+            };
             const timeout = opts.timeoutSec > 0
                 ? setTimeout(() => {
                     timedOut = true;
                     killChildProcessTree(child, false);
-                    setTimeout(() => {
-                        if (isChildProcessAlive(child)) {
-                            killChildProcessTree(child, true);
-                        }
-                    }, Math.max(1, opts.graceSec) * 1000);
+                    scheduleForceKill(Math.max(1, opts.graceSec) * 1000);
                 }, opts.timeoutSec * 1000)
                 : null;
             let abortCleanup = null;
             if (opts.abortSignal) {
                 const onAbort = () => {
                     aborted = true;
+                    const operatorHardDeadlineMs = operatorInterruptHardDeadlineMs(opts.abortSignal?.reason);
+                    operatorInterrupted = operatorHardDeadlineMs !== null;
                     killChildProcessTree(child, false);
-                    setTimeout(() => {
-                        if (isChildProcessAlive(child)) {
-                            killChildProcessTree(child, true);
-                        }
-                    }, Math.max(1, opts.graceSec) * 1000);
+                    scheduleForceKill(operatorHardDeadlineMs ?? Math.max(1, opts.graceSec) * 1000);
                 };
-                opts.abortSignal.addEventListener("abort", onAbort, { once: true });
-                abortCleanup = () => opts.abortSignal?.removeEventListener("abort", onAbort);
+                if (opts.abortSignal.aborted) {
+                    onAbort();
+                }
+                else {
+                    opts.abortSignal.addEventListener("abort", onAbort, { once: true });
+                    abortCleanup = () => opts.abortSignal?.removeEventListener("abort", onAbort);
+                }
             }
             child.stdout?.on("data", (chunk) => {
                 const text = String(chunk);
                 stdout = appendWithCap(stdout, text);
+                if (operatorInterrupted)
+                    return;
                 logChain = logChain
-                    .then(() => opts.onLog("stdout", text))
+                    .then(() => operatorInterrupted ? undefined : opts.onLog("stdout", text))
                     .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
             });
             child.stderr?.on("data", (chunk) => {
                 const text = String(chunk);
                 stderr = appendWithCap(stderr, text);
+                if (operatorInterrupted)
+                    return;
                 logChain = logChain
-                    .then(() => opts.onLog("stderr", text))
+                    .then(() => operatorInterrupted ? undefined : opts.onLog("stderr", text))
                     .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
             });
             child.on("error", (err) => {
@@ -841,6 +1121,7 @@ export async function runChildProcess(runId, command, args, opts) {
                     clearTimeout(timeout);
                 if (abortCleanup)
                     abortCleanup();
+                clearForceKillTimer();
                 runningProcesses.delete(runId);
                 const errno = err.code;
                 const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
@@ -854,8 +1135,11 @@ export async function runChildProcess(runId, command, args, opts) {
                     clearTimeout(timeout);
                 if (abortCleanup)
                     abortCleanup();
+                if (!isChildProcessTreeAlive(child))
+                    clearForceKillTimer();
                 runningProcesses.delete(runId);
-                void logChain.finally(() => {
+                const completionBarrier = operatorInterrupted ? Promise.resolve() : logChain;
+                void completionBarrier.finally(() => {
                     resolve({
                         exitCode: code,
                         signal: aborted ? "SIGTERM" : signal,