pi-webdesk 0.1.0

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

@@ -0,0 +1,55 @@
+// packages/git/src/errors.ts
+var GitServiceError = class extends Error {
+  code;
+  details;
+  constructor(code, message, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "GitServiceError";
+    this.code = code;
+    this.details = options?.details ?? {};
+  }
+};
+function isGitServiceError(value, code) {
+  if (!(value instanceof GitServiceError)) return false;
+  return code === void 0 || value.code === code;
+}
+var GitWorktreeIncompleteError = class extends GitServiceError {
+  facts;
+  constructor(message, facts, options) {
+    super("GIT_WORKTREE_CREATE_INCOMPLETE", message, {
+      cause: options?.cause,
+      details: { ...facts }
+    });
+    this.name = "GitWorktreeIncompleteError";
+    this.facts = facts;
+  }
+};
+var GitMergeConflictError = class extends GitServiceError {
+  /** Raw conflicted paths, bounded in count; presentation must escape them. */
+  conflictPaths;
+  /** Conflicted paths beyond the retained bound (reported, never silent). */
+  omittedConflictPaths;
+  constructor(message, conflictPaths, omittedConflictPaths, options) {
+    super("GIT_MERGE_CONFLICTED", message, {
+      ...options?.cause === void 0 ? {} : { cause: options.cause },
+      details: {
+        conflictedPaths: conflictPaths.length + omittedConflictPaths
+      }
+    });
+    this.name = "GitMergeConflictError";
+    this.conflictPaths = conflictPaths;
+    this.omittedConflictPaths = omittedConflictPaths;
+  }
+};
+function boundedDetailText(text, maxLength = 400) {
+  const trimmed = text.trim();
+  if (trimmed.length <= maxLength) return trimmed;
+  return `${trimmed.slice(0, maxLength)}\u2026 [truncated]`;
+}
+export {
+  GitMergeConflictError,
+  GitServiceError,
+  GitWorktreeIncompleteError,
+  boundedDetailText,
+  isGitServiceError
+};

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

