pi-webdesk 0.1.0

package/dist/packages/git/src/paths.js

@@ -0,0 +1,58 @@
+// packages/git/src/paths.ts
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { GitServiceError } from "./errors.js";
+function requireAbsolutePath(inputPath, label) {
+  if (!path.isAbsolute(inputPath)) {
+    throw new GitServiceError("GIT_PATH_NOT_ABSOLUTE", `${label} must be an absolute path`, {
+      details: { path: inputPath }
+    });
+  }
+}
+async function realpathOrNull(inputPath) {
+  try {
+    return await realpath(inputPath);
+  } catch {
+    return null;
+  }
+}
+async function canonicalizeDirectory(inputPath, label) {
+  requireAbsolutePath(inputPath, label);
+  let canonical;
+  try {
+    canonical = await realpath(inputPath);
+  } catch (error) {
+    const errno = error;
+    if (errno.code === "ENOENT" || errno.code === "ENOTDIR") {
+      throw new GitServiceError("GIT_PATH_NOT_FOUND", `${label} does not exist`, {
+        cause: error,
+        details: { path: inputPath }
+      });
+    }
+    throw new GitServiceError("GIT_FILESYSTEM_ERROR", `${label} could not be resolved`, {
+      cause: error,
+      details: { path: inputPath }
+    });
+  }
+  const info = await stat(canonical);
+  if (!info.isDirectory()) {
+    throw new GitServiceError("GIT_PATH_NOT_DIRECTORY", `${label} is not a directory`, {
+      details: { path: canonical }
+    });
+  }
+  return canonical;
+}
+async function canonicalPathForms(inputPath) {
+  const resolved = path.resolve(inputPath);
+  const direct = await realpathOrNull(resolved);
+  if (direct !== null) return [resolved, direct];
+  const parentReal = await realpathOrNull(path.dirname(resolved));
+  if (parentReal !== null) return [resolved, path.join(parentReal, path.basename(resolved))];
+  return [resolved];
+}
+export {
+  canonicalPathForms,
+  canonicalizeDirectory,
+  realpathOrNull,
+  requireAbsolutePath
+};

package/dist/packages/git/src/repository.js

@@ -0,0 +1,77 @@
+// packages/git/src/repository.ts
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { GitServiceError, boundedDetailText } from "./errors.js";
+import { canonicalizeDirectory } from "./paths.js";
+import {
+  defaultGitRunner,
+  runGitExpectingSuccess
+} from "./runner.js";
+var COMMIT_SHA_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function singleOutputLine(stdout) {
+  return stdout.endsWith("\n") ? stdout.slice(0, -1) : stdout;
+}
+async function inspectRepository(repositoryPath, options = {}) {
+  const runner = options.runner ?? defaultGitRunner;
+  const cwd = await canonicalizeDirectory(repositoryPath, "repository path");
+  const classify = await runner(["rev-parse", "--is-bare-repository", "--is-inside-work-tree"], {
+    cwd
+  });
+  if (classify.exitCode !== 0) {
+    throw new GitServiceError("GIT_NOT_A_REPOSITORY", "Path is not inside a Git repository", {
+      details: { path: cwd, stderr: boundedDetailText(classify.stderr) }
+    });
+  }
+  const [isBare, isInsideWorkTree] = classify.stdout.split("\n");
+  if (isBare === "true") {
+    throw new GitServiceError("GIT_BARE_REPOSITORY", "Path belongs to a bare Git repository", {
+      details: { path: cwd }
+    });
+  }
+  if (isInsideWorkTree !== "true") {
+    throw new GitServiceError(
+      "GIT_NOT_A_WORK_TREE",
+      "Path is inside a Git repository but not inside its working tree",
+      { details: { path: cwd } }
+    );
+  }
+  const toplevel = await runGitExpectingSuccess(runner, ["rev-parse", "--show-toplevel"], { cwd });
+  const root = await realpath(singleOutputLine(toplevel.stdout));
+  const commonDirResult = await runGitExpectingSuccess(runner, ["rev-parse", "--git-common-dir"], {
+    cwd
+  });
+  const commonDir = await realpath(path.resolve(cwd, singleOutputLine(commonDirResult.stdout)));
+  const head = await runner(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { cwd });
+  if (head.exitCode !== 0) {
+    throw new GitServiceError(
+      "GIT_HEAD_UNRESOLVED",
+      "HEAD does not resolve to a commit (the repository may have no commits yet)",
+      { details: { path: root } }
+    );
+  }
+  const headCommit = singleOutputLine(head.stdout);
+  if (!COMMIT_SHA_PATTERN.test(headCommit)) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git rev-parse returned an unexpected HEAD value", {
+      details: { path: root, value: boundedDetailText(headCommit, 80) }
+    });
+  }
+  const branchResult = await runner(["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd });
+  let branch;
+  if (branchResult.exitCode === 0) {
+    branch = singleOutputLine(branchResult.stdout);
+  } else if (branchResult.exitCode === 1) {
+    branch = null;
+  } else {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git symbolic-ref exited unexpectedly", {
+      details: {
+        exitCode: branchResult.exitCode,
+        stderr: boundedDetailText(branchResult.stderr)
+      }
+    });
+  }
+  return { root, commonDir, headCommit, branch };
+}
+export {
+  COMMIT_SHA_PATTERN,
+  inspectRepository
+};

