---
docgen:
  source: npm/scripts/lib/assert-project-root.mjs
  crc: 3ad7981a
---

# assert-project-root.mjs

## Огляд

Файл забезпечує захист від непередбачуваної поведінки при запуску `npx @nitra/cursor` з піддиректорій git-репозиторію. Він гарантує, що процес синхронізації та встановлення артефактів виконується лише з кореневої директорії проєкту, запобігаючи розповсюдженню конфігураційних файлів у невідповідні місця. Це забезпечує узгодженість та передбачуваність процесу налаштування проєкту.

## Поведінка

gitToplevel: Визначає реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає `null`, якщо `git` недоступний або не вдалося визначити корінь.
safeRealpath: Повертає реальний шлях вказаного каталогу, ігноруючи символічні посилання. Якщо шлях не існує, повертає вихідний шлях без змін.
assertCwdIsProjectRoot: Перевіряє, чи поточний робочий каталог є коренем git-репозиторію. Якщо так, функція не робить нічого. Якщо каталог знаходиться всередині git-репозиторію, але не є його коренем, викидає помилку, що інформує про необхідність перейти в корінь репозиторію.

## Публічний API

- gitToplevel — Отримує реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає шлях або `null`, якщо `dir` не є коренем репозиторію або `git` недоступний.
- assertCwdIsProjectRoot — Перевіряє, чи `dir` є коренем git-репозиторію. Якщо `dir` є піддиректорією репозиторію або знаходиться поза репозиторієм (без визначення `toplevel`), то функція пропускає операцію без помилки.

## Гарантії поведінки

- При запуску `npx @nitra/cursor` з кореня будь-якого git-репозиторію, виконується синхронізація проєкту.
- При запуску `npx @nitra/cursor` з піддиректорії git-репозиторію, `cwd` встановлюється на корінь git-репозиторію.
- Синхронізація проєкту включає створення та запуск сценаріїв для `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, `.n-cursor.json`, `.gitignore`.
- Синхронізація проєкту включає запуск `bun install`.
- При невдачі синхронізації повертається `false` або `null`.
- Немає кешування.
- Не перехоплює винятки.
- Функція `gitToplevel` забезпечує доступ до кореня git-репозиторію.
- Функція `assertCwdIsProjectRoot` перевіряє, чи поточний `cwd` є коренем git-репозиторію.
