okf-catalog 0.1.0

package/dist/source/git-runner.js

@@ -0,0 +1,232 @@
+import { spawn } from "node:child_process";
+import { escapeControls } from "../catalog/text.js";
+import { LOG_VALUE_CAP } from "../log.js";
+/** Variables git may inherit from the person's session; everything else is withheld (D47). */
+const KEEP = [
+    "HOME",
+    "PATH",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LC_ALL",
+    "TMPDIR",
+    "XDG_CONFIG_HOME",
+    "XDG_RUNTIME_DIR",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "SSH_AUTH_SOCK",
+    "SSH_AGENT_PID",
+    "GIT_SSH",
+    "GIT_SSH_COMMAND",
+    "http_proxy",
+    "https_proxy",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "all_proxy",
+    "no_proxy",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "CURL_CA_BUNDLE",
+    "GIT_SSL_CAINFO",
+    "GIT_SSL_CAPATH",
+];
+/** Settings every command carries: no hooks, no monitor, no submodules, no maintenance, no prompts, no credentials in URLs, objects checked. */
+export const GIT_FIXED_CONFIG = [
+    "core.hooksPath=/dev/null",
+    "core.fsmonitor=false",
+    "submodule.recurse=false",
+    "maintenance.auto=false",
+    "gc.auto=0",
+    "protocol.allow=never",
+    "credential.interactive=false",
+    "transfer.credentialsInUrl=die",
+    "fetch.fsckObjects=true",
+];
+const STDERR_RAW_CAP = 64 * 1024;
+const DEFAULT_STDOUT_CAP = 16 * 1024 * 1024;
+const TERM_GRACE_MS = 1000;
+/** The environment git runs with: the keep list, copied when set, and the fixed settings. */
+export function gitEnvironment(source, allowProtocols, cacheRoot) {
+    const env = {};
+    for (const name of KEEP) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    env.GIT_TERMINAL_PROMPT = "0";
+    env.GIT_ALLOW_PROTOCOL = allowProtocols;
+    env.GIT_ATTR_NOSYSTEM = "1";
+    env.GIT_CEILING_DIRECTORIES = cacheRoot;
+    return env;
+}
+/** URL userinfo replaced by `***`; the scp-like `user@host:path` form carries no password and stays. */
+export const redactCredentials = (text) => text.replace(/\b([a-z][a-z0-9+.-]*):\/\/[^\s/@]+@/gi, "$1://***@");
+export class GitError extends Error {
+    code;
+    stderr;
+    timedOut;
+    aborted;
+    overflow;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = "GitError";
+        this.code = details.code ?? null;
+        this.stderr = details.stderr ?? "";
+        this.timedOut = details.timedOut ?? false;
+        this.aborted = details.aborted ?? false;
+        this.overflow = details.overflow ?? false;
+    }
+}
+/** Captured stderr as it may be logged or shown: redacted, escaped, cut. */
+const presentStderr = (raw) => {
+    const text = Buffer.concat(raw).toString("utf8");
+    const safe = escapeControls(redactCredentials(text));
+    return safe.length <= LOG_VALUE_CAP ? safe : `${safe.slice(0, LOG_VALUE_CAP)}…`;
+};
+const killGroup = (child, signal) => {
+    if (child.pid === undefined)
+        return;
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // already gone
+        }
+    }
+};
+/**
+ * Runs git as a transport, nothing more: a fixed binary, a built environment, the fixed settings, an explicit
+ * repository, its own process group (so a timeout or a shutdown ends ssh and every other child with it),
+ * streamed and capped output, and errors that carry no credential.
+ */
+export function createGitRunner(options) {
+    const env = gitEnvironment(options.env, options.allowProtocols, options.cacheRoot);
+    const live = new Set();
+    let closed = false;
+    const configArgs = (extra = []) => [...GIT_FIXED_CONFIG, ...extra].flatMap((pair) => ["-c", pair]);
+    function run(args, run) {
+        return new Promise((resolve, reject) => {
+            if (closed) {
+                reject(new GitError("git was aborted by shutdown", { aborted: true }));
+                return;
+            }
+            const argv = [
+                ...configArgs(run.extraConfig),
+                ...(run.gitDir === undefined ? [] : [`--git-dir=${run.gitDir}`]),
+                ...args,
+            ];
+            const child = spawn(options.binary, argv, {
+                cwd: run.cwd,
+                env,
+                detached: true,
+                stdio: [run.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            });
+            live.add(child);
+            const out = [];
+            const err = [];
+            let outBytes = 0;
+            let errBytes = 0;
+            let settled = false;
+            let stopped = false;
+            let timedOut = false;
+            let aborted = false;
+            let overflow = false;
+            let killTimer;
+            const cap = run.maxStdoutBytes ?? DEFAULT_STDOUT_CAP;
+            const end = () => {
+                if (!settled)
+                    return;
+                clearTimeout(timer);
+                // The SIGKILL after the grace is kept even once git itself has exited: a group member that ignored
+                // SIGTERM (a stuck ssh) still gets it (bite 5 review BR10).
+                live.delete(child);
+            };
+            const terminate = () => {
+                killGroup(child, "SIGTERM");
+                killTimer = setTimeout(() => killGroup(child, "SIGKILL"), TERM_GRACE_MS);
+                killTimer.unref();
+            };
+            const timer = setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, run.timeoutMs);
+            child.okfAbort = () => {
+                aborted = true;
+                terminate();
+            };
+            child.stdout?.on("data", (chunk) => {
+                if (stopped || overflow)
+                    return;
+                if (run.onStdout !== undefined) {
+                    if (run.onStdout(chunk) === "stop") {
+                        stopped = true;
+                        terminate();
+                    }
+                    return;
+                }
+                outBytes += chunk.length;
+                if (outBytes > cap) {
+                    overflow = true;
+                    terminate();
+                    return;
+                }
+                out.push(chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                if (errBytes >= STDERR_RAW_CAP)
+                    return;
+                errBytes += chunk.length;
+                err.push(chunk);
+            });
+            child.on("error", (error) => {
+                settled = true;
+                end();
+                reject(new GitError(`git could not be run: ${redactCredentials(error.message)}`));
+            });
+            child.on("close", (code) => {
+                settled = true;
+                end();
+                const stderr = presentStderr(err);
+                if (aborted)
+                    reject(new GitError("git was aborted by shutdown", { stderr, aborted: true }));
+                else if (timedOut)
+                    reject(new GitError(`git did not finish within ${run.timeoutMs} ms`, {
+                        stderr,
+                        timedOut: true,
+                    }));
+                else if (overflow)
+                    reject(new GitError(`git printed more than ${cap} bytes`, { stderr, overflow: true }));
+                else if (stopped)
+                    resolve({ stdout: Buffer.alloc(0), stderr, code, stopped: true });
+                else if (code !== 0)
+                    reject(new GitError(`git exited with ${code}: ${stderr}`, { code, stderr }));
+                else
+                    resolve({ stdout: Buffer.concat(out), stderr, code, stopped: false });
+            });
+            // A git that exits without reading its input makes the pending write fail with EPIPE; that is not an event
+            // this process should die on (bite 5 review BR3).
+            child.stdin?.on("error", () => undefined);
+            if (run.input !== undefined)
+                child.stdin?.end(run.input);
+        });
+    }
+    return {
+        run,
+        abort: () => {
+            // Once aborted, no command starts again: a shutdown must not race a tick into a fresh fetch.
+            closed = true;
+            for (const child of live)
+                child.okfAbort?.();
+        },
+        get running() {
+            return live.size;
+        },
+        env,
+    };
+}
+//# sourceMappingURL=git-runner.js.map

package/dist/source/git-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-runner.js","sourceRoot":"","sources":["../../src/source/git-runner.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn } from \"node:child_process\";\nimport { escapeControls } from \"../catalog/text.js\";\nimport { LOG_VALUE_CAP } from \"../log.js\";\n\n/** Variables git may inherit from the person's session; everything else is withheld (D47). */\nconst KEEP = [\n  \"HOME\",\n  \"PATH\",\n  \"USER\",\n  \"LOGNAME\",\n  \"LANG\",\n  \"LC_ALL\",\n  \"TMPDIR\",\n  \"XDG_CONFIG_HOME\",\n  \"XDG_RUNTIME_DIR\",\n  \"DBUS_SESSION_BUS_ADDRESS\",\n  \"SSH_AUTH_SOCK\",\n  \"SSH_AGENT_PID\",\n  \"GIT_SSH\",\n  \"GIT_SSH_COMMAND\",\n  \"http_proxy\",\n  \"https_proxy\",\n  \"HTTP_PROXY\",\n  \"HTTPS_PROXY\",\n  \"ALL_PROXY\",\n  \"NO_PROXY\",\n  \"all_proxy\",\n  \"no_proxy\",\n  \"SSL_CERT_FILE\",\n  \"SSL_CERT_DIR\",\n  \"CURL_CA_BUNDLE\",\n  \"GIT_SSL_CAINFO\",\n  \"GIT_SSL_CAPATH\",\n] as const;\n\n/** Settings every command carries: no hooks, no monitor, no submodules, no maintenance, no prompts, no credentials in URLs, objects checked. */\nexport const GIT_FIXED_CONFIG: readonly string[] = [\n  \"core.hooksPath=/dev/null\",\n  \"core.fsmonitor=false\",\n  \"submodule.recurse=false\",\n  \"maintenance.auto=false\",\n  \"gc.auto=0\",\n  \"protocol.allow=never\",\n  \"credential.interactive=false\",\n  \"transfer.credentialsInUrl=die\",\n  \"fetch.fsckObjects=true\",\n];\n\nconst STDERR_RAW_CAP = 64 * 1024;\nconst DEFAULT_STDOUT_CAP = 16 * 1024 * 1024;\nconst TERM_GRACE_MS = 1000;\n\n/** The environment git runs with: the keep list, copied when set, and the fixed settings. */\nexport function gitEnvironment(\n  source: NodeJS.ProcessEnv,\n  allowProtocols: string,\n  cacheRoot: string,\n): NodeJS.ProcessEnv {\n  const env: NodeJS.ProcessEnv = {};\n  for (const name of KEEP) {\n    const value = source[name];\n    if (value !== undefined) env[name] = value;\n  }\n  env.GIT_TERMINAL_PROMPT = \"0\";\n  env.GIT_ALLOW_PROTOCOL = allowProtocols;\n  env.GIT_ATTR_NOSYSTEM = \"1\";\n  env.GIT_CEILING_DIRECTORIES = cacheRoot;\n  return env;\n}\n\n/** URL userinfo replaced by `***`; the scp-like `user@host:path` form carries no password and stays. */\nexport const redactCredentials = (text: string): string =>\n  text.replace(/\\b([a-z][a-z0-9+.-]*):\\/\\/[^\\s/@]+@/gi, \"$1://***@\");\n\nexport class GitError extends Error {\n  readonly code: number | null;\n  readonly stderr: string;\n  readonly timedOut: boolean;\n  readonly aborted: boolean;\n  readonly overflow: boolean;\n  constructor(\n    message: string,\n    details: {\n      code?: number | null;\n      stderr?: string;\n      timedOut?: boolean;\n      aborted?: boolean;\n      overflow?: boolean;\n    } = {},\n  ) {\n    super(message);\n    this.name = \"GitError\";\n    this.code = details.code ?? null;\n    this.stderr = details.stderr ?? \"\";\n    this.timedOut = details.timedOut ?? false;\n    this.aborted = details.aborted ?? false;\n    this.overflow = details.overflow ?? false;\n  }\n}\n\nexport interface RunOptions {\n  cwd: string;\n  /** Passed as `--git-dir=` once the clone exists, so git never searches for a repository. */\n  gitDir?: string;\n  timeoutMs: number;\n  /** Written to the command's stdin, then closed. */\n  input?: string;\n  /** Receives stdout as it arrives; answering `stop` ends the command, and `stdout` is then empty. */\n  onStdout?: (chunk: Buffer) => \"continue\" | \"stop\";\n  /** The most stdout kept when no consumer streams it. */\n  maxStdoutBytes?: number;\n  /** Extra `-c key=value` settings for this call only. */\n  extraConfig?: readonly string[];\n}\n\nexport interface RunResult {\n  stdout: Buffer;\n  stderr: string;\n  code: number | null;\n  /** The consumer stopped the command before it finished. */\n  stopped: boolean;\n}\n\nexport interface GitRunner {\n  run(args: readonly string[], options: RunOptions): Promise<RunResult>;\n  /** Kills every running command, with its whole process group, and refuses every command after it. */\n  abort(): void;\n  readonly running: number;\n  /** The environment every command runs with, for callers that must know what git will see. */\n  readonly env: NodeJS.ProcessEnv;\n}\n\nexport interface RunnerOptions {\n  /** An absolute path to git; never read from the environment. */\n  binary: string;\n  /** The `GIT_ALLOW_PROTOCOL` value: `https:ssh` in production, with `file` added by tests. */\n  allowProtocols: string;\n  cacheRoot: string;\n  env: NodeJS.ProcessEnv;\n}\n\n/** Captured stderr as it may be logged or shown: redacted, escaped, cut. */\nconst presentStderr = (raw: Buffer[]): string => {\n  const text = Buffer.concat(raw).toString(\"utf8\");\n  const safe = escapeControls(redactCredentials(text));\n  return safe.length <= LOG_VALUE_CAP ? safe : `${safe.slice(0, LOG_VALUE_CAP)}…`;\n};\n\nconst killGroup = (child: ChildProcess, signal: NodeJS.Signals): void => {\n  if (child.pid === undefined) return;\n  try {\n    process.kill(-child.pid, signal);\n  } catch {\n    try {\n      child.kill(signal);\n    } catch {\n      // already gone\n    }\n  }\n};\n\n/**\n * Runs git as a transport, nothing more: a fixed binary, a built environment, the fixed settings, an explicit\n * repository, its own process group (so a timeout or a shutdown ends ssh and every other child with it),\n * streamed and capped output, and errors that carry no credential.\n */\nexport function createGitRunner(options: RunnerOptions): GitRunner {\n  const env = gitEnvironment(options.env, options.allowProtocols, options.cacheRoot);\n  const live = new Set<ChildProcess>();\n  let closed = false;\n  const configArgs = (extra: readonly string[] = []): string[] =>\n    [...GIT_FIXED_CONFIG, ...extra].flatMap((pair) => [\"-c\", pair]);\n\n  function run(args: readonly string[], run: RunOptions): Promise<RunResult> {\n    return new Promise<RunResult>((resolve, reject) => {\n      if (closed) {\n        reject(new GitError(\"git was aborted by shutdown\", { aborted: true }));\n        return;\n      }\n      const argv = [\n        ...configArgs(run.extraConfig),\n        ...(run.gitDir === undefined ? [] : [`--git-dir=${run.gitDir}`]),\n        ...args,\n      ];\n      const child = spawn(options.binary, argv, {\n        cwd: run.cwd,\n        env,\n        detached: true,\n        stdio: [run.input === undefined ? \"ignore\" : \"pipe\", \"pipe\", \"pipe\"],\n      });\n      live.add(child);\n      const out: Buffer[] = [];\n      const err: Buffer[] = [];\n      let outBytes = 0;\n      let errBytes = 0;\n      let settled = false;\n      let stopped = false;\n      let timedOut = false;\n      let aborted = false;\n      let overflow = false;\n      let killTimer: NodeJS.Timeout | undefined;\n      const cap = run.maxStdoutBytes ?? DEFAULT_STDOUT_CAP;\n      const end = (): void => {\n        if (!settled) return;\n        clearTimeout(timer);\n        // The SIGKILL after the grace is kept even once git itself has exited: a group member that ignored\n        // SIGTERM (a stuck ssh) still gets it (bite 5 review BR10).\n        live.delete(child);\n      };\n      const terminate = (): void => {\n        killGroup(child, \"SIGTERM\");\n        killTimer = setTimeout(() => killGroup(child, \"SIGKILL\"), TERM_GRACE_MS);\n        killTimer.unref();\n      };\n      const timer = setTimeout(() => {\n        timedOut = true;\n        terminate();\n      }, run.timeoutMs);\n      (child as ChildProcess & { okfAbort?: () => void }).okfAbort = () => {\n        aborted = true;\n        terminate();\n      };\n      child.stdout?.on(\"data\", (chunk: Buffer) => {\n        if (stopped || overflow) return;\n        if (run.onStdout !== undefined) {\n          if (run.onStdout(chunk) === \"stop\") {\n            stopped = true;\n            terminate();\n          }\n          return;\n        }\n        outBytes += chunk.length;\n        if (outBytes > cap) {\n          overflow = true;\n          terminate();\n          return;\n        }\n        out.push(chunk);\n      });\n      child.stderr?.on(\"data\", (chunk: Buffer) => {\n        if (errBytes >= STDERR_RAW_CAP) return;\n        errBytes += chunk.length;\n        err.push(chunk);\n      });\n      child.on(\"error\", (error) => {\n        settled = true;\n        end();\n        reject(new GitError(`git could not be run: ${redactCredentials(error.message)}`));\n      });\n      child.on(\"close\", (code) => {\n        settled = true;\n        end();\n        const stderr = presentStderr(err);\n        if (aborted) reject(new GitError(\"git was aborted by shutdown\", { stderr, aborted: true }));\n        else if (timedOut)\n          reject(\n            new GitError(`git did not finish within ${run.timeoutMs} ms`, {\n              stderr,\n              timedOut: true,\n            }),\n          );\n        else if (overflow)\n          reject(new GitError(`git printed more than ${cap} bytes`, { stderr, overflow: true }));\n        else if (stopped) resolve({ stdout: Buffer.alloc(0), stderr, code, stopped: true });\n        else if (code !== 0)\n          reject(new GitError(`git exited with ${code}: ${stderr}`, { code, stderr }));\n        else resolve({ stdout: Buffer.concat(out), stderr, code, stopped: false });\n      });\n      // A git that exits without reading its input makes the pending write fail with EPIPE; that is not an event\n      // this process should die on (bite 5 review BR3).\n      child.stdin?.on(\"error\", () => undefined);\n      if (run.input !== undefined) child.stdin?.end(run.input);\n    });\n  }\n\n  return {\n    run,\n    abort: () => {\n      // Once aborted, no command starts again: a shutdown must not race a tick into a fresh fetch.\n      closed = true;\n      for (const child of live) (child as ChildProcess & { okfAbort?: () => void }).okfAbort?.();\n    },\n    get running() {\n      return live.size;\n    },\n    env,\n  };\n}\n"]}