@nitra/cursor 1.13.76 → 1.13.83

package/rules/vue/{fix → js}/packages/check.mjs

@@ -15,7 +15,7 @@
  * натомість використовуй `mode` з `defineConfig(({ mode }) => ...)`.
  *
  * Заборонені явні value-імпорти з `vue` у джерелах пакета — сканування `.vue`/`.ts`/`.js` тощо
- * через **oxc-parser** (`module.staticImports`; див. `utils/vue-forbidden-imports.mjs`); дозволені лише type-only та side-effect `import 'vue'`.
+ * через **oxc-parser** (`module.staticImports`; див. `./vue-forbidden-imports.mjs`); дозволені лише type-only та side-effect `import 'vue'`.
  *
  * Окремо в `.vue` SFC заборонено імпорти Node-нативних модулів — `node:*` префікс або bare-ім’я
  * вбудованого модуля Node (`fs`, `path`, `timers/promises` тощо). Vue SFC виконується у браузері,
@@ -31,7 +31,7 @@ import {
   findForbiddenVueImportsInSourceFile,
   isVueImportScanSourceFile,
   shouldSkipFileForVueImportScan
-} from '../../../../scripts/utils/vue-forbidden-imports.mjs'
+} from './vue-forbidden-imports.mjs'
 import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
 import { walkDir } from '../../../../scripts/utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from '../../../../scripts/utils/workspaces.mjs'

package/rules/vue/vue.mdc

@@ -341,4 +341,4 @@ import path from 'node:path'
 
 ## Перевірка
 
-`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/scripts/utils/vue-forbidden-imports.mjs`).
+`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/js/packages/vue-forbidden-imports.mjs`).

package/scripts/auto-rules.mjs

