me2lon 0.0.0-stage → 0.1.0

package/src/workspace-source.ts

@@ -0,0 +1,526 @@
+import { createHash } from "node:crypto";
+import { lstat, open, readFile, readlink, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { spawn } from "node:child_process";
+
+import { Me2lonClientError } from "./errors.js";
+import {
+  LOCAL_SOURCE_LIMITS,
+  SOURCE_SCHEMA_VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  type WorkspaceSnapshot,
+  type BoundWorkspace,
+  type SourceChange,
+  type SourceLimits,
+  type WorkspaceSource,
+} from "./types.js";
+
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+const exactCommitPattern = /^[0-9a-f]{40}$/u;
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+type TreeEntry = {
+  mode: string;
+  type: string;
+  oid: string;
+}
+
+async function runGit(root: string, args: string[]): Promise<Buffer> {
+  return await new Promise<Buffer>((resolvePromise, reject) => {
+    const child = spawn("git", ["-C", root, ...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" },
+      windowsHide: true,
+    });
+    const stdout: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > MAX_GIT_OUTPUT_BYTES) {
+        child.kill();
+        reject(
+          new Me2lonClientError(
+            "ME2LON_GIT_OUTPUT_LIMIT",
+            "Git produced more repository metadata than the Me2lon client accepts.",
+          ),
+        );
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes > 64 * 1024) {
+        child.kill();
+      }
+    });
+    child.once("error", (error) => {
+      reject(
+        new Me2lonClientError(
+          "ME2LON_GIT_UNAVAILABLE",
+          "The Me2lon client could not run Git.",
+          { cause: error },
+        ),
+      );
+    });
+    child.once("close", (code) => {
+      if (code !== 0) {
+        reject(
+          new Me2lonClientError(
+            "ME2LON_GIT_FAILURE",
+            "Git could not inspect the bound workspace and base commit.",
+          ),
+        );
+        return;
+      }
+      resolvePromise(Buffer.concat(stdout));
+    });
+  });
+}
+
+export async function discoverWorkspace(directory: string): Promise<{ root: string; head: string; branch: string | null }> {
+  const root = await realpath(decodeUtf8(await runGit(resolve(directory), ["rev-parse", "--show-toplevel"]), "Git root").trim());
+  const head = decodeUtf8(await runGit(root, ["rev-parse", "--verify", "HEAD^{commit}"]), "Git HEAD").trim();
+  if (!exactCommitPattern.test(head)) throw new Me2lonClientError("ME2LON_BASE_COMMIT_INVALID", "A local Git repository with an initial commit is required.");
+  const branch = decodeUtf8(await runGit(root, ["rev-parse", "--abbrev-ref", "HEAD"]), "Git branch").trim();
+  return { root, head, branch: branch === "HEAD" ? null : branch };
+}
+
+async function snapshotFile(root: string, path: string, maximumBytes: number): Promise<Buffer> {
+  const absolute = pathInsideRoot(root, path);
+  let parent = root;
+  for (const part of path.split("/")) {
+    parent = resolve(parent, part);
+    if ((await lstat(parent)).isSymbolicLink()) {
+      throw new Me2lonClientError("ME2LON_SOURCE_SYMLINK_UNSUPPORTED", `Symbolic link ${path} cannot be uploaded in a full snapshot.`);
+    }
+  }
+  if (!(await lstat(absolute)).isFile()) throw new Me2lonClientError("ME2LON_SOURCE_KIND_UNSUPPORTED", `Path ${path} is not a regular file; submodules and special files are unsupported.`);
+  const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || before.size > maximumBytes) throw new Me2lonClientError("ME2LON_SOURCE_FILE_LIMIT", `File ${path} is unsupported or exceeds the upload limit.`);
+    const buffer = Buffer.alloc(maximumBytes + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length > maximumBytes) throw new Me2lonClientError("ME2LON_SOURCE_FILE_LIMIT", `File ${path} exceeds the upload limit.`);
+    const bytes = buffer.subarray(0, length);
+    const after = await handle.stat();
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs ||
+      await realpath(absolute) !== absolute) {
+      throw new Me2lonClientError("ME2LON_WORKSPACE_CHANGED_DURING_READ", "The workspace changed during capture; retry the check.");
+    }
+    return bytes;
+  } finally { await handle.close(); }
+}
+
+/** Capture every supported Git-visible file, and verify the complete capture twice. */
+export async function buildWorkspaceSnapshot(workspace: BoundWorkspace, limits: SourceLimits = LOCAL_SOURCE_LIMITS): Promise<WorkspaceSnapshot> {
+  const before = await discoverWorkspace(workspace.root);
+  if (before.root !== workspace.root) throw new Me2lonClientError("ME2LON_WORKSPACE_NOT_ROOT", "The bound Git root changed.");
+  const visible = await gitVisiblePaths(before.root);
+  const flags = await trackedPathFlags(before.root);
+  assertCompleteWorktree(flags);
+  const paths = [...await currentExistingPaths(before.root, visible)].sort(comparePaths);
+  checkLimits(paths.length, 0, 0, limits);
+  const files: WorkspaceSnapshot["files"] = [];
+  const captured = new Map<string, Buffer>();
+  let totalReplacementBytes = 0;
+  for (const path of paths) {
+    const bytes = await snapshotFile(before.root, path, limits.maxFileBytes);
+    totalReplacementBytes += bytes.length;
+    checkLimits(files.length + 1, bytes.length, totalReplacementBytes, limits);
+    const content = decodeUtf8(bytes, `File ${path}`);
+    if (content.includes("\0")) throw new Me2lonClientError("ME2LON_SOURCE_NOT_UTF8", `File ${path} contains NUL bytes and cannot be uploaded.`);
+    files.push({ path, content }); captured.set(path, bytes);
+  }
+  for (const [path, bytes] of captured) {
+    if (!bytes.equals(await snapshotFile(before.root, path, limits.maxFileBytes))) {
+      throw new Me2lonClientError("ME2LON_WORKSPACE_CHANGED_DURING_READ", "The workspace changed during capture; retry the check.");
+    }
+  }
+  const after = await discoverWorkspace(before.root);
+  if (before.head !== after.head || before.branch !== after.branch ||
+    !visible.equals(await gitVisiblePaths(before.root)) || !flags.equals(await trackedPathFlags(before.root))) {
+    throw new Me2lonClientError("ME2LON_WORKSPACE_CHANGED_DURING_READ", "Git changed during capture; retry the check.");
+  }
+  if (files.length === 0) throw new Me2lonClientError("ME2LON_SOURCE_EMPTY", "The project has no files to upload.");
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION, baseCommitSha: before.head, branchLabel: before.branch, files,
+    totalReplacementBytes,
+    digest: `sha256:${createHash("sha256").update(JSON.stringify({ head: before.head, files })).digest("hex")}`,
+  };
+}
+
+function decodeUtf8(bytes: Buffer, context: string): string {
+  try {
+    return utf8Decoder.decode(bytes);
+  } catch (error) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_NOT_UTF8",
+      `${context} is not valid UTF-8 and cannot be represented by ${SOURCE_SCHEMA_VERSION}.`,
+      { cause: error },
+    );
+  }
+}
+
+function parseNullDelimited(bytes: Buffer, context: string): string[] {
+  const decoded = decodeUtf8(bytes, context);
+  const values = decoded.split("\0");
+  if (values.at(-1) === "") {
+    values.pop();
+  }
+  return values;
+}
+
+function validateGitPath(path: string): void {
+  if (
+    path === "" ||
+    path.includes("\0") ||
+    isAbsolute(path) ||
+    path.split("/").some((part) => part === "..") ||
+    path === ".git" ||
+    path.startsWith(".git/")
+  ) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_PATH_INVALID",
+      "Git reported a path that cannot be uploaded safely.",
+    );
+  }
+}
+
+function pathInsideRoot(root: string, gitPath: string): string {
+  validateGitPath(gitPath);
+  const absolutePath = resolve(root, ...gitPath.split("/"));
+  const fromRoot = relative(root, absolutePath);
+  if (fromRoot.startsWith(`..${sep}`) || fromRoot === ".." || isAbsolute(fromRoot)) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_PATH_INVALID",
+      "Git reported a path outside the bound workspace.",
+    );
+  }
+  return absolutePath;
+}
+
+function comparePaths(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+
+async function baseTree(
+  workspace: BoundWorkspace,
+): Promise<Map<string, TreeEntry>> {
+  const raw = await runGit(workspace.root, [
+    "ls-tree",
+    "-r",
+    "-z",
+    "--full-tree",
+    workspace.baseCommitSha,
+  ]);
+  const entries = new Map<string, TreeEntry>();
+  for (const record of parseNullDelimited(raw, "A Git tree path")) {
+    const tab = record.indexOf("\t");
+    if (tab === -1) {
+      throw new Me2lonClientError(
+        "ME2LON_GIT_METADATA_INVALID",
+        "Git returned an invalid base-tree record.",
+      );
+    }
+    const metadata = record.slice(0, tab).split(" ");
+    const path = record.slice(tab + 1);
+    validateGitPath(path);
+    const [mode, type, oid] = metadata;
+    if (!mode || !type || !oid) {
+      throw new Me2lonClientError(
+        "ME2LON_GIT_METADATA_INVALID",
+        "Git returned incomplete base-tree metadata.",
+      );
+    }
+    entries.set(path, { mode, type, oid });
+  }
+  return entries;
+}
+
+async function gitVisiblePaths(root: string): Promise<Buffer> {
+  return await runGit(root, [
+    "ls-files",
+    "-z",
+    "--cached",
+    "--others",
+    "--exclude-standard",
+  ]);
+}
+
+async function trackedPathFlags(root: string): Promise<Buffer> {
+  return await runGit(root, ["ls-files", "-v", "-z"]);
+}
+
+function assertCompleteWorktree(raw: Buffer): void {
+  for (const record of parseNullDelimited(raw, "A Git tracked-path flag")) {
+    const tag = record.at(0);
+    if (tag === "S" || (tag !== undefined && /^[a-z]$/u.test(tag))) {
+      throw new Me2lonClientError(
+        "ME2LON_INCOMPLETE_WORKTREE",
+        "The bound repository uses skip-worktree or assume-unchanged entries, so Me2lon cannot construct a complete source revision.",
+      );
+    }
+  }
+}
+
+async function changedPaths(
+  workspace: BoundWorkspace,
+): Promise<Buffer> {
+  return await runGit(workspace.root, [
+    "diff",
+    "--name-only",
+    "-z",
+    "--no-renames",
+    "--no-ext-diff",
+    "--no-textconv",
+    workspace.baseCommitSha,
+    "--",
+  ]);
+}
+
+async function currentExistingPaths(root: string, raw: Buffer): Promise<Set<string>> {
+  const result = new Set<string>();
+  for (const path of parseNullDelimited(raw, "A Git worktree path")) {
+    validateGitPath(path);
+    const absolutePath = pathInsideRoot(root, path);
+    try {
+      await lstat(absolutePath);
+      result.add(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  return result;
+}
+
+async function readBaseBlob(root: string, oid: string): Promise<Buffer> {
+  return await runGit(root, ["cat-file", "blob", oid]);
+}
+
+function checkLimits(
+  changes: number,
+  fileBytes: number,
+  totalBytes: number,
+  limits: SourceLimits,
+): void {
+  if (changes > limits.maxChanges) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_CHANGE_LIMIT",
+      `The workspace revision exceeds the ${limits.maxChanges}-change client limit.`,
+    );
+  }
+  if (fileBytes > limits.maxFileBytes) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_FILE_LIMIT",
+      `A replacement exceeds the ${limits.maxFileBytes}-byte client limit.`,
+    );
+  }
+  if (totalBytes > limits.maxTotalBytes) {
+    throw new Me2lonClientError(
+      "ME2LON_SOURCE_TOTAL_LIMIT",
+      `The workspace revision exceeds the ${limits.maxTotalBytes}-byte aggregate client limit.`,
+    );
+  }
+}
+
+export async function bindWorkspace(
+  requestedRoot: string,
+  repositoryId: string,
+  requestedBaseCommit: string,
+): Promise<BoundWorkspace> {
+  if (!repositoryId.trim()) {
+    throw new Me2lonClientError(
+      "ME2LON_REPOSITORY_REQUIRED",
+      "A repository id is required.",
+    );
+  }
+  if (!exactCommitPattern.test(requestedBaseCommit)) {
+    throw new Me2lonClientError(
+      "ME2LON_BASE_COMMIT_NOT_EXACT",
+      "The base commit must be a full 40-character hexadecimal Git commit id, not a branch or abbreviated revision.",
+    );
+  }
+
+  const root = await realpath(resolve(requestedRoot));
+  const reportedRoot = decodeUtf8(
+    await runGit(root, ["rev-parse", "--show-toplevel"]),
+    "The Git workspace root",
+  ).trim();
+  const canonicalRoot = await realpath(reportedRoot);
+  if (canonicalRoot !== root) {
+    throw new Me2lonClientError(
+      "ME2LON_WORKSPACE_NOT_ROOT",
+      "The MCP workspace must be bound to the Git repository root, not a parent or subdirectory.",
+    );
+  }
+
+  const canonicalCommit = decodeUtf8(
+    await runGit(root, [
+      "rev-parse",
+      "--verify",
+      `${requestedBaseCommit}^{commit}`,
+    ]),
+    "The Git base commit",
+  ).trim();
+  if (!exactCommitPattern.test(canonicalCommit)) {
+    throw new Me2lonClientError(
+      "ME2LON_BASE_COMMIT_INVALID",
+      "Git did not resolve the requested object to an exact commit id.",
+    );
+  }
+  return {
+    root,
+    repositoryId: repositoryId.trim(),
+    baseCommitSha: canonicalCommit,
+  };
+}
+
+export async function buildWorkspaceSource(
+  workspace: BoundWorkspace,
+  limits: SourceLimits = LOCAL_SOURCE_LIMITS,
+): Promise<WorkspaceSource> {
+  const [tree, visibleBeforeRaw, changedBeforeRaw, pathFlagsRaw] = await Promise.all([
+    baseTree(workspace),
+    gitVisiblePaths(workspace.root),
+    changedPaths(workspace),
+    trackedPathFlags(workspace.root),
+  ]);
+  assertCompleteWorktree(pathFlagsRaw);
+  const visible = await currentExistingPaths(workspace.root, visibleBeforeRaw);
+  const candidatePaths = new Set(
+    parseNullDelimited(changedBeforeRaw, "A changed Git path"),
+  );
+  for (const path of visible) {
+    if (!tree.has(path)) {
+      candidatePaths.add(path);
+    }
+  }
+  for (const path of tree.keys()) {
+    if (!visible.has(path)) {
+      candidatePaths.add(path);
+    }
+  }
+
+  const changes: SourceChange[] = [];
+  let replacementCount = 0;
+  let deletionCount = 0;
+  let totalReplacementBytes = 0;
+
+  for (const path of [...candidatePaths].sort(comparePaths)) {
+    validateGitPath(path);
+    const base = tree.get(path);
+    if (!visible.has(path)) {
+      if (base) {
+        changes.push({ operation: "delete", path });
+        deletionCount += 1;
+        checkLimits(changes.length, 0, totalReplacementBytes, limits);
+      }
+      continue;
+    }
+
+    const absolutePath = pathInsideRoot(workspace.root, path);
+    const before = await lstat(absolutePath);
+    if (before.isSymbolicLink()) {
+      if (!base || base.mode !== "120000" || base.type !== "blob") {
+        throw new Me2lonClientError(
+          "ME2LON_SOURCE_SYMLINK_UNSUPPORTED",
+          `Changed symbolic link ${path} cannot be represented by ${SOURCE_SCHEMA_VERSION}.`,
+        );
+      }
+      const [target, original] = await Promise.all([
+        readlink(absolutePath, "utf8"),
+        readBaseBlob(workspace.root, base.oid),
+      ]);
+      if (!Buffer.from(target, "utf8").equals(original)) {
+        throw new Me2lonClientError(
+          "ME2LON_SOURCE_SYMLINK_UNSUPPORTED",
+          `Changed symbolic link ${path} cannot be represented by ${SOURCE_SCHEMA_VERSION}.`,
+        );
+      }
+      continue;
+    }
+    if (base?.type === "commit") {
+      throw new Me2lonClientError(
+        "ME2LON_SOURCE_SUBMODULE_UNSUPPORTED",
+        `Changed submodule ${path} cannot be represented by ${SOURCE_SCHEMA_VERSION}.`,
+      );
+    }
+    if (!before.isFile()) {
+      throw new Me2lonClientError(
+        "ME2LON_SOURCE_KIND_UNSUPPORTED",
+        `Changed path ${path} is not a regular UTF-8 file.`,
+      );
+    }
+
+    checkLimits(changes.length, before.size, totalReplacementBytes, limits);
+    const bytes = await readFile(absolutePath);
+    const after = await lstat(absolutePath);
+    if (
+      before.size !== after.size ||
+      before.mtimeMs !== after.mtimeMs ||
+      before.ctimeMs !== after.ctimeMs
+    ) {
+      throw new Me2lonClientError(
+        "ME2LON_WORKSPACE_CHANGED_DURING_READ",
+        "The workspace changed while Me2lon was preparing its revision; retry the check.",
+      );
+    }
+    checkLimits(
+      changes.length + 1,
+      bytes.length,
+      totalReplacementBytes + bytes.length,
+      limits,
+    );
+    if (base?.type === "blob") {
+      const original = await readBaseBlob(workspace.root, base.oid);
+      if (bytes.equals(original)) {
+        continue;
+      }
+    }
+    const content = decodeUtf8(bytes, `Replacement ${path}`);
+    changes.push({ operation: "replace", path, content });
+    replacementCount += 1;
+    totalReplacementBytes += bytes.length;
+  }
+
+  const [visibleAfterRaw, changedAfterRaw] = await Promise.all([
+    gitVisiblePaths(workspace.root),
+    changedPaths(workspace),
+  ]);
+  if (
+    !visibleBeforeRaw.equals(visibleAfterRaw) ||
+    !changedBeforeRaw.equals(changedAfterRaw)
+  ) {
+    throw new Me2lonClientError(
+      "ME2LON_WORKSPACE_CHANGED_DURING_READ",
+      "The workspace changed while Me2lon was preparing its revision; retry the check.",
+    );
+  }
+
+  const digestPayload = JSON.stringify({
+    schemaVersion: SOURCE_SCHEMA_VERSION,
+    baseCommitSha: workspace.baseCommitSha,
+    changes,
+  });
+  return {
+    schemaVersion: SOURCE_SCHEMA_VERSION,
+    baseCommitSha: workspace.baseCommitSha,
+    changes,
+    digest: `sha256:${createHash("sha256").update(digestPayload).digest("hex")}`,
+    replacementCount,
+    deletionCount,
+    totalReplacementBytes,
+  };
+}

package/tsconfig.build.json

@@ -0,0 +1,18 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "noEmit": false
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "test/**/*.ts",
+    "src/mcp.ts"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}