@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/utils/run-git-command.js

@@ -0,0 +1,393 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync } from "node:fs";
+import { GitCommandRuntimeMetricsWindow, } from "./git-command-runtime-metrics.js";
+import { settleGitCommandTrace, spawnGitCommandTrace, startGitCommandTrace, submitGitCommandTrace, } from "./git-command-trace.js";
+import { spawnProcess } from "./spawn.js";
+import { GitProcessScheduler, resolveGitProcessPolicy, } from "./git-process-scheduler.js";
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_OUTPUT_BYTES = 20 * 1024 * 1024; // 20MB
+const DEFAULT_STDERR_LIMIT = 2048;
+let gitProcessScheduler = new GitProcessScheduler(resolveGitProcessPolicy({ env: process.env }));
+let gitRuntimeMetrics = createGitCommandRuntimeMetricsWindow(gitProcessScheduler.policy);
+const gitCommandPriority = new AsyncLocalStorage();
+export function runWithGitCommandPriority(priority, operation) {
+    return gitCommandPriority.run(priority, operation);
+}
+function createGitCommandRuntimeMetricsWindow(policy) {
+    return new GitCommandRuntimeMetricsWindow({
+        concurrencyLimit: policy.maxProcessConcurrency,
+        maxProcessesPerSecond: policy.maxProcessesPerSecond,
+    });
+}
+export function configureGitProcessPolicy(policy) {
+    gitProcessScheduler = new GitProcessScheduler(policy);
+    gitRuntimeMetrics = createGitCommandRuntimeMetricsWindow(policy);
+}
+export function createRunGitCommand(provenance) {
+    return (args, options) => runGitCommandWithProvenance(args, options, provenance);
+}
+let gitCommandMetricsState = null;
+export function startGitCommandMetrics() {
+    gitCommandMetricsState = {
+        commands: [],
+        submissions: [],
+        submitted: 0,
+        started: 0,
+        completed: 0,
+        active: 0,
+        maxConcurrent: 0,
+        lastSubmittedAtMs: Date.now(),
+    };
+}
+export function stopGitCommandMetrics() {
+    const state = gitCommandMetricsState;
+    if (!state) {
+        return {
+            commands: [],
+            submissions: [],
+            submitted: 0,
+            started: 0,
+            completed: 0,
+            active: 0,
+            pending: 0,
+            total: 0,
+            failed: 0,
+            maxConcurrent: 0,
+        };
+    }
+    const unfinished = state.submitted - state.completed;
+    if (unfinished > 0) {
+        throw new Error(`Cannot stop Git command metrics while ${unfinished} submitted commands are unfinished`);
+    }
+    gitCommandMetricsState = null;
+    return snapshotGitCommandMetricsState(state);
+}
+export function getGitCommandMetrics() {
+    const state = gitCommandMetricsState;
+    if (!state) {
+        return stopGitCommandMetrics();
+    }
+    return snapshotGitCommandMetricsState(state);
+}
+export async function waitForGitCommandMetricsIdle(options) {
+    const startedAtMs = Date.now();
+    while (true) {
+        const state = gitCommandMetricsState;
+        if (!state) {
+            throw new Error("Git command metrics are not running");
+        }
+        const isComplete = state.completed === state.submitted;
+        const hasBeenQuiet = Date.now() - state.lastSubmittedAtMs >= options.quietMs;
+        if (isComplete && hasBeenQuiet) {
+            return;
+        }
+        if (Date.now() - startedAtMs >= options.timeoutMs) {
+            const unfinished = state.submitted - state.completed;
+            throw new Error(`Timed out waiting for Git command metrics to become idle (${unfinished} unfinished)`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+function snapshotGitCommandMetricsState(state) {
+    return {
+        commands: [...state.commands],
+        submissions: state.submissions.map((submission) => ({
+            args: [...submission.args],
+            cwd: submission.cwd,
+        })),
+        submitted: state.submitted,
+        started: state.started,
+        completed: state.completed,
+        active: state.active,
+        pending: state.submitted - state.started,
+        total: state.commands.length,
+        failed: state.commands.filter((command) => !command.success).length,
+        maxConcurrent: state.maxConcurrent,
+    };
+}
+export function snapshotGitCommandRuntimeMetrics() {
+    return gitRuntimeMetrics.snapshotAndReset({
+        active: gitProcessScheduler.activeCount,
+        pending: gitProcessScheduler.pendingCount,
+    });
+}
+function submitGitCommandMetric(args, cwd) {
+    const state = gitCommandMetricsState;
+    if (!state) {
+        return null;
+    }
+    state.submissions.push({ args: [...args], cwd });
+    state.submitted += 1;
+    state.lastSubmittedAtMs = Date.now();
+    return state;
+}
+function beginGitCommandMetric(state) {
+    if (!state) {
+        return;
+    }
+    state.started += 1;
+    state.active += 1;
+    state.maxConcurrent = Math.max(state.maxConcurrent, state.active);
+}
+function finishGitCommandMetric(state, metric) {
+    if (!state) {
+        return;
+    }
+    state.active = Math.max(0, state.active - 1);
+    state.completed += 1;
+    state.commands.push(metric);
+}
+function mergeEnvOverlays(env, envOverlay) {
+    if (!env) {
+        return envOverlay;
+    }
+    if (!envOverlay) {
+        return env;
+    }
+    return { ...env, ...envOverlay };
+}
+function getEnvOverlayKeys(envOverlay) {
+    return Object.keys(envOverlay ?? {}).sort();
+}
+function runGitCommandWithProvenance(args, options, provenance) {
+    const metricsState = submitGitCommandMetric(args, options.cwd);
+    const commandTrace = submitGitCommandTrace(args, options.cwd, {
+        active: gitProcessScheduler.activeCount,
+        pending: gitProcessScheduler.pendingCount,
+    });
+    const runtimeMetric = gitRuntimeMetrics.submit(getGitOperation(args), provenance);
+    const startCommand = () => {
+        let releaseProcessSlot;
+        const exited = new Promise((resolve) => {
+            releaseProcessSlot = resolve;
+        });
+        const resultPromise = new Promise((resolve, reject) => {
+            startGitCommandTrace(commandTrace, {
+                active: gitProcessScheduler.activeCount,
+                pending: gitProcessScheduler.pendingCount,
+            });
+            gitRuntimeMetrics.start(runtimeMetric);
+            const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+            const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+            const acceptExitCodes = options.acceptExitCodes ?? [0];
+            const command = formatGitCommand(args);
+            const envOverlay = mergeEnvOverlays(options.env, options.envOverlay);
+            const startedAt = Date.now();
+            beginGitCommandMetric(metricsState);
+            const logger = typeof options.logger?.trace === "function" ? options.logger : undefined;
+            const traceContext = logger
+                ? {
+                    command: "git",
+                    args,
+                    cwd: options.cwd,
+                    cwdExists: existsSync(options.cwd),
+                    timeout,
+                    maxOutputBytes,
+                    acceptExitCodes,
+                    envOverlayKeys: getEnvOverlayKeys(envOverlay),
+                }
+                : null;
+            if (logger && traceContext) {
+                logger.trace(traceContext, "Spawning git command");
+            }
+            let settled = false;
+            let metricFinished = false;
+            let processError = null;
+            let processExit = null;
+            let timeoutError = null;
+            let truncated = false;
+            let stdoutBytes = 0;
+            let stderrBytes = 0;
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            let timer;
+            const settle = (callback) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                callback();
+            };
+            const finishMetricOnce = (metric, timedOut = false) => {
+                if (metricFinished)
+                    return;
+                metricFinished = true;
+                finishGitCommandMetric(metricsState, metric);
+                gitRuntimeMetrics.finish(runtimeMetric, { success: metric.success, timedOut });
+            };
+            const settleTimeoutTrace = (exitCode, signal) => {
+                settleGitCommandTrace(commandTrace, {
+                    outcome: "timed_out",
+                    exitCode,
+                    signal,
+                });
+            };
+            const markProcessExited = (exitCode, signal) => {
+                if (processExit)
+                    return;
+                processExit = { exitCode, signal };
+                const timedOut = timeoutError !== null;
+                finishMetricOnce({
+                    args,
+                    cwd: options.cwd,
+                    startedAtMs: startedAt,
+                    durationMs: Date.now() - startedAt,
+                    exitCode,
+                    signal,
+                    success: !timedOut && !processError && (truncated || acceptExitCodes.includes(exitCode ?? -1)),
+                }, timedOut);
+                releaseProcessSlot();
+                if (timedOut) {
+                    settleTimeoutTrace(exitCode, signal);
+                }
+            };
+            const rejectSpawnFailure = (error) => {
+                processError = error instanceof Error ? error : new Error(String(error));
+                markProcessExited(null, null);
+                settleGitCommandTrace(commandTrace, {
+                    outcome: "spawn_error",
+                    exitCode: null,
+                    signal: null,
+                });
+                settle(() => reject(processError));
+            };
+            let child;
+            try {
+                // `core.quotepath=false` makes git emit raw UTF-8 paths instead of
+                // octal-escaping non-ASCII bytes (e.g. `测试文件.txt` vs `"\346\265\213..."`).
+                // `core.fsmonitor=false` prevents repository config from launching a command.
+                child = spawnProcess("git", ["-c", "core.quotepath=false", "-c", "core.fsmonitor=false", ...args], {
+                    cwd: options.cwd,
+                    envOverlay,
+                    shell: false,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                spawnGitCommandTrace(commandTrace, child.pid);
+            }
+            catch (error) {
+                rejectSpawnFailure(error);
+                return;
+            }
+            const stdout = child.stdout;
+            const stderr = child.stderr;
+            if (!stdout || !stderr) {
+                child.kill("SIGKILL");
+                rejectSpawnFailure(new Error("Git process did not expose piped stdout and stderr"));
+                return;
+            }
+            timer = setTimeout(() => {
+                timeoutError = new Error(`Git command timed out after ${timeout}ms: ${command}`);
+                child.kill("SIGKILL");
+                settle(() => reject(timeoutError));
+                if (processExit) {
+                    settleTimeoutTrace(processExit.exitCode, processExit.signal);
+                }
+            }, timeout);
+            stdout.on("data", (chunk) => {
+                if (settled || truncated)
+                    return;
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const remainingBytes = maxOutputBytes - stdoutBytes;
+                if (remainingBytes <= 0) {
+                    truncated = true;
+                    child.kill("SIGKILL");
+                    return;
+                }
+                if (buffer.length > remainingBytes) {
+                    stdoutChunks.push(buffer.subarray(0, remainingBytes));
+                    stdoutBytes += remainingBytes;
+                    truncated = true;
+                    child.kill("SIGKILL");
+                    return;
+                }
+                stdoutChunks.push(buffer);
+                stdoutBytes += buffer.length;
+            });
+            stderr.on("data", (chunk) => {
+                if (settled || stderrBytes >= DEFAULT_STDERR_LIMIT)
+                    return;
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const remainingBytes = DEFAULT_STDERR_LIMIT - stderrBytes;
+                if (buffer.length > remainingBytes) {
+                    stderrChunks.push(buffer.subarray(0, remainingBytes));
+                    stderrBytes += remainingBytes;
+                    return;
+                }
+                stderrChunks.push(buffer);
+                stderrBytes += buffer.length;
+            });
+            child.on("error", (error) => {
+                processError = error;
+                if (logger && traceContext) {
+                    logger.trace({
+                        ...traceContext,
+                        err: error,
+                        durationMs: Date.now() - startedAt,
+                    }, "Git command process error");
+                }
+            });
+            child.on("exit", markProcessExited);
+            child.on("close", (exitCode, signal) => {
+                markProcessExited(exitCode, signal);
+                const result = {
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                    truncated,
+                    exitCode,
+                    signal,
+                };
+                if (logger && traceContext) {
+                    logger.trace({
+                        ...traceContext,
+                        durationMs: Date.now() - startedAt,
+                        exitCode,
+                        signal,
+                        truncated,
+                        stdoutBytes,
+                        stderrBytes,
+                    }, "Git command closed");
+                }
+                if (timeoutError) {
+                    return;
+                }
+                if (processError) {
+                    settleGitCommandTrace(commandTrace, {
+                        outcome: "spawn_error",
+                        exitCode,
+                        signal,
+                    });
+                    settle(() => reject(processError));
+                    return;
+                }
+                settleGitCommandTrace(commandTrace, {
+                    outcome: "closed",
+                    exitCode,
+                    signal,
+                    truncated,
+                });
+                if (!truncated && !acceptExitCodes.includes(exitCode ?? -1)) {
+                    const stderrPreview = result.stderr.trim() || "(no stderr)";
+                    const truncationNote = result.truncated ? " (stdout truncated)" : "";
+                    settle(() => reject(new Error(`Git command failed: ${command}${truncationNote} (exit code: ${String(exitCode)}, signal: ${signal ?? "none"})\n${stderrPreview}`)));
+                    return;
+                }
+                settle(() => resolve(result));
+            });
+        });
+        return { result: resultPromise, exited };
+    };
+    const promise = gitProcessScheduler.run(startCommand, {
+        priority: gitCommandPriority.getStore() ?? "normal",
+    });
+    gitRuntimeMetrics.observeLimiter(gitProcessScheduler.activeCount, gitProcessScheduler.pendingCount);
+    return promise;
+}
+export const runGitCommand = runGitCommandWithProvenance;
+function formatGitCommand(args) {
+    return ["git", ...args].join(" ");
+}
+function getGitOperation(args) {
+    return args[0] === "-c" ? (args[2] ?? "unknown") : (args[0] ?? "unknown");
+}
+//# sourceMappingURL=run-git-command.js.map

package/dist/server/utils/spawn.d.ts

@@ -0,0 +1,26 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type ProcessEnvRecord } from "../server/paseo-env.js";
+interface ExternalEnvOptions {
+    baseEnv?: ProcessEnvRecord;
+    envMode?: "external" | "internal";
+    env?: ProcessEnvRecord;
+    envOverlay?: ProcessEnvRecord;
+}
+export type SpawnProcessOptions = Omit<SpawnOptions, "env"> & ExternalEnvOptions;
+interface ExecCommandOptions extends ExternalEnvOptions {
+    cwd?: string;
+    encoding?: BufferEncoding;
+    killSignal?: NodeJS.Signals;
+    timeout?: number;
+    maxBuffer?: number;
+    shell?: boolean | string;
+    signal?: AbortSignal;
+}
+interface ExecCommandResult {
+    stdout: string;
+    stderr: string;
+}
+export declare function spawnProcess(command: string, args: string[], options?: SpawnProcessOptions): ChildProcess;
+export declare function execCommand(command: string, args: string[], options?: ExecCommandOptions): Promise<ExecCommandResult>;
+export {};
+//# sourceMappingURL=spawn.d.ts.map

package/dist/server/utils/spawn.js

@@ -0,0 +1,60 @@
+import { execFile, spawn } from "node:child_process";
+import { extname } from "node:path";
+import { promisify } from "node:util";
+import { createExternalCommandProcessEnv } from "../server/paseo-env.js";
+import { isWindowsCommandScript, quoteWindowsArgument, quoteWindowsCommand, } from "./windows-command.js";
+const execFileAsync = promisify(execFile);
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function shouldUseWindowsShell(command, requestedShell) {
+    if (isWindowsCommandScript(command)) {
+        return true;
+    }
+    if (requestedShell !== undefined) {
+        return requestedShell;
+    }
+    return process.platform === "win32" && !hasPathSeparator(command) && !extname(command);
+}
+export function spawnProcess(command, args, options) {
+    const { baseEnv, env, envOverlay, ...spawnOptions } = options ?? {};
+    const resolvedBaseEnv = env ?? baseEnv ?? process.env;
+    const isWindows = process.platform === "win32";
+    const shell = shouldUseWindowsShell(command, spawnOptions.shell);
+    const shouldQuoteForShell = isWindows && shell !== false;
+    const resolvedCommand = shouldQuoteForShell ? quoteWindowsCommand(command) : command;
+    const resolvedArgs = shouldQuoteForShell ? args.map(quoteWindowsArgument) : args;
+    const childEnv = options?.envMode === "internal"
+        ? { ...resolvedBaseEnv, ...envOverlay }
+        : createExternalCommandProcessEnv(command, resolvedBaseEnv, ...(envOverlay ? [envOverlay] : []));
+    return spawn(resolvedCommand, resolvedArgs, {
+        ...spawnOptions,
+        env: childEnv,
+        shell,
+        signal: options?.signal,
+        windowsHide: true,
+    });
+}
+export async function execCommand(command, args, options) {
+    const { baseEnv, env, envOverlay } = options ?? {};
+    const resolvedBaseEnv = env ?? baseEnv ?? process.env;
+    const isWindows = process.platform === "win32";
+    const shell = shouldUseWindowsShell(command, options?.shell);
+    const shouldQuoteForShell = isWindows && shell !== false;
+    const resolvedCommand = shouldQuoteForShell ? quoteWindowsCommand(command) : command;
+    const resolvedArgs = shouldQuoteForShell ? args.map(quoteWindowsArgument) : args;
+    const childEnv = options?.envMode === "internal"
+        ? { ...resolvedBaseEnv, ...envOverlay }
+        : createExternalCommandProcessEnv(command, resolvedBaseEnv, ...(envOverlay ? [envOverlay] : []));
+    return execFileAsync(resolvedCommand, resolvedArgs, {
+        cwd: options?.cwd,
+        env: childEnv,
+        encoding: options?.encoding ?? "utf8",
+        killSignal: options?.killSignal,
+        timeout: options?.timeout,
+        maxBuffer: options?.maxBuffer,
+        shell,
+        windowsHide: true,
+    });
+}
+//# sourceMappingURL=spawn.js.map

package/dist/server/utils/ssh-hostname.d.ts

@@ -0,0 +1,8 @@
+export type SshHostnameResolver = (host: string) => Promise<string | null>;
+/**
+ * Resolve an SSH host alias (e.g. `github-work` from ~/.ssh/config) to its
+ * configured HostName via `ssh -G`. Results are cached for the daemon's
+ * lifetime; a host that isn't an alias resolves to itself.
+ */
+export declare function resolveSshHostname(host: string): Promise<string | null>;
+//# sourceMappingURL=ssh-hostname.d.ts.map

package/dist/server/utils/ssh-hostname.js

@@ -0,0 +1,60 @@
+import { normalizeHost } from "@camerontaylor/paseo-protocol/git-remote";
+import { findExecutable } from "../executable-resolution/executable-resolution.js";
+import { execCommand } from "./spawn.js";
+const SSH_HOSTNAME_RESOLVE_TIMEOUT_MS = 5000;
+let sshExecutableLookup = null;
+const sshHostnameResolutionCache = new Map();
+/**
+ * Resolve an SSH host alias (e.g. `github-work` from ~/.ssh/config) to its
+ * configured HostName via `ssh -G`. Results are cached for the daemon's
+ * lifetime; a host that isn't an alias resolves to itself.
+ */
+export async function resolveSshHostname(host) {
+    const normalized = normalizeHost(host);
+    if (!normalized) {
+        return null;
+    }
+    const cached = sshHostnameResolutionCache.get(normalized);
+    if (cached) {
+        return cached;
+    }
+    const resolution = runSshHostnameLookup(normalized);
+    sshHostnameResolutionCache.set(normalized, resolution);
+    return resolution;
+}
+async function runSshHostnameLookup(host) {
+    sshExecutableLookup ?? (sshExecutableLookup = findExecutable("ssh"));
+    const sshPath = await sshExecutableLookup;
+    if (!sshPath) {
+        return null;
+    }
+    try {
+        const { stdout } = await execCommand(sshPath, ["-G", host], {
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+            maxBuffer: 1024 * 1024,
+            timeout: SSH_HOSTNAME_RESOLVE_TIMEOUT_MS,
+        });
+        return parseSshHostname(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function parseSshHostname(stdout) {
+    for (const line of stdout.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const [key, value] = trimmed.split(/\s+/u);
+        if (key?.toLowerCase() !== "hostname") {
+            continue;
+        }
+        const normalized = normalizeHost(value ?? "");
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=ssh-hostname.js.map

package/dist/server/utils/string-command-shell.d.ts

@@ -0,0 +1,13 @@
+export interface BuildStringCommandShellInvocationOptions {
+    command: string;
+    platform?: NodeJS.Platform;
+    windowsShell?: "powershell" | "cmd";
+}
+export interface StringCommandShellInvocation {
+    shell: string;
+    args: string[];
+}
+export declare function createStringCommandShellEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function createStringCommandShellEnvOverlay(): Record<string, string | undefined>;
+export declare function buildStringCommandShellInvocation(options: BuildStringCommandShellInvocationOptions): StringCommandShellInvocation;
+//# sourceMappingURL=string-command-shell.d.ts.map

package/dist/server/utils/string-command-shell.js

@@ -0,0 +1,37 @@
+export function createStringCommandShellEnv(env) {
+    const sanitized = { ...env };
+    delete sanitized.BASH_ENV;
+    return sanitized;
+}
+export function createStringCommandShellEnvOverlay() {
+    return { BASH_ENV: undefined };
+}
+export function buildStringCommandShellInvocation(options) {
+    const platform = options.platform ?? process.platform;
+    // Project-authored command strings use a stable script shell. The caller supplies
+    // the environment; shell startup files should not rewrite it behind our back.
+    if (platform === "win32") {
+        if (options.windowsShell === "cmd") {
+            return {
+                shell: "cmd.exe",
+                args: ["/c", options.command],
+            };
+        }
+        return {
+            shell: "powershell",
+            args: [
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                options.command,
+            ],
+        };
+    }
+    return {
+        shell: "bash",
+        args: ["-c", options.command],
+    };
+}
+//# sourceMappingURL=string-command-shell.js.map

package/dist/server/utils/tree-kill.d.ts

@@ -0,0 +1,19 @@
+export interface TreeKillTarget {
+    pid?: number;
+    exitCode?: number | null;
+    signalCode?: NodeJS.Signals | null;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once?(event: "exit", listener: () => void): unknown;
+}
+export interface TerminateWithTreeKillOptions {
+    gracefulSignal?: NodeJS.Signals;
+    forceSignal?: NodeJS.Signals;
+    gracefulTimeoutMs: number;
+    forceTimeoutMs?: number;
+    onForceSignal?: () => void;
+}
+export type TerminateWithTreeKillResult = "already-exited" | "terminated" | "killed" | "kill-timeout";
+export type ProcessTerminator = (child: TreeKillTarget, options: TerminateWithTreeKillOptions) => Promise<TerminateWithTreeKillResult>;
+export declare function terminateWithTreeKill(child: TreeKillTarget, options: TerminateWithTreeKillOptions): Promise<TerminateWithTreeKillResult>;
+export declare function signalProcessTree(child: TreeKillTarget, signal: NodeJS.Signals): Promise<void>;
+//# sourceMappingURL=tree-kill.d.ts.map