@@ -0,0 +1,286 @@
+// packages/git/src/fingerprint.ts
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readlink } from "node:fs/promises";
+import path from "node:path";
+import { GitServiceError, isGitServiceError } from "./errors.js";
+import { inspectRepository } from "./repository.js";
+import {
+  READ_ONLY_GIT_FLAGS,
+  parseStatusOutput,
+  sameRepositoryIdentity
+} from "./review.js";
+import {
+  defaultGitRunner,
+  runGitExpectingSuccess
+} from "./runner.js";
+var DEFAULT_STATE_MAX_ENTRIES = 2e3;
+var DEFAULT_STATE_MAX_DURATION_MS = 1e4;
+var DEFAULT_STATE_MAX_CONTENT_BYTES = 64 * 1024 * 1024;
+function positiveBound(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new GitServiceError(
+      "GIT_STATE_TOO_LARGE",
+      `${label} must be a positive safe integer`
+    );
+  }
+  return value;
+}
+function withCaptureDeadline(runner, deadlineMs, now) {
+  return async (args, options = {}) => {
+    const remainingMs = Math.floor(deadlineMs - now());
+    if (remainingMs < 1) {
+      throw new GitServiceError(
+        "GIT_STATE_DEADLINE_EXCEEDED",
+        "The worktree-state capture exceeded its overall time budget"
+      );
+    }
+    const callerLimitMs = options.timeoutMs ?? Number.POSITIVE_INFINITY;
+    try {
+      return await runner(args, {
+        ...options,
+        timeoutMs: Math.min(remainingMs, callerLimitMs)
+      });
+    } catch (error) {
+      if (remainingMs <= callerLimitMs && isGitServiceError(error, "GIT_COMMAND_TERMINATED")) {
+        throw new GitServiceError(
+          "GIT_STATE_DEADLINE_EXCEEDED",
+          "The worktree-state capture exceeded its overall time budget",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  };
+}
+function needsContentHash(entry) {
+  if (entry.record === "untracked" || entry.record === "unmerged") return true;
+  return entry.y !== "." && entry.y !== "D";
+}
+async function hashWorktreeContent(root, paths, maxContentBytes, deadlineMs, now) {
+  const hashes = /* @__PURE__ */ new Map();
+  let consumedBytes = 0;
+  function ensureBudget() {
+    if (now() >= deadlineMs) {
+      throw new GitServiceError(
+        "GIT_STATE_DEADLINE_EXCEEDED",
+        "The worktree-state capture exceeded its overall time budget"
+      );
+    }
+  }
+  function consume(bytes) {
+    consumedBytes += bytes;
+    if (consumedBytes > maxContentBytes) {
+      throw new GitServiceError(
+        "GIT_STATE_TOO_LARGE",
+        `Changed worktree content exceeds the ${maxContentBytes}-byte fingerprint bound`,
+        { details: { maxContentBytes } }
+      );
+    }
+  }
+  function sameFileIdentity(before, after) {
+    return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs && before.mode === after.mode;
+  }
+  for (const entryPath of paths) {
+    ensureBudget();
+    const absolutePath = path.join(root, ...entryPath.split("/"));
+    let before;
+    try {
+      before = await lstat(absolutePath, { bigint: true });
+    } catch (error) {
+      throw new GitServiceError(
+        "GIT_STATE_CHANGED_DURING_CAPTURE",
+        "A changed worktree path disappeared while its state was being captured",
+        { cause: error }
+      );
+    }
+    if (before.isSymbolicLink()) {
+      let target;
+      let after;
+      try {
+        target = await readlink(absolutePath, { encoding: "buffer" });
+        after = await lstat(absolutePath, { bigint: true });
+      } catch (error) {
+        throw new GitServiceError(
+          "GIT_STATE_CHANGED_DURING_CAPTURE",
+          "A symlink changed while its state was being captured",
+          { cause: error }
+        );
+      }
+      if (!sameFileIdentity(before, after)) {
+        throw new GitServiceError(
+          "GIT_STATE_CHANGED_DURING_CAPTURE",
+          "A symlink changed while its state was being captured"
+        );
+      }
+      consume(target.byteLength);
+      hashes.set(
+        entryPath,
+        `symlink-sha256:${createHash("sha256").update(target).digest("hex")}`
+      );
+      continue;
+    }
+    if (!before.isFile()) {
+      throw new GitServiceError(
+        "GIT_STATE_UNFINGERPRINTABLE",
+        "A changed worktree path is a directory or special file that Webdesk cannot fingerprint safely"
+      );
+    }
+    if (before.size > BigInt(maxContentBytes - consumedBytes)) {
+      throw new GitServiceError(
+        "GIT_STATE_TOO_LARGE",
+        `Changed worktree content exceeds the ${maxContentBytes}-byte fingerprint bound`,
+        { details: { maxContentBytes } }
+      );
+    }
+    consume(Number(before.size));
+    let handle = null;
+    try {
+      handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const opened = await handle.stat({ bigint: true });
+      if (!opened.isFile() || !sameFileIdentity(before, opened)) {
+        throw new GitServiceError(
+          "GIT_STATE_CHANGED_DURING_CAPTURE",
+          "A worktree file changed before its content could be captured"
+        );
+      }
+      const digest = createHash("sha256");
+      const buffer = Buffer.allocUnsafe(64 * 1024);
+      let bytesReadTotal = 0;
+      while (true) {
+        ensureBudget();
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+        if (bytesRead === 0) break;
+        bytesReadTotal += bytesRead;
+        digest.update(buffer.subarray(0, bytesRead));
+      }
+      const after = await handle.stat({ bigint: true });
+      if (BigInt(bytesReadTotal) !== before.size || !sameFileIdentity(before, after)) {
+        throw new GitServiceError(
+          "GIT_STATE_CHANGED_DURING_CAPTURE",
+          "A worktree file changed while its content was being captured"
+        );
+      }
+      hashes.set(entryPath, `file-sha256:${digest.digest("hex")}`);
+    } catch (error) {
+      if (isGitServiceError(error)) throw error;
+      throw new GitServiceError(
+        "GIT_STATE_CHANGED_DURING_CAPTURE",
+        "A worktree file changed or could not be opened safely while its state was being captured",
+        { cause: error }
+      );
+    } finally {
+      await handle?.close().catch(() => void 0);
+    }
+  }
+  return hashes;
+}
+async function captureWorktreeState(options) {
+  const maxEntries = positiveBound(
+    options.maxEntries ?? DEFAULT_STATE_MAX_ENTRIES,
+    "State entry limit"
+  );
+  const maxDurationMs = positiveBound(
+    options.maxDurationMs ?? DEFAULT_STATE_MAX_DURATION_MS,
+    "State duration limit"
+  );
+  const maxContentBytes = positiveBound(
+    options.maxContentBytes ?? DEFAULT_STATE_MAX_CONTENT_BYTES,
+    "State content-byte limit"
+  );
+  const now = options.now ?? Date.now;
+  const deadlineMs = now() + maxDurationMs;
+  const runner = withCaptureDeadline(
+    options.runner ?? defaultGitRunner,
+    deadlineMs,
+    now
+  );
+  const worktree = await inspectRepository(options.worktreePath, { runner });
+  const status = await runGitExpectingSuccess(
+    runner,
+    [
+      ...READ_ONLY_GIT_FLAGS,
+      "status",
+      "--porcelain=v2",
+      "-z",
+      "--untracked-files=all"
+    ],
+    { cwd: worktree.root }
+  );
+  const entries = parseStatusOutput(status.stdout);
+  if (entries.length > maxEntries) {
+    throw new GitServiceError(
+      "GIT_STATE_TOO_LARGE",
+      `The worktree has ${entries.length} changed or untracked entries, more than the ${maxEntries}-entry fingerprint bound`,
+      { details: { entries: entries.length, maxEntries } }
+    );
+  }
+  entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  if (entries.some((entry) => entry.sub.startsWith("S"))) {
+    throw new GitServiceError(
+      "GIT_STATE_UNFINGERPRINTABLE",
+      "Dirty or moved submodules cannot be fingerprinted safely yet"
+    );
+  }
+  const contentPaths = entries.filter(needsContentHash).map((entry) => entry.path);
+  const contentHashes = await hashWorktreeContent(
+    worktree.root,
+    contentPaths,
+    maxContentBytes,
+    deadlineMs,
+    now
+  );
+  const digest = createHash("sha256");
+  digest.update("pita-worktree-state-v1");
+  digest.update("\0");
+  digest.update(worktree.root);
+  digest.update("\0");
+  digest.update(worktree.commonDir);
+  digest.update("\0");
+  digest.update(worktree.branch ?? "
detached");
+  digest.update("\0");
+  digest.update(worktree.headCommit);
+  digest.update("\0\0");
+  digest.update(status.stdout);
+  digest.update("\0\0");
+  for (const entryPath of contentPaths) {
+    const contentHash = contentHashes.get(entryPath);
+    if (contentHash === void 0) {
+      throw new GitServiceError(
+        "GIT_STATE_CHANGED_DURING_CAPTURE",
+        "A changed worktree path was not captured consistently"
+      );
+    }
+    digest.update(entryPath);
+    digest.update("\0");
+    digest.update(contentHash);
+    digest.update("\0");
+  }
+  const stateFingerprint = digest.digest("hex");
+  const verified = await inspectRepository(worktree.root, { runner });
+  if (!sameRepositoryIdentity(worktree, verified)) {
+    throw new GitServiceError(
+      "GIT_REPOSITORY_CHANGED_DURING_CAPTURE",
+      "The worktree branch or HEAD changed while its state was being captured; retry to observe the new state",
+      {
+        details: {
+          beforeHead: worktree.headCommit,
+          afterHead: verified.headCommit,
+          beforeBranch: worktree.branch,
+          afterBranch: verified.branch
+        }
+      }
+    );
+  }
+  return {
+    worktree,
+    stateFingerprint,
+    statusEntryCount: entries.length
+  };
+}
+export {
+  DEFAULT_STATE_MAX_CONTENT_BYTES,
+  DEFAULT_STATE_MAX_DURATION_MS,
+  DEFAULT_STATE_MAX_ENTRIES,
+  captureWorktreeState
+};

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

@@ -0,0 +1,123 @@
+// packages/git/src/index.ts
+import {
+  GitMergeConflictError,
+  GitServiceError,
+  GitWorktreeIncompleteError,
+  isGitServiceError
+} from "./errors.js";
+import {
+  createDefaultGitRunner
+} from "./runner.js";
+import {
+  inspectRepository
+} from "./repository.js";
+import {
+  DEFAULT_REVIEW_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_REVIEW_MAX_DURATION_MS,
+  DEFAULT_REVIEW_MAX_FILES,
+  DEFAULT_REVIEW_MAX_TOTAL_DIFF_CHARS,
+  reviewWorktree
+} from "./review.js";
+import {
+  DEFAULT_STATE_MAX_DURATION_MS,
+  DEFAULT_STATE_MAX_CONTENT_BYTES,
+  DEFAULT_STATE_MAX_ENTRIES,
+  captureWorktreeState
+} from "./fingerprint.js";
+import {
+  DEFAULT_VALIDATION_MAX_OUTPUT_CHARS,
+  DEFAULT_VALIDATION_TIMEOUT_MS,
+  MAX_VALIDATION_COMMAND_CHARS,
+  MAX_VALIDATION_TIMEOUT_MS,
+  ValidationRunnerError,
+  isValidationRunnerError,
+  startValidationRun
+} from "./validation.js";
+import {
+  createTaskWorktree,
+  preflightTaskWorktree
+} from "./worktree.js";
+import {
+  DEFAULT_COMMIT_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_COMMIT_MAX_DURATION_MS,
+  DEFAULT_COMMIT_MAX_ENTRIES,
+  DEFAULT_COMMIT_MAX_FILES,
+  DEFAULT_COMMIT_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_COMMIT_SIGNING_TIMEOUT_MS,
+  MAX_COMMIT_MESSAGE_CHARS,
+  commitPreparedTree,
+  prepareCommitTree
+} from "./commit.js";
+import {
+  DEFAULT_MERGE_MAX_COMMIT_SUBJECTS,
+  DEFAULT_MERGE_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_MERGE_MAX_DURATION_MS,
+  DEFAULT_MERGE_MAX_ENTRIES,
+  DEFAULT_MERGE_MAX_FILES,
+  DEFAULT_MERGE_MAX_GUARD_PATH_CHARS,
+  DEFAULT_MERGE_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_MERGE_GUARD_TIMEOUT_MS,
+  DEFAULT_MERGE_SIGNING_TIMEOUT_MS,
+  MAX_MERGE_CONFLICT_PATHS,
+  MAX_MERGE_MESSAGE_CHARS,
+  MIN_MERGE_GIT_VERSION,
+  assertMergeTargetPathsUnoccupied,
+  ensureMergeCapableGit,
+  isMergeCommitAncestor,
+  prepareMergeTree,
+  publishMerge,
+  syncTargetCheckout
+} from "./merge.js";
+export {
+  DEFAULT_COMMIT_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_COMMIT_MAX_DURATION_MS,
+  DEFAULT_COMMIT_MAX_ENTRIES,
+  DEFAULT_COMMIT_MAX_FILES,
+  DEFAULT_COMMIT_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_COMMIT_SIGNING_TIMEOUT_MS,
+  DEFAULT_MERGE_GUARD_TIMEOUT_MS,
+  DEFAULT_MERGE_MAX_COMMIT_SUBJECTS,
+  DEFAULT_MERGE_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_MERGE_MAX_DURATION_MS,
+  DEFAULT_MERGE_MAX_ENTRIES,
+  DEFAULT_MERGE_MAX_FILES,
+  DEFAULT_MERGE_MAX_GUARD_PATH_CHARS,
+  DEFAULT_MERGE_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_MERGE_SIGNING_TIMEOUT_MS,
+  DEFAULT_REVIEW_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_REVIEW_MAX_DURATION_MS,
+  DEFAULT_REVIEW_MAX_FILES,
+  DEFAULT_REVIEW_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_STATE_MAX_CONTENT_BYTES,
+  DEFAULT_STATE_MAX_DURATION_MS,
+  DEFAULT_STATE_MAX_ENTRIES,
+  DEFAULT_VALIDATION_MAX_OUTPUT_CHARS,
+  DEFAULT_VALIDATION_TIMEOUT_MS,
+  GitMergeConflictError,
+  GitServiceError,
+  GitWorktreeIncompleteError,
+  MAX_COMMIT_MESSAGE_CHARS,
+  MAX_MERGE_CONFLICT_PATHS,
+  MAX_MERGE_MESSAGE_CHARS,
+  MAX_VALIDATION_COMMAND_CHARS,
+  MAX_VALIDATION_TIMEOUT_MS,
+  MIN_MERGE_GIT_VERSION,
+  ValidationRunnerError,
+  assertMergeTargetPathsUnoccupied,
+  captureWorktreeState,
+  commitPreparedTree,
+  createDefaultGitRunner,
+  createTaskWorktree,
+  ensureMergeCapableGit,
+  inspectRepository,
+  isGitServiceError,
+  isMergeCommitAncestor,
+  isValidationRunnerError,
+  preflightTaskWorktree,
+  prepareCommitTree,
+  prepareMergeTree,
+  publishMerge,
+  reviewWorktree,
+  startValidationRun,
+  syncTargetCheckout
+};