@7n/rules 1.29.1 → 1.29.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.29.3] - 2026-07-19
+
+### Changed
+
+- release: @7n/llm-lib@2.8.3, @7n/rules@1.29.2
+
+## [1.29.2] - 2026-07-19
+
+### Changed
+
+- fix(auto-worktree): на брудному дереві перед auto-create — інтерактивний y/N-запит закомить і запушити (`npx @7n/n push`) замість одразу кидати
+- chore(adr): батч фонової нормалізації — чернетки doc-files/worktree-lifecycle у канонічні ADR
+
 ## [1.29.1] - 2026-07-19
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.29.1",
+  "version": "1.29.3",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/scripts/lib/auto-worktree.mjs

@@ -2,6 +2,26 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, rm } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+
+const YES_RE = /^y(es)?$/i
+
+/**
+ * Питає y/N у терміналі. Поза TTY (CI, неінтерактивний виклик) — одразу `false`,
+ * той самий безпечний дефолт, що й раніше (throw), без зависання на порожньому stdin.
+ * @param {string} message текст питання (без "[y/N]" — додається тут)
+ * @returns {Promise<boolean>} `true` лише на явне "y"/"yes"
+ */
+async function defaultConfirm(message) {
+  if (!process.stdin.isTTY) return false
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = await rl.question(`${message} [y/N] `)
+    return YES_RE.test(answer.trim())
+  } finally {
+    rl.close()
+  }
+}
 
 /**
  * Гарантує, що подальші кроки виконуються в ізольованому worktree
@@ -16,18 +36,29 @@ import { dirname, join } from 'node:path'
  * Якщо у вихідному `cwd` вже є незакомічені зміни, вони НЕ потраплять у щойно
  * створений worktree (той — checkout HEAD), і перенесення назад мовчки
  * затерло б їх версією з worktree. Тому за замовчуванням (`requireCleanTree:
- * true`) auto-create кидає на брудному дереві замість ризикувати чужими
- * незакоміченими правками. Викликач, що гарантує чистоту дерева сам (наприклад
- * taze — SKILL.md вимагає цього як передумову ще ДО виклику), може передати
- * `requireCleanTree: false`, щоб не платити за зайву git-команду.
+ * true`) на брудному дереві auto-create питає в терміналі (`deps.confirm`,
+ * дефолт — y/N через stdin; поза TTY одразу "ні") дозвіл закомить і
+ * запушити зараз через `npx \@7n/n push` (сквош усього робочого дерева в один
+ * коміт + push у origin — сама команда підтвердження не питає, тому питаємо
+ * ми, ДО виклику). На "ні"/поза TTY — кидає, як і раніше. Викликач, що
+ * гарантує чистоту дерева сам (наприклад taze — SKILL.md вимагає цього як
+ * передумову ще ДО виклику), може передати `requireCleanTree: false`, щоб не
+ * платити за зайву git-команду і не питати підтвердження.
  * @param {string} cwd каталог для перевірки
  * @param {typeof import('node:child_process').spawnSync} spawnFn інжект для тестів
  * @param {(line: string) => void} log колбек прогресу
  * @param {{ suffix: string, description: string, requireCleanTree?: boolean }} opts `suffix` — коротка (до 10 символів) назва задачі для `<branch>-<suffix>`; `description` — текст для `npx \@7n/mt worktree create`
- * @returns {{ cwd: string, autoCreated: boolean, branchArg: string|null }} `autoCreated: false` — `cwd` без змін
+ * @param {{ confirm?: (message: string) => Promise<boolean> }} [deps] `confirm` — інжект для тестів/альтернативного UX (дефолт — `defaultConfirm`, readline y/N)
+ * @returns {Promise<{ cwd: string, autoCreated: boolean, branchArg: string|null }>} `autoCreated: false` — `cwd` без змін
  *   (вже worktree); `autoCreated: true` — `cwd` щойно створеного worktree і `branchArg`, з яким його створено
  */