@@ -16,13 +16,13 @@ import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 
-import { textHasBunSqlImport } from './utils/bun-sql-scan.mjs'
+import { textHasBunSqlImport } from '../rules/js-bun-db/js/safety/bun-sql-scan.mjs'
 import {
   isGqlScanSourceFile,
   shouldSkipFileForGqlScan,
   sourceFileHasGqlTaggedTemplate
-} from './utils/graphql-gql-scan.mjs'
-import { contentForVueImportScan } from './utils/vue-forbidden-imports.mjs'
+} from '../rules/graphql/js/tooling/graphql-gql-scan.mjs'
+import { contentForVueImportScan } from '../rules/vue/js/packages/vue-forbidden-imports.mjs'
 
 /** Порядок автододавання правил відповідно до `rules/<rule>/auto.md`. */
 export const AUTO_RULE_ORDER = Object.freeze([

package/scripts/sync-claude-config.mjs

@@ -19,7 +19,7 @@
  * - `.cursor/hooks.json` — **merge**: користувацькі hooks зберігаються; ADR stop
  *   entries додаються, коли правило `adr` увімкнене, і видаляються, коли вимкнене.
  * - `.gitignore` — **merge** (лише з `adr`): дописує відсутні рядки з канонічного
- *   фрагмента `rules/adr/fix/hooks/template/.gitignore.snippet` (`node_modules/`, `dist/`,
+ *   фрагмента `rules/adr/js/hooks/template/.gitignore.snippet` (`node_modules/`, `dist/`,
  *   `*.secret`, логи capture/normalize, `.normalize-state`, `.normalize.lock`); існуючі
  *   рядки не перезаписуються.
  *
@@ -56,7 +56,7 @@ const ADR_HOOK_SCRIPT_NAME = 'capture-decisions.sh'
 const ADR_NORMALIZE_HOOK_SCRIPT_NAME = 'normalize-decisions.sh'
 const TEMPLATE_DIR_NAME = '.claude-template'
 /** Відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета. */
-export const ADR_GITIGNORE_SNIPPET_REL = 'rules/adr/fix/hooks/template/.gitignore.snippet'
+export const ADR_GITIGNORE_SNIPPET_REL = 'rules/adr/js/hooks/template/.gitignore.snippet'
 const GITIGNORE_FILE = '.gitignore'
 const EOL_RE = /\r?\n/u
 

package/scripts/utils/ast-scan-utils.mjs

@@ -5,8 +5,9 @@
  * розпізнавання типових вузлів (функцій, `*.join(...)`),
  * робота з `TemplateLiteral` (текст quasis, контекст SQL-списку).
  *
- * Використовується файлами `bun-sql-scan.mjs`, `mssql-pool-scan.mjs` та іншими сканерами
- * для уникнення дублювання boilerplate.
+ * Використовується сканерами у `rules/<rule>/js/...` (наприклад,
+ * `rules/js-bun-db/js/safety/bun-sql-scan.mjs`, `rules/js-mssql/js/deps/mssql-pool-scan.mjs`,
+ * `rules/js-run/js/runtime/*-scan.mjs`) для уникнення дублювання boilerplate.
  */
 import { parseSync } from 'oxc-parser'
 

package/scripts/utils/discover-checkable-rules.mjs

@@ -1,17 +1,17 @@
 /**
  * Discovery rules для CLI `check`. Шукає правила, для яких є щось «прогонне»:
- *   - JS concerns:   `rules/<id>/fix/<concern>/<check.mjs | check-*.mjs>` — кожен concern окремий вузол.
+ *   - JS concerns:   `rules/<id>/js/<concern>/<check.mjs | check-*.mjs>` — кожен concern окремий вузол.
  *   - Policy concerns: `rules/<id>/policy/<concern>/target.json` — пара з `<concern>.rego`.
  *
- * Каталог `fix/utils/` свідомо пропускається — це хелпери, не концерни.
+ * Каталог `js/utils/` свідомо пропускається — це хелпери, не концерни.
  * Файли `*.test.mjs` фільтруються regex (`^check(?:-.+)?\.mjs$`).
  *
  * Намеренно НЕ парсимо `target.json` тут (це робить runner). Discovery — швидкий скан структури:
  * шляхи + назви, без I/O вмісту.
  *
- * Історичний контекст: до 1.11.12 існувала dual-mode підтримка `js/` (legacy) і `fix/` (новий),
- * де концерн мав поле `rootDir`. Після переїзду всіх 26 правил у `fix/` (CHANGELOG 1.11.10)
- * legacy-канал прибрано (CHANGELOG 1.11.12) — одне джерело правди.
+ * Історичний контекст: convention пройшла еволюцію `js/` (до 1.11.12) → `fix/` (1.11.10–1.13.79)
+ * → знову `js/` (1.13.80+, після появи кореневого `fix.mjs` як entry-point правила, щоб не плутати
+ * з папкою `fix/`). Convention тепер за технологією: `js/` ↔ `policy/`.
  */
 import { existsSync } from 'node:fs'
 import { readdir } from 'node:fs/promises'
@@ -22,7 +22,7 @@ const TEST_SUFFIX = '.test.mjs'
 
 /**
  * @typedef {object} JsConcern
- * @property {string} name імʼя концерну (`<name>` у `fix/<name>/`)
+ * @property {string} name імʼя концерну (`<name>` у `js/<name>/`)
  * @property {string[]} files імена `check*.mjs` у концерні (відсортовані алфавітно)
  */
 
@@ -39,21 +39,21 @@ const TEST_SUFFIX = '.test.mjs'
  */
 
 /**
- * Перелічує JS-концерни одного правила: підкаталоги `fix/<name>/` з принаймні одним `check*.mjs`.
+ * Перелічує JS-концерни одного правила: підкаталоги `js/<name>/` з принаймні одним `check*.mjs`.
  *
- * `fix/utils/` свідомо пропускається — це хелпери, а не концерни.
- * @param {string} fixDir абсолютний шлях `rules/<id>/fix/`
+ * `js/utils/` свідомо пропускається — це хелпери, а не концерни.
+ * @param {string} jsDir абсолютний шлях `rules/<id>/js/`
  * @returns {Promise<JsConcern[]>} концерни в алфавітному порядку
  */
-async function listJsConcerns(fixDir) {
-  if (!existsSync(fixDir)) return []
-  const topLevel = await readdir(fixDir, { withFileTypes: true })
+async function listJsConcerns(jsDir) {
+  if (!existsSync(jsDir)) return []
+  const topLevel = await readdir(jsDir, { withFileTypes: true })
 
   /** @type {JsConcern[]} */
   const concerns = []
   for (const entry of topLevel) {
     if (!entry.isDirectory() || entry.name === 'utils' || entry.name.startsWith('.')) continue
-    const concernDir = join(fixDir, entry.name)
+    const concernDir = join(jsDir, entry.name)
     const dirContents = await readdir(concernDir)
     const files = dirContents
       .filter(n => CHECK_FILENAME_RE.test(n) && !n.endsWith(TEST_SUFFIX))
@@ -86,7 +86,20 @@ async function listPolicyConcerns(policyDir) {
 }
 
 /**
- * Сканує `rules/` і повертає правила, для яких є JS-концерни (у `fix/`) або policy-концерни
+ * Будує `CheckableRule` для одного каталогу правила (без enumeration по `rules/`).
+ * Використовується `runStandardRule` для per-rule entry-point flow.
+ * @param {string} ruleDir абсолютний шлях `rules/<id>/`
+ * @param {string} ruleId id правила (= basename(ruleDir))
+ * @returns {Promise<CheckableRule>} опис правила (jsConcerns + policyConcerns)
+ */
+export async function discoverOneRule(ruleDir, ruleId) {
+  const jsConcerns = await listJsConcerns(join(ruleDir, 'js'))
+  const policyConcerns = await listPolicyConcerns(join(ruleDir, 'policy'))
+  return { id: ruleId, jsConcerns, policyConcerns }
+}
+
+/**
+ * Сканує `rules/` і повертає правила, для яких є JS-концерни (у `js/`) або policy-концерни
  * (у `policy/`). Правила без жодної прогонної частини (тільки `.mdc` + `auto.md`) фільтруються.
  * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
  * @returns {Promise<CheckableRule[]>} відсортовані за id
@@ -99,10 +112,9 @@ export async function discoverCheckableRules(bundledRulesDir) {
   for (const entry of entries) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
     const ruleDir = join(bundledRulesDir, entry.name)
-    const jsConcerns = await listJsConcerns(join(ruleDir, 'fix'))
-    const policyConcerns = await listPolicyConcerns(join(ruleDir, 'policy'))
-    if (jsConcerns.length > 0 || policyConcerns.length > 0) {
-      out.push({ id: entry.name, jsConcerns, policyConcerns })
+    const rule = await discoverOneRule(ruleDir, entry.name)
+    if (rule.jsConcerns.length > 0 || rule.policyConcerns.length > 0) {
+      out.push(rule)
     }
   }
   return out.toSorted((a, b) => a.id.localeCompare(b.id))

package/scripts/utils/list-rule-ids.mjs

@@ -0,0 +1,23 @@
+/**
+ * Перебір `rules/<id>/` директорій з фільтром на наявність `fix.mjs`.
+ * Після атомарної міграції `fix.mjs` обов'язковий у кожному правилі — каталог без нього
+ * пропускається (це not-a-rule або заглушка).
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
+ * @param {string} [filter] id одного правила (через `--rule abie`)
+ * @returns {Promise<string[]>} відсортовані алфавітно id
+ */
+export async function listRuleIds(bundledRulesDir, filter) {
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  const ids = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .map(e => e.name)
+    .filter(id => existsSync(join(bundledRulesDir, id, 'fix.mjs')))
+    .filter(id => filter === undefined || id === filter)
+  return ids.toSorted((a, b) => a.localeCompare(b))
+}

package/scripts/utils/run-rule.mjs

@@ -2,9 +2,9 @@
  * Оркестратор одного правила під CLI `check`.
  *
  * Послідовність (concerns у межах правила — алфавітно):
- *   1. **applies-гейт** з `fix/applies/check.mjs`. Якщо модуль експортує `applies()` і вона повертає
+ *   1. **applies-гейт** з `js/applies/check.mjs`. Якщо модуль експортує `applies()` і вона повертає
  *      false — друкуємо `✅ правило не застосовне` і завершуємо без подальших викликів.
- *   2. **JS-концерни** — кожен `check*.mjs` у `fix/<concern>/`. Concern `applies` теж може мати
+ *   2. **JS-концерни** — кожен `check*.mjs` у `js/<concern>/`. Concern `applies` теж може мати
  *      `check()` для друку контексту (його `applies()` уже відпрацював на кроці 1, він не повторюється).
  *   3. **Policy-концерни** — кожен `policy/<concern>/target.json` через `runConftestBatch`.
  *      Резолвер `resolveTargetFiles` ділить cache (`walkCache`) між концернами.
@@ -24,9 +24,9 @@ import { resolveConcernTemplateData } from './template.mjs'
 const APPLIES_CONCERN_NAME = 'applies'
 
 /**
- * Обчислює абсолютний шлях до файла-check у JS-концерні: `rules/<id>/fix/<concern>/<file>`.
- * Legacy `js/` корінь і поле `concern.rootDir` прибрані у 1.11.12 — усі правила переїхали
- * у `fix/` ще у 1.11.10.
+ * Обчислює абсолютний шлях до файла-check у JS-концерні: `rules/<id>/js/<concern>/<file>`.
+ * Convention `js/` (за технологією) повернулась у 1.13.80 після короткої епохи `fix/`
+ * (1.11.10–1.13.79) — щоб не плутати з кореневим `fix.mjs` entry-point'ом.
  * @param {string} bundledRulesDir абсолютний `rules/`
  * @param {string} ruleId id правила
  * @param {import('./discover-checkable-rules.mjs').JsConcern} concern опис концерну
@@ -34,11 +34,11 @@ const APPLIES_CONCERN_NAME = 'applies'
  * @returns {string} абсолютний шлях
  */
 function resolveJsCheckPath(bundledRulesDir, ruleId, concern, fileName) {
-  return join(bundledRulesDir, ruleId, 'fix', concern.name, fileName)
+  return join(bundledRulesDir, ruleId, 'js', concern.name, fileName)
 }
 
 /**
- * Спробувати викликати applies() гейт з `fix/applies/check.mjs` правила.
+ * Спробувати викликати applies() гейт з `js/applies/check.mjs` правила.
  * Гейт активний лише за наявності концерну з імʼям `applies` і експортом-функцією `applies` у його
  * першому check-файлі (алфавіт).
  * @param {string} bundledRulesDir абсолютний `rules/`

package/scripts/utils/run-standard-rule.mjs

@@ -0,0 +1,34 @@
+/**
+ * Public API per-rule orchestration. Викликається з `rules/<id>/fix.mjs`.
+ *
+ * Інкапсулює: `discoverOneRule` → `runRule(applies → JS → policy → mdc-refs)`.
+ * Локальна логіка в правилах заборонена; розширення поведінки — через `ctx`-опції.
+ */
+import { basename, dirname } from 'node:path'
+
+import { discoverOneRule } from './discover-checkable-rules.mjs'
+import { runRule } from './run-rule.mjs'
+import { getOrCreateWalkCache } from './walk-cache.mjs'
+
+/**
+ * @typedef {object} RuleContext
+ * @property {Map<string, Promise<string[]>>} [walkCache] FS-walk cache між concerns одного прогону
+ *
+ * Зарезервовано на майбутнє (поки не реалізовано — додається, коли з'явиться потреба):
+ *   - `skipMdcRefs`, `skipApplies`, `onlyConcerns`.
+ * Розширення поведінки правила робиться лише через нові поля тут, не через локальну
+ * логіку в `rules/<id>/fix.mjs`.
+ */
+
+/**
+ * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
+ * @param {RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 OK, 1 violations
+ */
+export async function runStandardRule(ruleDir, ctx = {}) {
+  const ruleId = basename(ruleDir)
+  const bundledRulesDir = dirname(ruleDir)
+  const rule = await discoverOneRule(ruleDir, ruleId)
+  const walkCache = ctx.walkCache ?? getOrCreateWalkCache()
+  return runRule(rule, bundledRulesDir, walkCache)
+}

package/scripts/utils/walk-cache.mjs

@@ -0,0 +1,24 @@
+/**
+ * Module-singleton FS-walk cache, спільний для всіх concerns одного `check`-прогону.
+ * Ключі — рядкові glob/regex дескриптори; значення — `Promise<string[]>` зі списком файлів.
+ * Кеш живий у межах одного процесу (Node/Bun module-instance). Тести скидають через `resetWalkCache()`.
+ */
+
+/** @type {Map<string, Promise<string[]>> | null} */
+let cache = null
+
+/**
+ * Повертає поточний cache; lazy-ініціалізує при першому виклику.
+ * @returns {Map<string, Promise<string[]>>} module-singleton walk cache
+ */
+export function getOrCreateWalkCache() {
+  if (cache === null) cache = new Map()
+  return cache
+}
+
+/**
+ * Скидає cache (для тестів між кейсами).
+ */
+export function resetWalkCache() {
+  cache = new Map()
+}

package/scripts/utils/with-lock.mjs

@@ -0,0 +1,120 @@
+/**
+ * Guard-механізм: атомарний lock + dedup для важких команд.
+ * Алгоритм: mkdirSync-based lock, перевірка живості PID, sha256-dedup з TTL.
+ */
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { worktreeFingerprint } from './worktree-fingerprint.mjs'
+
+const DEFAULTS = {
+  ttl: 600_000,
+  staleThreshold: 1_800_000,
+  waitTimeout: 1_200_000,
+  pollInterval: 1_500,
+}
+
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms))
+}
+
+function makeRelease(lockDir) {
+  return () => fs.rmSync(lockDir, { recursive: true, force: true })
+}
+
+/**
+ * @param {{exitCode:number, fingerprint:string|null, finishedAt:number}} result
+ * @param {string|null} fingerprint
+ * @param {number} ttl
+ */
+export function shouldDedup(result, fingerprint, ttl) {
+  if (result.exitCode !== 0) return false
+  if (fingerprint === null || result.fingerprint !== fingerprint) return false
+  if (Date.now() - result.finishedAt >= ttl) return false
+  return true
+}
+
+/**
+ * @param {string} key
+ * @param {() => Promise<number>} runFn
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string}} [opts]
+ * @returns {Promise<number>}
+ */
+export async function withLock(key, runFn, opts = {}) {
+  const { ttl, staleThreshold, waitTimeout, pollInterval } = { ...DEFAULTS, ...opts }
+  const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
+  const cacheDir = opts.cacheDir ?? path.join(process.cwd(), 'node_modules/.cache/n-cursor', key)
+  const lockDir = path.join(cacheDir, 'lock')
+  const ownerFile = path.join(lockDir, 'owner.json')
+  const resultFile = path.join(cacheDir, 'result.json')
+  const release = makeRelease(lockDir)
+
+  const fingerprint = getFingerprint()
+  fs.mkdirSync(cacheDir, { recursive: true })
+
+  const loopStart = Date.now()
+  let locked = false
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    if (Date.now() - loopStart >= waitTimeout) {
+      console.error(`⚠️ ${key}: чекав ${waitTimeout / 60_000} хв — запускаю без локу`)
+      return await runFn()
+    }
+    try {
+      fs.mkdirSync(lockDir)
+      fs.writeFileSync(ownerFile, JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now(), fingerprint }))
+      locked = true
+      break
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      let owner
+      try { owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8')) } catch {
+        fs.rmSync(lockDir, { recursive: true, force: true })
+        continue
+      }
+      const stale = (Date.now() - owner.startedAt > staleThreshold) ||
+        (os.hostname() === owner.host && !isAlive(owner.pid))
+      if (stale) {
+        console.error(`🧹 ${key}: знайдено застарілий лок — очищаю`)
+        fs.rmSync(lockDir, { recursive: true, force: true })
+        continue
+      }
+      console.error(`⏳ ${key}: чекаю, лок тримає pid ${owner.pid}…`)
+      await sleep(pollInterval)
+    }
+  }
+
+  console.error(`🔒 ${key}: лок взято`)
+
+  try {
+    const raw = fs.readFileSync(resultFile, 'utf8')
+    const result = JSON.parse(raw)
+    if (shouldDedup(result, fingerprint, ttl)) {
+      const elapsed = Math.round((Date.now() - result.finishedAt) / 1000)
+      console.error(`♻️ ${key}: те саме дерево, ${elapsed}с тому — пропускаю`)
+      release()
+      return 0
+    }
+  } catch { /* result.json не існує або пошкоджений */ }
+
+  const onSignal = () => { release(); process.exit(130) }
+  process.once('SIGINT', onSignal)
+  process.once('SIGTERM', onSignal)
+
+  let code
+  try {
+    code = await runFn()
+    fs.writeFileSync(resultFile, JSON.stringify({ finishedAt: Date.now(), exitCode: code, fingerprint }))
+  } finally {
+    process.off('SIGINT', onSignal)
+    process.off('SIGTERM', onSignal)
+    release()
+  }
+
+  return code
+}

