# tools-ast-edit

## Назначение

`ast_edit` никогда сам не пишет файлы. Он только строит in-memory preview AST rewrite и возвращает `previewId`; запись на диск выполняется OMP-compatible tool `resolve` после stale-file проверки. Legacy `ast_apply` еще существует как alias для старых callers.

Такое имя остается допустимым только потому, что tool планирует структурное редактирование, но критичный preview-only контракт должен быть виден с первой строки. Если продуктово понадобится прямое редактирование одним tool, это должно быть отдельным redesign с явным apply mode и теми же stale-check гарантиями.

## Почему он есть в проекте

Extension нужен для preview-first refactor flow. Агент может рассчитать потенциальные правки по AST-паттернам, но запись на диск остается отделенной от расчета, чтобы review и apply были отдельными действиями.

## Пользовательская поверхность

Агент вызывает tool `ast_edit`, когда хочет подготовить structural rewrite. Обязательные параметры: `ops` со списком операций `{ pat, out }` и `paths` со списком файлов, директорий или простых path/glob-выражений. Optional параметр `language` задает язык явно; без него язык определяется по расширению файла.

Tool возвращает `previewId`, список файлов с числом замен и общее количество replacement. Применение или отклонение preview выполняется tool `resolve`.

## Как работает по коду

Entrypoint валидирует параметры, расширяет `paths` относительно project root и вызывает `_shared/ast-engine.astPreview`. Движок читает каждый файл, последовательно применяет AST-операции к in-memory тексту, считает replacements и сохраняет preview в module-level `Map`.

Preview содержит исходный текст, новый текст, количество замен и SHA-256 исходного содержимого каждого файла. После создания preview extension отправляет dev event `ast:preview` и возвращает summary, но не вызывает `writeFile`.

- Entrypoint: `./extensions/tools-ast-edit/index.ts`
- Manifest: `extensions/tools-ast-edit/manifest.json`
- Commands: none
- Tools: `ast_edit`
- Hooks: none
- Permissions: fs.read=`.`, fs.write=none, subprocess=none, network=none, browser=false, models=false, ui=none
- State: Pending previews живут только в памяти процесса внутри `_shared/ast-engine`; после restart они пропадут.
- Review: status=reviewed, source=write-from-scratch, reviewedBy=pi-dev-extensions, reviewedAt=2026-06-01, risk=high

## Ограничения и риски

Tool intentionally preview-only, но он все равно high-risk по смыслу: результат может подготовить массовый rewrite. Без просмотра diff человек или агент видит только summary по файлам и количеству замен.

Preview хранится в памяти, поэтому его нельзя считать durable артефактом. Если код изменился между preview и apply, stale-проверка должна сработать в `resolve`.

## Решение

Решение: оставить `tools-ast-edit` как preview-only planner. Критичная product boundary теперь зафиксирована явно: `ast_edit` планирует структурное редактирование, а `resolve` пишет файлы через pending preview finalization.