-export function ensureRunningInWorktree(cwd, spawnFn, log, { suffix, description, requireCleanTree = true }) {
+export async function ensureRunningInWorktree(
+  cwd,
+  spawnFn,
+  log,
+  { suffix, description, requireCleanTree = true },
+  deps = {}
+) {
   const toplevelResult = spawnFn('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
   const toplevel = toplevelResult.status === 0 ? toplevelResult.stdout.trim() : ''
   const segments = new Set(toplevel.replaceAll('\\', '/').split('/'))
@@ -45,11 +76,28 @@ export function ensureRunningInWorktree(cwd, spawnFn, log, { suffix, description
   if (requireCleanTree) {
     const statusResult = spawnFn('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' })
     if (statusResult.status === 0 && statusResult.stdout.trim().length > 0) {
-      throw new Error(
-        `"${cwd}" не в ізольованому worktree і має незакомічені зміни — auto-create worktree тут НЕБЕЗПЕЧНИЙ: ` +
-          'перенесення результату назад копіюванням файлів затерло б ці незакомічені правки версією зі свіжого ' +
-          'checkout (worktree = HEAD, без твоїх правок). Закомить/застеш зміни або створи worktree вручну.'
+      const dirtyTreeError = () =>
+        new Error(
+          `"${cwd}" не в ізольованому worktree і має незакомічені зміни — auto-create worktree тут НЕБЕЗПЕЧНИЙ: ` +
+            'перенесення результату назад копіюванням файлів затерло б ці незакомічені правки версією зі свіжого ' +
+            'checkout (worktree = HEAD, без твоїх правок). Закомить/застеш зміни або створи worktree вручну.'
+        )
+
+      const confirm = deps.confirm ?? defaultConfirm
+      const wantsPush = await confirm(
+        `"${cwd}" не в ізольованому worktree і має незакомічені зміни — auto-create worktree тут НЕБЕЗПЕЧНИЙ ` +
+          '(перенесення назад копіюванням файлів затерло б їх версією зі свіжого checkout). ' +
+          'Закомить і запушити зараз через `npx @7n/n push`?'
       )
+      if (!wantsPush) throw dirtyTreeError()
+
+      log(`📤 "${cwd}" брудне — запускаю \`npx @7n/n push\` перед auto-create worktree...`)
+      runCommand('npx', ['@7n/n', 'push'], cwd, spawnFn)
+
+      const recheckResult = spawnFn('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' })
+      if (recheckResult.status !== 0 || recheckResult.stdout.trim().length > 0) {
+        throw new Error(`\`npx @7n/n push\` відпрацював, але "${cwd}" усе ще не чисте — перевір вручну (git status).`)
+      }
     }
   }
 

package/scripts/lib/docs/auto-worktree.md

@@ -3,7 +3,7 @@ type: JS Module
 title: auto-worktree.mjs
 resource: npm/scripts/lib/auto-worktree.mjs
 docgen:
-  crc: 8d55dfc5
+  crc: 82081402
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98
@@ -22,7 +22,7 @@ docgen:
 
 ## Публічний API
 
-- ensureRunningInWorktree — Гарантує ізольований worktree для наступних кроків; якщо вже працюєш у `.worktrees/`, лишає поточний каталог без змін, інакше створює окремий worktree та ставить залежності. За замовчуванням блокує запуск на брудному дереві, щоб не втратити незакомічені правки; це можна послабити лише там, де чистоту вже забезпечили іншим способом.
+- ensureRunningInWorktree — Гарантує ізольований worktree для наступних кроків; якщо вже працюєш у `.worktrees/`, лишає поточний каталог без змін, інакше створює окремий worktree та ставить залежності. За замовчуванням на брудному дереві питає в терміналі (y/N) дозвіл закомить і запушити зараз через `npx @7n/n push`, і лише на "ні" (або поза TTY) кидає; це можна послабити (`requireCleanTree: false`) лише там, де чистоту вже забезпечили іншим способом.
 - bringChangesBackToOriginal — Повертає зміни з автоствореного worktree у початкове дерево простим копіюванням файлів: нові й змінені файли переносять, видалені — прибирають у вихідному дереві. Працює як перенесення фактичного стану, а не як merge.
 - removeAutoCreatedWorktree — Прибирає тимчасовий worktree та пов’язану з ним ephemeral branch після того, як зміни вже перенесено назад; якщо прибирання не вдалось, залишає worktree для ручного розбору.
 

package/skills/taze/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/skills/taze/js/orchestrate.mjs
 docgen:
-  crc: c1bcfe63
+  crc: 9e3842cb
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98

package/skills/taze/js/migration-cache.mjs

@@ -0,0 +1,90 @@
+/** @see ./docs/migration-cache.md */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Каталог за замовчуванням для кешу міграцій — спільний для всіх репо на цій
+ * машині (не прив'язаний до конкретного worktree/репо), бо ключ кешу — сам
+ * пакет+діапазон версій, а не проєкт.
+ */
+export const DEFAULT_CACHE_DIR = join(homedir(), '.cache', 'n-rules', 'taze-migrations')
+
+/**
+ * Санітизує `(pkg, from, to)` у безпечне імʼя файлу — крос-репо ключ кешу.
+ * Той самий `(pkg, from, to)` у різних репо/воркспейсах дає той самий ключ.
+ * @param {string} pkg назва пакета (може містити `@scope/name`)
+ * @param {string} from стара версія
+ * @param {string} to нова версія
+ * @returns {string} ключ без розширення
+ */
+export function migrationCacheKey(pkg, from, to) {
+  return `${pkg}@${from}__${to}`.replaceAll(/[^a-zA-Z0-9._@-]/g, '-')
+}
+
+/**
+ * Читає кешований запис міграції для `(pkg, from, to)`, якщо інший
+ * repo/worktree на цій машині вже проганяв через LLM ту саму пару версій.
+ * Відсутній/побитий файл — `null` (мовчки, не провал прогону: кеш —
+ * оптимізація, а не залежність, від якої залежить коректність).
+ * @param {string} pkg назва пакета
+ * @param {string} from стара версія
+ * @param {string} to нова версія
+ * @param {{ cacheDir?: string, existsSyncFn?: typeof existsSync, readFileFn?: typeof readFile }} [deps] інжекти для тестів
+ * @returns {Promise<{notes: string, sourceRepo: string, updatedAt: string}|null>} кешований запис або null
+ */
+export async function readMigrationCache(pkg, from, to, deps = {}) {
+  const cacheDir = deps.cacheDir ?? DEFAULT_CACHE_DIR
+  const exists = deps.existsSyncFn ?? existsSync
+  const read = deps.readFileFn ?? readFile
+  const path = join(cacheDir, `${migrationCacheKey(pkg, from, to)}.json`)
+  if (!exists(path)) return null
+  try {
+    return JSON.parse(await read(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Зберігає результат ізольованого LLM-виклику для `(pkg, from, to)` — щоб
+ * наступний репо з тим самим bump-ом на цій машині не повторював
+ * CHANGELOG-дослідження з нуля (див. `readMigrationCache`).
+ * @param {string} pkg назва пакета
+ * @param {string} from стара версія
+ * @param {string} to нова версія
+ * @param {{notes: string, sourceRepo: string, updatedAt: string}} entry запис для збереження
+ * @param {{ cacheDir?: string, mkdirFn?: typeof mkdir, writeFileFn?: typeof writeFile }} [deps] інжекти для тестів
+ * @returns {Promise<void>}
+ */
+export async function writeMigrationCache(pkg, from, to, entry, deps = {}) {
+  const cacheDir = deps.cacheDir ?? DEFAULT_CACHE_DIR
+  const makeDir = deps.mkdirFn ?? mkdir
+  const write = deps.writeFileFn ?? writeFile
+  await makeDir(cacheDir, { recursive: true })
+  const path = join(cacheDir, `${migrationCacheKey(pkg, from, to)}.json`)
+  await write(path, JSON.stringify(entry, null, 2))
+}
+
+/**
+ * Дописує до промпта `provider.promptFor(entry)` підсумок відомої міграції,
+ * якщо кеш її знайшов — каже раннеру пропустити крок 1 (CHANGELOG/diff-
+ * дослідження) і одразу шукати використання в поточному проєкті.
+ * @param {string} prompt базовий промпт з `provider.promptFor(entry)`
+ * @param {{notes: string, sourceRepo: string}} cached кешований запис
+ * @returns {string} доповнений промпт
+ */
+export function withKnownMigrationNotes(prompt, cached) {
+  return [
+    prompt,
+    '',
+    '## Відома міграція (кеш з іншого репо на цій машині)',
+    '',
+    `Це саме оновлення (той самий пакет і діапазон версій) вже проаналізовано раніше в "${cached.sourceRepo}". Підсумок того прогону:`,
+    '',
+    cached.notes,
+    '',
+    'Довірся цьому підсумку й пропусти крок 1 (повторне CHANGELOG/diff-дослідження) — одразу переходь до кроку 2 (використання API в ЦЬОМУ проєкті) і застосування міграції, якщо вона тут релевантна.'
+  ].join('\n')
+}

package/skills/taze/js/orchestrate.mjs

@@ -10,6 +10,7 @@ import {
 import { assertEcosystemProvider } from '../../../scripts/lib/plugin-api.mjs'
 import { readNRulesConfigLite } from '../../../scripts/lib/read-n-rules-config-lite.mjs'
 import { getHandlers, resolvePlugins } from '../../../scripts/lib/resolve-plugins.mjs'
+import { readMigrationCache, withKnownMigrationNotes, writeMigrationCache } from './migration-cache.mjs'
 
 export { bringChangesBackToOriginal, removeAutoCreatedWorktree } from '../../../scripts/lib/auto-worktree.mjs'
 
@@ -123,11 +124,22 @@ async function runEcosystem(provider, { cwd, runner, log, deps, spawnFn, call })
     const diff = await provider.diff(cwd, eco.manifests, deps)
     log(`🔍 ${provider.title} diff: ${diff.major.length} major, ${diff.minorPatch} minor/patch`)
 
+    const readCache = deps.readMigrationCache ?? readMigrationCache
+    const writeCache = deps.writeMigrationCache ?? writeMigrationCache
     for (const entry of diff.major) {
       log(`🔧 [${provider.id}] ${entry.pkg} (${entry.manifest}): ${entry.from} → ${entry.to}...`)
-      const outcome = await call(runner, provider.promptFor(entry), cwd, deps)
+      let prompt = provider.promptFor(entry)
+      const cached = await readCache(entry.pkg, entry.from, entry.to, deps)
+      if (cached) {
+        log(`  ♻️ Кешована міграція з "${cached.sourceRepo}" — пропускаю повторне CHANGELOG-дослідження`)
+        prompt = withKnownMigrationNotes(prompt, cached)
+      }
+      const outcome = await call(runner, prompt, cwd, deps)
       eco.results.push({ ...entry, ...outcome })
       log(outcome.ok ? `  ✅ ${entry.pkg}` : `  ❌ ${entry.pkg}: ${outcome.error}`)
+      if (outcome.ok && outcome.text) {
+        await writeCache(entry.pkg, entry.from, entry.to, { notes: outcome.text, sourceRepo: cwd, updatedAt: new Date().toISOString() }, deps)
+      }
     }
 
     await provider.cleanup(cwd, eco.manifests, deps)
@@ -223,12 +235,46 @@ export async function runTazeOrchestrator(options = {}) {
   const call = deps.callRunner ?? callRunner
 
   const originalCwd = options.cwd ?? process.cwd()
-  const worktree = ensureRunningInWorktree(originalCwd, spawnFn, log, {
+  const worktree = await ensureRunningInWorktree(originalCwd, spawnFn, log, {
     suffix: 'taze',
     description: 'n-taze: worktree-only skill'
   })
   const cwd = worktree.cwd
 
+  let cleanedUp = false
+  /**
+   * Переносить зміни назад і прибирає автостворений worktree — не більше
+   * одного разу (idempotent), щоб і сигнальний обробник, і `finally` могли
+   * безпечно кликати те саме без подвійного `bringChangesBackToOriginal`/
+   * `removeAutoCreatedWorktree`.
+   * @returns {Promise<void>}
+   */
+  const cleanupAutoCreatedWorktree = async () => {
+    if (cleanedUp) return
+    cleanedUp = true
+    try {
+      await bringChangesBackToOriginal(cwd, originalCwd, spawnFn, log, deps)
+    } catch (error) {
+      log(`⚠️ Перенесення змін назад провалилось: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    removeAutoCreatedWorktree(worktree.branchArg, originalCwd, spawnFn, log)
+  }
+
+  // SIGINT/SIGTERM (Ctrl-C, таймаут зовнішнього раннера, `kill`) без обробника
+  // залишають автостворений worktree осиротілим — Node завершується одразу,
+  // `finally` нижче не встигає спрацювати. Ловимо сигнал, рятуємо прогрес
+  // (перенесення змін + видалення worktree) і лише тоді виходимо.
+  const exitProcess = deps.exitProcessFn ?? (code => (process.exitCode = code))
+  const onSignal = async signal => {
+    log(`⚠️ Отримано ${signal} — переношу прогрес автоствореного worktree назад перед виходом...`)
+    await cleanupAutoCreatedWorktree()
+    exitProcess(1)
+  }
+  if (worktree.autoCreated) {
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+  }
+
   try {
     const providers = deps.ecosystemProviders ?? (await loadPluginTazeProviders(cwd, log, deps))
     if (providers.length === 0) {
@@ -253,12 +299,9 @@ export async function runTazeOrchestrator(options = {}) {
     // сирітський worktree прибирався навіть при кинутому винятку всередині
     // try (падіння bunx/diff/провайдера), а не лише при успішному прогоні.
     if (worktree.autoCreated) {
-      try {
-        await bringChangesBackToOriginal(cwd, originalCwd, spawnFn, log, deps)
-      } catch (error) {
-        log(`⚠️ Перенесення змін назад провалилось: ${error instanceof Error ? error.message : String(error)}`)
-      }
-      removeAutoCreatedWorktree(worktree.branchArg, originalCwd, spawnFn, log)
+      process.removeListener('SIGINT', onSignal)
+      process.removeListener('SIGTERM', onSignal)
+      await cleanupAutoCreatedWorktree()
     }
   }
 }