package/scripts/utils/workspaces.mjs

@@ -11,7 +11,7 @@ import { dirname, join, relative } from 'node:path'
 const TRAILING_SLASH_RE = /\/$/
 const LEADING_DOTSLASH_RE = /^\.\//
 
-/** Glob-ігнор для workspace-патернів із `*` (узгоджено з `package-manifest.mjs`). */
+/** Glob-ігнор для workspace-патернів із `*` (узгоджено з `rules/changelog/js/consistency/package-manifest.mjs`). */
 export const WORKSPACE_GLOB_IGNORE = Object.freeze(['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**'])
 
 /**

package/scripts/utils/worktree-fingerprint.mjs

@@ -0,0 +1,30 @@
+/**
+ * Fingerprint поточного стану git-робочого дерева.
+ * Повертає sha256-hex (64 символи) або null, якщо не в git-репо.
+ * @param {typeof import('child_process').spawnSync} spawn
+ */
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+
+export function worktreeFingerprint(spawn = spawnSync) {
+  /** @param {string[]} args */
+  function git(args) {
+    const r = spawn('git', args, { encoding: 'utf8' })
+    if (r.status !== 0 || r.error) throw new Error(`git ${args[0]} failed`)
+    return r.stdout
+  }
+
+  try {
+    const commitHash = git(['rev-parse', 'HEAD']).trim()
+    const diffText = git(['diff', 'HEAD'])
+    const untrackedRaw = git(['ls-files', '--others', '--exclude-standard'])
+    const untrackedFiles = untrackedRaw.split('\n').filter(Boolean)
+    const pairs = untrackedFiles
+      .map(f => `${f}:${git(['hash-object', f]).trim()}`)
+      .sort()
+    const raw = [commitHash, diffText, ...pairs].join('\n')
+    return createHash('sha256').update(raw).digest('hex')
+  } catch {
+    return null
+  }
+}