package/dist/packages/git/src/review.js

@@ -0,0 +1,396 @@
+// packages/git/src/review.ts
+import { createHash } from "node:crypto";
+import { GitServiceError, boundedDetailText, isGitServiceError } from "./errors.js";
+import { inspectRepository } from "./repository.js";
+import {
+  createDefaultGitRunner,
+  defaultGitRunner,
+  runGitExpectingSuccess
+} from "./runner.js";
+var DEFAULT_REVIEW_MAX_FILES = 200;
+var DEFAULT_REVIEW_MAX_DIFF_CHARS_PER_FILE = 2e4;
+var DEFAULT_REVIEW_MAX_TOTAL_DIFF_CHARS = 2e5;
+var DEFAULT_REVIEW_MAX_DURATION_MS = 2e4;
+var DEFAULT_REVIEW_DIFF_TIMEOUT_MS = 2e3;
+var DEFAULT_REVIEW_IDENTITY_RESERVE_MS = 1e3;
+var MIN_REVIEW_DIFF_OUTPUT_BYTES = 64 * 1024;
+var MAX_REVIEW_PATH_CHARS = 4096;
+var READ_ONLY_GIT_FLAGS = [
+  "--no-optional-locks",
+  "--literal-pathspecs",
+  "-c",
+  "core.quotepath=false",
+  "-c",
+  "core.fsmonitor=false"
+];
+var DIFF_FLAGS = [
+  "--no-color",
+  "--no-ext-diff",
+  "--no-textconv",
+  "--unified=3"
+];
+function parseFailure(reason, sample) {
+  return new GitServiceError(
+    "GIT_REVIEW_PARSE_FAILED",
+    `git status returned unexpected output: ${reason}`,
+    { details: { sample: boundedDetailText(sample, 200) } }
+  );
+}
+function validateReportedPath(candidate) {
+  if (candidate.length === 0 || candidate.length > MAX_REVIEW_PATH_CHARS) {
+    throw parseFailure("path is empty or too long", candidate);
+  }
+  if (candidate.startsWith("/")) {
+    throw parseFailure("path is absolute", candidate);
+  }
+  if (candidate.includes("\uFFFD")) {
+    throw parseFailure("path is not valid UTF-8", candidate);
+  }
+  const segments = candidate.split("/");
+  for (const [index, segment] of segments.entries()) {
+    if (segment === "" && index === segments.length - 1 && candidate.endsWith("/")) {
+      continue;
+    }
+    if (segment === "" || segment === "." || segment === "..") {
+      throw parseFailure("path contains an empty, '.', or '..' segment", candidate);
+    }
+  }
+  return candidate;
+}
+function statusPair(parts, token) {
+  const xy = parts[1];
+  if (xy === void 0 || xy.length !== 2) {
+    throw parseFailure("missing XY status field", token);
+  }
+  const [x, y] = xy;
+  if (!/^[.MTADRCU]$/.test(x) || !/^[.MTADRCU]$/.test(y)) {
+    throw parseFailure("invalid XY status field", token);
+  }
+  return { x, y };
+}
+function submoduleState(parts, token) {
+  const sub = parts[2];
+  if (sub === void 0 || !/^(?:N\.\.\.|S[.C][.M][.U])$/.test(sub)) {
+    throw parseFailure("invalid submodule status field", token);
+  }
+  return sub;
+}
+function positiveBound(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new GitServiceError(
+      "GIT_REVIEW_PARSE_FAILED",
+      `${label} must be a positive safe integer`
+    );
+  }
+  return value;
+}
+function restOfRecord(parts, fixedFields, token) {
+  if (parts.length <= fixedFields) {
+    throw parseFailure("missing path field", token);
+  }
+  return parts.slice(fixedFields).join(" ");
+}
+function parseStatusOutput(stdout) {
+  const tokens = stdout.split("\0");
+  const entries = [];
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (token === "") continue;
+    if (token.startsWith("? ")) {
+      entries.push({
+        record: "untracked",
+        path: validateReportedPath(token.slice(2)),
+        previousPath: null,
+        x: ".",
+        y: ".",
+        sub: "N..."
+      });
+      continue;
+    }
+    if (token.startsWith("1 ")) {
+      const parts = token.split(" ");
+      entries.push({
+        record: "changed",
+        path: validateReportedPath(restOfRecord(parts, 8, token)),
+        previousPath: null,
+        ...statusPair(parts, token),
+        sub: submoduleState(parts, token)
+      });
+      continue;
+    }
+    if (token.startsWith("2 ")) {
+      const parts = token.split(" ");
+      const previous = tokens[++index];
+      if (previous === void 0 || previous === "") {
+        throw parseFailure("rename record is missing its source path", token);
+      }
+      entries.push({
+        record: "renamed",
+        path: validateReportedPath(restOfRecord(parts, 9, token)),
+        previousPath: validateReportedPath(previous),
+        ...statusPair(parts, token),
+        sub: submoduleState(parts, token)
+      });
+      continue;
+    }
+    if (token.startsWith("u ")) {
+      const parts = token.split(" ");
+      entries.push({
+        record: "unmerged",
+        path: validateReportedPath(restOfRecord(parts, 10, token)),
+        previousPath: null,
+        ...statusPair(parts, token),
+        sub: submoduleState(parts, token)
+      });
+      continue;
+    }
+    if (token.startsWith("# ") || token.startsWith("! ")) continue;
+    throw parseFailure("unrecognized record type", token);
+  }
+  return entries;
+}
+function changeKind(entry) {
+  if (entry.record === "unmerged") return "conflicted";
+  if (entry.record === "untracked") return "untracked";
+  if (entry.record === "renamed") {
+    return entry.x === "C" || entry.y === "C" ? "copied" : "renamed";
+  }
+  if (entry.x === "A" || entry.y === "A") return "added";
+  if (entry.x === "D" || entry.y === "D") return "deleted";
+  if (entry.x === "T" || entry.y === "T") return "type-changed";
+  return "modified";
+}
+function isBinaryDiff(diff) {
+  return diff.split("\n").some((line) => line.startsWith("Binary files ") && line.endsWith(" differ"));
+}
+async function produceFileDiff(runner, root, entry, baseCommit) {
+  let args;
+  if (entry.record === "untracked") {
+    args = [...READ_ONLY_GIT_FLAGS, "diff", ...DIFF_FLAGS, "--no-index", "--", "/dev/null", entry.path];
+  } else if (entry.record === "unmerged") {
+    args = [...READ_ONLY_GIT_FLAGS, "diff", ...DIFF_FLAGS, "--", entry.path];
+  } else {
+    args = [
+      ...READ_ONLY_GIT_FLAGS,
+      "diff",
+      ...DIFF_FLAGS,
+      "--find-renames",
+      baseCommit,
+      "--",
+      entry.path,
+      ...entry.previousPath === null ? [] : [entry.previousPath]
+    ];
+  }
+  let result;
+  try {
+    result = await runner(args, { cwd: root });
+  } catch (error) {
+    if (isGitServiceError(error, "GIT_OUTPUT_OVERFLOW")) return { outcome: "too-large" };
+    if (isGitServiceError(error, "GIT_REVIEW_DEADLINE_EXCEEDED")) {
+      return { outcome: "review-budget" };
+    }
+    if (isGitServiceError(error, "GIT_COMMAND_TERMINATED")) return { outcome: "diff-failed" };
+    throw error;
+  }
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    return { outcome: "diff-failed" };
+  }
+  if (isBinaryDiff(result.stdout)) return { outcome: "binary" };
+  return { outcome: "text", text: result.stdout };
+}
+function withDeadline(runner, deadlineMs, now, perCommandLimitMs) {
+  return async (args, options = {}) => {
+    const remainingMs = Math.floor(deadlineMs - now());
+    if (remainingMs < 1) {
+      throw new GitServiceError(
+        "GIT_REVIEW_DEADLINE_EXCEEDED",
+        "The Git review exceeded its overall time budget"
+      );
+    }
+    const callerLimitMs = options.timeoutMs ?? Number.POSITIVE_INFINITY;
+    const commandLimitMs = perCommandLimitMs ?? Number.POSITIVE_INFINITY;
+    const aggregateIsLimit = remainingMs <= callerLimitMs && remainingMs <= commandLimitMs;
+    try {
+      return await runner(args, {
+        ...options,
+        timeoutMs: Math.min(remainingMs, callerLimitMs, commandLimitMs)
+      });
+    } catch (error) {
+      if (aggregateIsLimit && isGitServiceError(error, "GIT_COMMAND_TERMINATED")) {
+        throw new GitServiceError(
+          "GIT_REVIEW_DEADLINE_EXCEEDED",
+          "The Git review exceeded its overall time budget",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  };
+}
+function statusEntryId(entry) {
+  return createHash("sha256").update(entry.record).update("\0").update(entry.path).update("\0").update(entry.previousPath ?? "").update("\0").update(entry.x).update(entry.y).update(entry.sub).digest("hex");
+}
+function sameRepositoryIdentity(left, right) {
+  return left.root === right.root && left.commonDir === right.commonDir && left.headCommit === right.headCommit && left.branch === right.branch;
+}
+async function reviewWorktree(options) {
+  const maxFiles = positiveBound(
+    options.maxFiles ?? DEFAULT_REVIEW_MAX_FILES,
+    "Review file limit"
+  );
+  const maxDiffCharsPerFile = positiveBound(
+    options.maxDiffCharsPerFile ?? DEFAULT_REVIEW_MAX_DIFF_CHARS_PER_FILE,
+    "Per-file diff limit"
+  );
+  const maxTotalDiffChars = positiveBound(
+    options.maxTotalDiffChars ?? DEFAULT_REVIEW_MAX_TOTAL_DIFF_CHARS,
+    "Total diff limit"
+  );
+  const maxDurationMs = positiveBound(
+    options.maxDurationMs ?? DEFAULT_REVIEW_MAX_DURATION_MS,
+    "Review duration limit"
+  );
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const deadlineMs = startedAt + maxDurationMs;
+  const identityReserveMs = Math.min(
+    DEFAULT_REVIEW_IDENTITY_RESERVE_MS,
+    Math.max(1, Math.floor(maxDurationMs / 4))
+  );
+  const diffDeadlineMs = deadlineMs - identityReserveMs;
+  const baseRunner = options.runner ?? defaultGitRunner;
+  const reviewRunner = withDeadline(baseRunner, deadlineMs, now);
+  const rawDiffRunner = options.runner ?? createDefaultGitRunner({
+    timeoutMs: DEFAULT_REVIEW_DIFF_TIMEOUT_MS,
+    maxOutputBytes: Math.max(
+      MIN_REVIEW_DIFF_OUTPUT_BYTES,
+      maxDiffCharsPerFile * 4 + 16 * 1024
+    )
+  });
+  const diffRunner = withDeadline(
+    rawDiffRunner,
+    diffDeadlineMs,
+    now,
+    DEFAULT_REVIEW_DIFF_TIMEOUT_MS
+  );
+  const worktree = await inspectRepository(options.worktreePath, { runner: reviewRunner });
+  const status = await runGitExpectingSuccess(
+    reviewRunner,
+    [
+      ...READ_ONLY_GIT_FLAGS,
+      "status",
+      "--porcelain=v2",
+      "-z",
+      "--untracked-files=all"
+    ],
+    { cwd: worktree.root }
+  );
+  const entries = parseStatusOutput(status.stdout);
+  entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const totalChangedFiles = entries.length;
+  const selected = entries.slice(0, maxFiles);
+  let remainingChars = maxTotalDiffChars;
+  let totalDiffTruncated = false;
+  const files = [];
+  for (const entry of selected) {
+    const base = {
+      entryId: statusEntryId(entry),
+      path: entry.path,
+      previousPath: entry.previousPath,
+      kind: changeKind(entry),
+      staged: (entry.record === "changed" || entry.record === "renamed") && entry.x !== ".",
+      unstaged: (entry.record === "changed" || entry.record === "renamed") && entry.y !== "."
+    };
+    if (remainingChars <= 0) {
+      totalDiffTruncated = true;
+      files.push({
+        ...base,
+        binary: false,
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: "total-budget"
+      });
+      continue;
+    }
+    if (now() >= diffDeadlineMs) {
+      totalDiffTruncated = true;
+      files.push({
+        ...base,
+        binary: false,
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: "review-budget"
+      });
+      continue;
+    }
+    const produced = await produceFileDiff(
+      diffRunner,
+      worktree.root,
+      entry,
+      worktree.headCommit
+    );
+    if (produced.outcome !== "text") {
+      if (produced.outcome === "review-budget") totalDiffTruncated = true;
+      files.push({
+        ...base,
+        binary: produced.outcome === "binary",
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: produced.outcome
+      });
+      continue;
+    }
+    const perFileLimit = Math.min(maxDiffCharsPerFile, remainingChars);
+    let text = produced.text;
+    let truncated = false;
+    if (text.length > perFileLimit) {
+      if (perFileLimit < maxDiffCharsPerFile) totalDiffTruncated = true;
+      text = text.slice(0, perFileLimit);
+      truncated = true;
+    }
+    remainingChars -= text.length;
+    files.push({
+      ...base,
+      binary: false,
+      diff: text,
+      diffTruncated: truncated,
+      diffOmittedReason: null
+    });
+  }
+  const verifiedWorktree = await inspectRepository(worktree.root, {
+    runner: reviewRunner
+  });
+  if (!sameRepositoryIdentity(worktree, verifiedWorktree)) {
+    throw new GitServiceError(
+      "GIT_REPOSITORY_CHANGED_DURING_REVIEW",
+      "The worktree branch or HEAD changed while its review was being captured; refresh to retry",
+      {
+        details: {
+          beforeHead: worktree.headCommit,
+          afterHead: verifiedWorktree.headCommit,
+          beforeBranch: worktree.branch,
+          afterBranch: verifiedWorktree.branch
+        }
+      }
+    );
+  }
+  return {
+    worktree,
+    clean: totalChangedFiles === 0,
+    files,
+    totalChangedFiles,
+    omittedFiles: totalChangedFiles - selected.length,
+    totalDiffTruncated
+  };
+}
+export {
+  DEFAULT_REVIEW_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_REVIEW_MAX_DURATION_MS,
+  DEFAULT_REVIEW_MAX_FILES,
+  DEFAULT_REVIEW_MAX_TOTAL_DIFF_CHARS,
+  READ_ONLY_GIT_FLAGS,
+  parseStatusOutput,
+  reviewWorktree,
+  sameRepositoryIdentity,
+  validateReportedPath
+};

package/dist/packages/git/src/runner.js

@@ -0,0 +1,110 @@
+// packages/git/src/runner.ts
+import { execFile } from "node:child_process";
+import { GitServiceError, boundedDetailText } from "./errors.js";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+function createDefaultGitRunner(options = {}) {
+  const gitExecutable = options.gitExecutable ?? "git";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const pinnedEnv = {
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_OPTIONAL_LOCKS: "0",
+    LC_ALL: "C",
+    LANG: "C"
+  };
+  const baseEnv = {
+    ...process.env,
+    ...options.extraEnv,
+    ...pinnedEnv
+  };
+  return (args, runOptions = {}) => new Promise((resolve, reject) => {
+    const invocationTimeoutMs = Math.min(
+      timeoutMs,
+      runOptions.timeoutMs ?? timeoutMs
+    );
+    const env = runOptions.extraEnv === void 0 ? baseEnv : { ...baseEnv, ...runOptions.extraEnv, ...pinnedEnv };
+    const child = execFile(
+      gitExecutable,
+      args,
+      {
+        cwd: runOptions.cwd,
+        env,
+        encoding: "utf8",
+        timeout: invocationTimeoutMs,
+        maxBuffer: maxOutputBytes,
+        windowsHide: true
+      },
+      (error, stdout, stderr) => {
+        if (error === null) {
+          resolve({ exitCode: 0, stdout, stderr });
+          return;
+        }
+        const failure = error;
+        if (typeof failure.code === "number") {
+          resolve({ exitCode: failure.code, stdout, stderr });
+          return;
+        }
+        const details = { args: boundedDetailText(args.join(" "), 256) };
+        if (failure.code === "ENOENT") {
+          reject(
+            new GitServiceError(
+              "GIT_EXECUTABLE_NOT_FOUND",
+              `Git executable "${gitExecutable}" was not found`,
+              { cause: failure, details }
+            )
+          );
+        } else if (failure.killed === true || failure.signal != null) {
+          reject(
+            new GitServiceError(
+              "GIT_COMMAND_TERMINATED",
+              "Git command timed out or was terminated by a signal",
+              { cause: failure, details }
+            )
+          );
+        } else if (failure.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+          reject(
+            new GitServiceError(
+              "GIT_OUTPUT_OVERFLOW",
+              "Git command produced more output than the configured bound",
+              { cause: failure, details }
+            )
+          );
+        } else {
+          reject(
+            new GitServiceError("GIT_SPAWN_FAILED", "Failed to spawn the Git process", {
+              cause: failure,
+              details
+            })
+          );
+        }
+      }
+    );
+    if (child.stdin !== null) {
+      child.stdin.on("error", () => void 0);
+      if (runOptions.stdin !== void 0) {
+        child.stdin.write(runOptions.stdin);
+      }
+      child.stdin.end();
+    }
+  });
+}
+var defaultGitRunner = createDefaultGitRunner();
+async function runGitExpectingSuccess(runner, args, options) {
+  const result = await runner(args, options);
+  if (result.exitCode !== 0) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", `git ${args[0] ?? ""} exited unexpectedly`, {
+      details: {
+        args: boundedDetailText(args.join(" "), 256),
+        exitCode: result.exitCode,
+        stderr: boundedDetailText(result.stderr)
+      }
+    });
+  }
+  return result;
+}
+export {
+  createDefaultGitRunner,
+  defaultGitRunner,
+  runGitExpectingSuccess
+};