@akira-tl/forgerelay 0.9.4 → 0.10.0

package/dist/runtime/instructions/shell-instructions.js

@@ -0,0 +1,100 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const TEMPLATE_REPOSITORY_RAW = "https://raw.githubusercontent.com/Akira-TL/forgerelay";
+const TEMPLATE_DIRECTORY = "templates/instructions";
+export function shellInstructionFamily(family) {
+    if (family === "pwsh" || family === "powershell" || family === "cmd" || family === "zsh" || family === "fish") {
+        return family;
+    }
+    return undefined;
+}
+export function shellInstructionPath(configDir, family) {
+    const instructionFamily = shellInstructionFamily(family);
+    return instructionFamily ? join(resolve(configDir), "instructions", `${instructionFamily}.md`) : undefined;
+}
+export function shellInstructionFamiliesToSeed(platform, selectedFamily) {
+    const selectedPosixGuidance = selectedFamily === "zsh" || selectedFamily === "fish"
+        ? [selectedFamily]
+        : [];
+    if (platform === "win32")
+        return ["pwsh", "powershell", "cmd", ...selectedPosixGuidance];
+    return selectedPosixGuidance;
+}
+export function shellInstructionTemplateUrl(version, family) {
+    const normalizedVersion = version.trim().replace(/^v/, "");
+    if (!normalizedVersion)
+        throw new Error("ForgeRelay version is required to fetch shell Instructions.");
+    return `${TEMPLATE_REPOSITORY_RAW}/v${encodeURIComponent(normalizedVersion)}/${TEMPLATE_DIRECTORY}/${family}.md`;
+}
+export async function seedShellInstructionFiles(options) {
+    const instructionsDir = join(resolve(options.configDir), "instructions");
+    await mkdir(instructionsDir, { recursive: true, mode: 0o700 });
+    const fetchText = options.fetchText ?? fetchInstructionText;
+    const uniqueFamilies = [...new Set(options.families)];
+    const results = [];
+    for (const family of uniqueFamilies) {
+        const path = join(instructionsDir, `${family}.md`);
+        const sourceUrl = shellInstructionTemplateUrl(options.version, family);
+        if (!options.reset && await fileExists(path)) {
+            results.push({ family, path, status: "preserved", sourceUrl });
+            continue;
+        }
+        try {
+            const content = await fetchText(sourceUrl);
+            if (!content.trim())
+                throw new Error("template response was empty");
+            await writeFile(path, content.endsWith("\n") ? content : `${content}\n`, {
+                encoding: "utf8",
+                mode: 0o600,
+                flag: options.reset ? "w" : "wx",
+            });
+            results.push({ family, path, status: "created", sourceUrl });
+        }
+        catch (error) {
+            if (!options.reset && await fileExists(path)) {
+                results.push({ family, path, status: "preserved", sourceUrl });
+                continue;
+            }
+            results.push({
+                family,
+                path,
+                status: "failed",
+                sourceUrl,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return results;
+}
+export async function readShellInstruction(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+async function fetchInstructionText(url) {
+    const response = await fetch(url, {
+        headers: { "user-agent": "forgerelay-shell-instructions" },
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} while fetching ${url}`);
+    }
+    return response.text();
+}
+async function fileExists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}

package/dist/runtime/security/runtime-privilege.js

@@ -0,0 +1,120 @@
+import { spawnSync } from "node:child_process";
+const WINDOWS_ELEVATED_INTEGRITY_SIDS = [
+    "S-1-16-12288", // High Mandatory Level
+    "S-1-16-16384", // System Mandatory Level
+    "S-1-16-20480", // Protected Process Mandatory Level
+];
+const WINDOWS_LOCAL_SYSTEM_SID = "S-1-5-18";
+export function detectRuntimePrivilege(dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    if (platform === "win32") {
+        return detectWindowsRuntimePrivilege(dependencies.runWindowsWhoami ?? runWindowsWhoami);
+    }
+    if (platform === "linux" || platform === "darwin") {
+        const geteuid = dependencies.geteuid ?? process.geteuid?.bind(process);
+        if (!geteuid) {
+            return {
+                level: "unknown",
+                platform,
+                source: "unsupported",
+                detail: "effective user id is unavailable",
+            };
+        }
+        return {
+            level: geteuid() === 0 ? "elevated" : "standard",
+            platform,
+            source: "posix-euid",
+        };
+    }
+    return {
+        level: "unknown",
+        platform,
+        source: "unsupported",
+        detail: `privilege detection is not implemented for ${platform}`,
+    };
+}
+export function assertRuntimePrivilegeAllowed(state, allowElevated) {
+    if (state.level === "standard" || allowElevated)
+        return;
+    const detected = state.level === "elevated"
+        ? "ForgeRelay detected elevated operating-system privileges."
+        : `ForgeRelay could not safely determine whether this process is elevated${state.detail ? ` (${state.detail})` : ""}.`;
+    throw new Error([
+        detected,
+        "ForgeRelay refuses to start its Agent/Hook runtime with system-level or unknown privilege by default because commands may make system-wide or irreversible changes.",
+        "",
+        "Run ForgeRelay as a normal user, or if elevated execution is intentional, acknowledge the risk for this invocation:",
+        "  forgerelay serve --allow-elevated",
+        "",
+        "The --allow-elevated acknowledgement is invocation-scoped and is not a persistent configuration setting.",
+    ].join("\n"));
+}
+export function formatRuntimePrivilege(state) {
+    const detail = state.detail ? ` (${state.detail})` : "";
+    return `${state.level}${detail}`;
+}
+export function elevatedRuntimeWarning(state) {
+    const status = state.level === "elevated"
+        ? "elevated operating-system privileges"
+        : state.level === "unknown"
+            ? "an unverified operating-system privilege level"
+            : "standard operating-system privileges";
+    return [
+        `WARNING: --allow-elevated was supplied and ForgeRelay is starting with ${status}.`,
+        "Agent and Hook commands run with the ForgeRelay process authority and may make system-wide or irreversible changes.",
+        "Continue only when this level of operating-system access is intentional.",
+    ].join("\n");
+}
+function detectWindowsRuntimePrivilege(runWhoami) {
+    const user = runWhoami(["/user", "/fo", "csv", "/nh"]);
+    const groups = runWhoami(["/groups", "/fo", "csv", "/nh"]);
+    if (user.status !== 0 || groups.status !== 0) {
+        const reason = [user.stderr, groups.stderr]
+            .map((value) => value.trim())
+            .filter(Boolean)
+            .join("; ");
+        return {
+            level: "unknown",
+            platform: "win32",
+            source: "windows-token",
+            detail: reason || "whoami.exe could not inspect the current process token",
+        };
+    }
+    if (containsSid(user.stdout, WINDOWS_LOCAL_SYSTEM_SID)) {
+        return {
+            level: "elevated",
+            platform: "win32",
+            source: "windows-token",
+            detail: "LocalSystem token",
+        };
+    }
+    const elevatedIntegritySid = WINDOWS_ELEVATED_INTEGRITY_SIDS.find((sid) => containsSid(groups.stdout, sid));
+    if (elevatedIntegritySid) {
+        return {
+            level: "elevated",
+            platform: "win32",
+            source: "windows-token",
+            detail: `integrity ${elevatedIntegritySid}`,
+        };
+    }
+    return {
+        level: "standard",
+        platform: "win32",
+        source: "windows-token",
+    };
+}
+function containsSid(output, sid) {
+    const escaped = sid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^0-9-])${escaped}(?:$|[^0-9-])`, "i").test(output);
+}
+function runWindowsWhoami(args) {
+    const result = spawnSync("whoami.exe", args, {
+        encoding: "utf8",
+        windowsHide: true,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? result.error?.message ?? "",
+    };
+}

package/dist/runtime/shell/command-shell-runtime.js

@@ -0,0 +1,235 @@
+import { existsSync, readlinkSync } from "node:fs";
+import { isAbsolute, resolve, win32 } from "node:path";
+import { spawnSync } from "node:child_process";
+const POSIX_SH_NAMES = new Set(["ash", "dash", "ksh", "sh"]);
+export function resolveCommandShellRuntime(input) {
+    const selected = input.explicit
+        ? { source: "explicit", value: input.explicit }
+        : input.launcher
+            ? { source: "launcher", value: input.launcher }
+            : input.recordedFallback
+                ? { source: "recorded", value: input.recordedFallback }
+                : undefined;
+    if (!selected) {
+        throw new Error("Unable to determine ForgeRelay command shell. Configure a shell explicitly or run `forgerelay init` to record a fallback for non-interactive launches.");
+    }
+    return runtimeFromSelection(selected.value, selected.source);
+}
+/**
+ * Preserve the pre-P3 execution contract while the owner-facing init/config
+ * surface is introduced incrementally. This is deliberately separate from the
+ * strict precedence resolver above: new configuration should call
+ * resolveCommandShellRuntime instead of inventing another fallback.
+ */
+export function resolveConfiguredCommandShellRuntime(preference, platform = process.platform, environment = process.env) {
+    const legacyExplicit = environment.FORGERELAY_COMMAND_SHELL?.trim();
+    if (legacyExplicit) {
+        const explicit = normalizeCommandShellSelection({ executable: legacyExplicit }, platform, environment, true);
+        return resolveCommandShellRuntime({ explicit });
+    }
+    if (!preference)
+        return resolveCompatibilityCommandShellRuntime(platform, environment);
+    if (preference.mode === "pinned") {
+        const explicit = normalizeCommandShellSelection(preference, platform, environment, true);
+        return resolveCommandShellRuntime({ explicit });
+    }
+    const launcher = detectLauncherCommandShell({ platform, environment });
+    if (launcher)
+        return resolveCommandShellRuntime({ launcher });
+    const recordedFallback = normalizeCommandShellSelection(preference, platform, environment, true);
+    return resolveCommandShellRuntime({ recordedFallback });
+}
+export function resolveCompatibilityCommandShellRuntime(platform = process.platform, environment = process.env) {
+    if (platform === "win32") {
+        return runtimeFromSelection({
+            family: "cmd",
+            executable: environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe",
+        }, "compatibility-default");
+    }
+    const configured = environment.FORGERELAY_COMMAND_SHELL?.trim();
+    if (configured) {
+        return runtimeFromSelection({ executable: configured }, "explicit");
+    }
+    if (platform === "linux" || platform === "darwin") {
+        return runtimeFromSelection({ family: "bash", executable: "/bin/bash" }, "compatibility-default");
+    }
+    return runtimeFromSelection({ family: "sh", executable: "/bin/sh" }, "compatibility-default");
+}
+export function detectLauncherCommandShell(dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const environment = dependencies.environment ?? process.env;
+    // npm lifecycle scripts insert their own /bin/sh or cmd.exe. Treating that
+    // wrapper as the user's launcher would recreate the npm-script-shell bug P3
+    // is specifically intended to avoid. The recorded fallback is safer here.
+    if (environment.npm_lifecycle_event)
+        return undefined;
+    const ppid = dependencies.ppid ?? process.ppid;
+    if (!Number.isInteger(ppid) || ppid < 1)
+        return undefined;
+    const parentExecutable = (dependencies.parentExecutable ?? defaultParentExecutable)(platform, ppid);
+    if (!parentExecutable)
+        return undefined;
+    const family = inferCommandShellFamily(parentExecutable);
+    if (!family)
+        return undefined;
+    return {
+        family,
+        executable: resolveExecutablePath(parentExecutable, platform, environment),
+    };
+}
+export function normalizeCommandShellSelection(selection, platform = process.platform, environment = process.env, requireAvailable = false) {
+    const executable = resolveExecutablePath(selection.executable, platform, environment);
+    if (requireAvailable && !executableExists(executable, platform, environment)) {
+        throw new Error(`Configured command-shell executable is unavailable: ${selection.executable}. Choose an installed shell or update the explicit executable path.`);
+    }
+    return { ...selection, executable };
+}
+export function defaultCommandShellSelection(family, platform = process.platform, environment = process.env) {
+    const candidate = family === "bash" && platform !== "win32"
+        ? "/bin/bash"
+        : family === "sh" && platform !== "win32"
+            ? "/bin/sh"
+            : family === "cmd"
+                ? environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe"
+                : family === "powershell"
+                    ? "powershell.exe"
+                    : family;
+    return normalizeCommandShellSelection({ family, executable: candidate }, platform, environment);
+}
+export function inferCommandShellFamily(executable) {
+    const name = executableBasename(executable).toLowerCase().replace(/\.exe$/i, "");
+    if (name === "bash")
+        return "bash";
+    if (name === "zsh")
+        return "zsh";
+    if (name === "fish")
+        return "fish";
+    if (POSIX_SH_NAMES.has(name))
+        return "sh";
+    if (name === "pwsh")
+        return "pwsh";
+    if (name === "powershell")
+        return "powershell";
+    if (name === "cmd")
+        return "cmd";
+    return undefined;
+}
+export function formatCommandShellRuntime(runtime) {
+    const version = runtime.version ? ` ${runtime.version}` : "";
+    return `${runtime.family}${version} (${runtime.executable}; ${runtime.source})`;
+}
+export function snapshotCommandShellRuntime(runtime) {
+    return { ...runtime, capabilities: [...runtime.capabilities] };
+}
+export function commandShellAgentInstruction(runtime) {
+    if (runtime.family === "bash")
+        return "";
+    const version = runtime.version ? ` ${runtime.version}` : "";
+    return [
+        `Command shell runtime: ${runtime.family}${version}.`,
+        `Executable: ${runtime.executable}.`,
+        `Selection source: ${runtime.source}.`,
+        "Write shell commands for this runtime rather than assuming Bash syntax.",
+    ].join(" ");
+}
+function runtimeFromSelection(selection, source) {
+    const executable = selection.executable.trim();
+    if (!executable)
+        throw new Error(`Command shell ${source} selection is missing an executable.`);
+    const family = selection.family ?? inferCommandShellFamily(executable);
+    if (!family) {
+        throw new Error(`Unable to identify the command-shell family for ${executable}. Configure the shell family explicitly instead of allowing ForgeRelay to guess the command language.`);
+    }
+    return {
+        family,
+        executable,
+        source,
+        ...(selection.version?.trim() ? { version: selection.version.trim() } : {}),
+        capabilities: Array.from(new Set(selection.capabilities ?? defaultCapabilities(family))),
+    };
+}
+function defaultCapabilities(family) {
+    switch (family) {
+        case "bash":
+            return ["bash", "profile-isolation", "posix-command-language"];
+        case "zsh":
+            return ["zsh", "profile-isolation", "posix-command-language"];
+        case "sh":
+            return ["posix-sh", "posix-command-language"];
+        case "fish":
+            return ["fish-command-language"];
+        case "pwsh":
+            return ["powershell-command-language", "powershell-core"];
+        case "powershell":
+            return ["powershell-command-language", "windows-powershell"];
+        case "cmd":
+            return ["cmd-command-language"];
+    }
+}
+function executableBasename(executable) {
+    const normalized = executable.trim().replace(/^"|"$/g, "");
+    return win32.basename(normalized.replaceAll("/", "\\"));
+}
+function executableExists(executable, platform, environment) {
+    if (existsSync(executable))
+        return true;
+    return resolveExecutablePath(executable, platform, environment) !== executable;
+}
+function resolveExecutablePath(executable, platform, environment) {
+    const trimmed = executable.trim().replace(/^"|"$/g, "");
+    if (isAbsolute(trimmed) || win32.isAbsolute(trimmed))
+        return trimmed;
+    if (trimmed.includes("/") || trimmed.includes("\\"))
+        return resolve(trimmed);
+    const pathValue = environment.PATH ?? environment.Path ?? environment.path;
+    if (!pathValue)
+        return trimmed;
+    const delimiter = platform === "win32" ? ";" : ":";
+    const extensions = platform === "win32"
+        ? (environment.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    const hasExtension = /\.[A-Za-z0-9]+$/.test(trimmed);
+    for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+        const candidates = platform === "win32" && !hasExtension
+            ? extensions.map((extension) => win32.join(directory, `${trimmed}${extension}`))
+            : [platform === "win32" ? win32.join(directory, trimmed) : resolve(directory, trimmed)];
+        for (const candidate of candidates) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return trimmed;
+}
+function defaultParentExecutable(platform, ppid) {
+    if (platform === "linux") {
+        try {
+            return readlinkSync(`/proc/${ppid}/exe`);
+        }
+        catch {
+            return psParentExecutable(ppid);
+        }
+    }
+    if (platform === "darwin")
+        return psParentExecutable(ppid);
+    if (platform === "win32")
+        return windowsParentExecutable(ppid);
+    return undefined;
+}
+function psParentExecutable(ppid) {
+    const result = spawnSync("ps", ["-p", String(ppid), "-o", "comm="], {
+        encoding: "utf8",
+    });
+    if (result.status !== 0)
+        return undefined;
+    return result.stdout?.trim() || undefined;
+}
+function windowsParentExecutable(ppid) {
+    const result = spawnSync("tasklist.exe", ["/fi", `PID eq ${ppid}`, "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true });
+    if (result.status !== 0)
+        return undefined;
+    const output = result.stdout?.trim();
+    if (!output || output.startsWith("INFO:"))
+        return undefined;
+    const quoted = /^"([^"]+)"/.exec(output);
+    return quoted?.[1] ?? (output.split(",", 1)[0]?.replace(/^"|"$/g, "").trim() || undefined);
+}