Function fetchSkillFiles

src/lib/git-client.ts:127–196

(params: {
  url: string;
  ref: string;
  skillsPath: string;
  logger?: Logger;
})

 * `git clone --branch` does not accept raw SHAs.
 */
export async function fetchSkillFiles(params: {
  url: string;
  ref: string;
  skillsPath: string;
  logger?: Logger;
}): Promise<Array<{ relativePath: string; content: string; size: number }>> {
  const { url, ref, skillsPath, logger } = params;
  validateGitUrl(url, { logger });
  validateRef(ref);
  if (skillsPath.split(/[/\\]/).includes("..") || isAbsolute(skillsPath)) {
    throw new GitClientError(
      `Invalid skillsPath "${skillsPath}": must be a relative path without ".."`,
    );
  }
  const ctrl = findControlCharacter(skillsPath);
  if (ctrl) {
    throw new GitClientError(
      `skillsPath contains control character ${ctrl.hex} at position ${ctrl.position}`,
    );
  }
  await checkGitAvailable();
  const tmpDir = await createTempDirectory("rulesync-git-");
  // Treat empty/"." paths as the repository root. Cone-mode sparse-checkout
  // with such patterns only restores the top-level files (it intentionally
  // excludes any subdirectory), so we must check out the entire working tree
  // instead. Otherwise repositories whose skills live directly at the root
  // (e.g. `<repo>/<skill-name>/SKILL.md` without a `skills/` container)
  // would only yield root-level files like README.md.
  // Normalize first so variants like "./.", ".//", or Windows ".\\" are also
  // recognized as the root and don't fall back to the (buggy) sparse-checkout path.
  const normalizedSkillsPath = posix.normalize(skillsPath.replace(/\\/g, "/")).replace(/\/+$/, "");
  const isRootPath = normalizedSkillsPath === "" || normalizedSkillsPath === ".";
  try {
    await execFileAsync(
      "git",
      [
        "clone",
        "--depth",
        "1",
        "--branch",
        ref,
        "--no-checkout",
        "--filter=blob:none",
        "--",
        url,
        tmpDir,
      ],
      { timeout: GIT_TIMEOUT_MS },
    );
    if (isRootPath) {
      // Disable sparse-checkout and restore the full tree.
      await execFileAsync("git", ["-C", tmpDir, "sparse-checkout", "disable"], {
        timeout: GIT_TIMEOUT_MS,
      });
    } else {
      await execFileAsync("git", ["-C", tmpDir, "sparse-checkout", "set", "--", skillsPath], {
        timeout: GIT_TIMEOUT_MS,
      });