diff --git a/content/docs/cli/configuration.mdx b/content/docs/cli/configuration.mdx index f1baf08..cff1b8b 100644 --- a/content/docs/cli/configuration.mdx +++ b/content/docs/cli/configuration.mdx @@ -51,7 +51,7 @@ Frozen rejects every root replace, even unused entries, before acce | Command | Relevant flags | |---------|----------------| -| generate | --project (repeatable), --all, --workspace, --descriptor_set_out, --descriptor_set_out_dir, --include_imports | +| generate | --gen-config, --project (repeatable), --all, --workspace, --descriptor_set_out, --descriptor_set_out_dir, --include_imports | | lint | --path (-p), --root (-r) | | breaking | --path (-p), --root (-r), --against | | init | --dir (-d), --module | @@ -62,7 +62,7 @@ Frozen rejects every root replace, even unused entries, before acce The global flags are --cfg (alias --config, default easyp.yaml), --debug (-d), --format (-f, text or json), and --frozen. EASYP_CFG, EASYP_DEBUG, and EASYP_FORMAT set their respective defaults. The module cache uses EASYPPATH or $HOME/.easyp. -By default, generate selects the closest easyp.gen.yaml in the current directory or a workspace ancestor. Repeat --project for multiple explicit consumers. --all separately opts into recursive selection below the invocation directory and is mutually exclusive with --project. --workspace sets the boundary for module paths and inheritance; by default this is the nearest Git repository or enclosing EasyP files. Modules and roots come from protobuf.mod; generate.packages selects exact protobuf package names across the selected modules. The generate --path and generate --root flags are unavailable. +By default, generate selects the closest easyp.gen.yaml in the current directory or a workspace ancestor. Use --gen-config private.easyp.gen.yaml for one explicitly named generation file; --cfg/--config selects policy only. Repeat --project for multiple explicit consumers. --all separately opts into recursive selection below the invocation directory. --gen-config, --project and --all are mutually exclusive selection modes. --workspace sets the boundary for module paths and inheritance; by default this is the nearest Git repository or enclosing EasyP files. Modules and roots come from protobuf.mod; generate.packages selects exact protobuf package names across the selected modules. The generate --path and generate --root flags are unavailable. --descriptor_set_out merges compatible graphs into one file; --descriptor_set_out_dir produces an independent file per project/module pair. The flags are mutually exclusive and destinations are invocation-relative. --include_imports defaults to false and affects exports only. plugins[].with_imports also defaults to false but separately enables imported code generation for an individual plugin. options.go.package_prefix changes Go only; full managed mode requires explicit generate.managed.enabled: true. diff --git a/content/docs/cli/configuration.ru.mdx b/content/docs/cli/configuration.ru.mdx index 9020cca..7276734 100644 --- a/content/docs/cli/configuration.ru.mdx +++ b/content/docs/cli/configuration.ru.mdx @@ -51,7 +51,7 @@ Frozen отклоняет все корневые replace, даже | Команда | Основные флаги | |---------|----------------| -| generate | --project (повторяемый), --all, --workspace, --descriptor_set_out, --descriptor_set_out_dir, --include_imports | +| generate | --gen-config, --project (повторяемый), --all, --workspace, --descriptor_set_out, --descriptor_set_out_dir, --include_imports | | lint | --path (-p), --root (-r) | | breaking | --path (-p), --root (-r), --against | | init | --dir (-d), --module | @@ -62,7 +62,7 @@ Frozen отклоняет все корневые replace, даже Общие флаги: --cfg (псевдоним --config, по умолчанию easyp.yaml), --debug (-d), --format (-f, text или json) и --frozen. Переменные EASYP_CFG, EASYP_DEBUG и EASYP_FORMAT задают значения по умолчанию. Кеш модулей находится в EASYPPATH или $HOME/.easyp. -По умолчанию generate выбирает ближайший easyp.gen.yaml в текущем или родительском каталоге workspace. --project можно повторять для нескольких явных потребителей. --all отдельно включает рекурсивный выбор внутри каталога запуска и несовместим с --project. --workspace задаёт границу для путей модулей и наследования; по умолчанию используется ближайший Git-репозиторий или охватывающие файлы EasyP. Модули и корни исходников берутся из protobuf.mod; generate.packages выбирает точные имена protobuf-пакетов среди выбранных модулей. Флагов generate --path и generate --root нет. +По умолчанию generate выбирает ближайший easyp.gen.yaml в текущем или родительском каталоге workspace. Для одного файла с другим именем используйте --gen-config private.easyp.gen.yaml; --cfg/--config выбирает только политики. --project можно повторять для нескольких явных потребителей. --all отдельно включает рекурсивный выбор внутри каталога запуска. --gen-config, --project и --all — взаимоисключающие режимы выбора. --workspace задаёт границу для путей модулей и наследования; по умолчанию используется ближайший Git-репозиторий или охватывающие файлы EasyP. Модули и корни исходников берутся из protobuf.mod; generate.packages выбирает точные имена protobuf-пакетов среди выбранных модулей. Флагов generate --path и generate --root нет. --descriptor_set_out объединяет совместимые графы в один файл; --descriptor_set_out_dir создаёт независимый файл для каждой пары проект/модуль. Флаги взаимоисключающие, пути считаются от каталога запуска. --include_imports по умолчанию равен false и влияет только на экспорт. plugins[].with_imports также по умолчанию равен false, но отдельно включает генерацию импортов для конкретного плагина. options.go.package_prefix меняет только Go; полный managed mode требует явного generate.managed.enabled: true. diff --git a/content/docs/cli/generator/index.mdx b/content/docs/cli/generator/index.mdx index f1358ba..960e82f 100644 --- a/content/docs/cli/generator/index.mdx +++ b/content/docs/cli/generator/index.mdx @@ -53,7 +53,24 @@ easyp generate --workspace ../.. --project .. --project is repeatable and cannot be combined with --all. Recursive discovery skips hidden directories, easyp_vendor, node_modules, and nested Git repositories. Select a project in a skipped directory explicitly. Automatic selection rejects a symlink configuration file; an explicit project selection is required to use it. Choosing --all authorizes plugins in the discovered projects, including command plugins. -The nearest Git repository, including a worktree with a .git file, supplies the workspace boundary. Without Git, enclosing EasyP configuration and manifest files establish the boundary; --workspace sets it explicitly. Project paths and descriptor destinations are relative to the invocation directory. Plugin output paths are relative to their easyp.gen.yaml. The command has no --path or --root flag. +The nearest Git repository, including a worktree with a .git file, supplies the workspace boundary. Without Git, enclosing EasyP configuration and manifest files establish the boundary; --workspace sets it explicitly. Project paths and descriptor destinations are relative to the invocation directory. Plugin output paths are relative to the selected generation file. The command has no --path or --root flag. + +## Named generation configs + +Keep profiles such as private.easyp.gen.yaml and public.easyp.gen.yaml beside the same protobuf.mod, then select one file with --gen-config: + +~~~bash +easyp generate --gen-config private.easyp.gen.yaml +easyp generate --gen-config public.easyp.gen.yaml +# The selected profile can also export descriptors. +easyp generate --gen-config public.easyp.gen.yaml --descriptor_set_out build/public.pb +~~~ + +The flag accepts one relative or absolute file path inside the workspace. Relative paths start at the invocation directory; --workspace can set the boundary explicitly. The file uses the native version: v1 generation format. Missing, empty or invalid selections fail without falling back to easyp.gen.yaml. + +Do not combine --gen-config with --project or --all. Automatic selection and --all still discover only standard easyp.gen.yaml files. The global --config/--cfg flag selects a policy file and does not select a generation profile. + +Colocated profiles keep the same source, module and output path rules; no directory relocation or extra ../ is needed. Plugin outputs remain relative to the selected file's directory. Options inherit from standard easyp.gen.yaml files in ancestor directories; a standard file in the same directory is an independent profile and is not inherited. See [profiles for one module](/docs/guides/multi-target-generation#profiles-for-one-module) for complete examples. ## Frozen generation @@ -64,7 +81,7 @@ easyp --frozen generate --all --descriptor_set_out_dir build/descriptors Each selected local native module must have protobuf.mod and protobuf.lock, including an empty lock without dependencies. An explicit workspace-relative path uses the selected module's files: backend/easyp.gen.yaml with generate.modules: [proto/user] validates proto/user/protobuf.mod and proto/user/protobuf.lock. The generator-only backend directory needs neither file. Frozen rejects all root replacements, even unused ones, and validates the locked direct and transitive graph before any plugin executes. A failure in a later selected project therefore prevents plugins in earlier projects from running. The same preflight applies to both descriptor export modes and pluginless exports. -A dependency selected by identity through generate.modules requires its consumer's manifest and lock; the downloaded dependency does not need its own lock. Unselected projects are ignored. --frozen does not change the existing --project/--all selection and plugin authorization rules. +A dependency selected by identity through generate.modules requires its consumer's manifest and lock; the downloaded dependency does not need its own lock. Unselected projects are ignored. --frozen does not change the existing --gen-config/--project/--all selection and plugin authorization rules. Exact locked commits may be downloaded into the cache and are hash-verified, including on cache reuse. Manifest and lock files are never rewritten, and dependency HEAD/tags are never resolved. Frozen is explicit, not inferred from CI, and does not make remote plugins offline or pin local plugin executables. See [frozen builds](/docs/cli/package-manager#frozen-builds). diff --git a/content/docs/cli/generator/index.ru.mdx b/content/docs/cli/generator/index.ru.mdx index 02ed54e..eeec76d 100644 --- a/content/docs/cli/generator/index.ru.mdx +++ b/content/docs/cli/generator/index.ru.mdx @@ -53,7 +53,24 @@ easyp generate --workspace ../.. --project .. --project можно повторять, но нельзя сочетать с --all. Рекурсивный поиск пропускает скрытые каталоги, easyp_vendor, node_modules и вложенные Git-репозитории. Проект в пропускаемом каталоге можно выбрать явно. Автоматический выбор отклоняет конфигурацию-симлинк; для неё нужен явный выбор проекта. Флаг --all разрешает запуск плагинов найденных проектов, включая command-плагины. -Границу workspace задаёт ближайший Git-репозиторий, включая worktree с файлом .git. Без Git граница определяется по охватывающим конфигам и манифестам EasyP; --workspace задаёт её явно. Пути проектов и дескрипторов считаются от каталога запуска. Пути результатов плагинов считаются от их easyp.gen.yaml. Флагов --path и --root у команды нет. +Границу workspace задаёт ближайший Git-репозиторий, включая worktree с файлом .git. Без Git граница определяется по охватывающим конфигам и манифестам EasyP; --workspace задаёт её явно. Пути проектов и дескрипторов считаются от каталога запуска. Пути результатов плагинов считаются от выбранного файла генерации. Флагов --path и --root у команды нет. + +## Конфиги генерации с разными именами + +Разместите private.easyp.gen.yaml и public.easyp.gen.yaml рядом с одним protobuf.mod и выбирайте файл через --gen-config: + +~~~bash +easyp generate --gen-config private.easyp.gen.yaml +easyp generate --gen-config public.easyp.gen.yaml +# Выбранный профиль также может экспортировать дескрипторы. +easyp generate --gen-config public.easyp.gen.yaml --descriptor_set_out build/public.pb +~~~ + +Флаг принимает один относительный или абсолютный путь к файлу внутри workspace. Относительный путь считается от каталога запуска; границу можно явно задать через --workspace. Файл использует нативный формат генерации version: v1. Отсутствующий, пустой или некорректный выбор вызывает ошибку без переключения на easyp.gen.yaml. + +Не сочетайте --gen-config с --project или --all. Автоматический выбор и --all по-прежнему находят только стандартные файлы easyp.gen.yaml. Общий флаг --config/--cfg выбирает файл политик и не выбирает профиль генерации. + +Профили в одном каталоге сохраняют прежние правила путей исходников, модулей и результатов: переносить конфиги и добавлять ../ не нужно. Результаты плагинов остаются относительными к каталогу выбранного файла. Опции наследуются из стандартных easyp.gen.yaml в родительских каталогах; стандартный файл в том же каталоге считается отдельным профилем и не наследуется. Полные примеры — в [руководстве по генерации для одного модуля](/ru/docs/guides/multi-target-generation#профили-для-одного-модуля). ## Генерация в режиме frozen @@ -64,7 +81,7 @@ easyp --frozen generate --all --descriptor_set_out_dir build/descriptors Каждому выбранному локальному native-модулю нужны protobuf.mod и protobuf.lock, в том числе пустой lock без зависимостей. Явный путь от workspace использует файлы выбранного модуля: backend/easyp.gen.yaml с generate.modules: [proto/user] проверяет proto/user/protobuf.mod и proto/user/protobuf.lock. Самому каталогу backend, содержащему только настройки генератора, эти файлы не нужны. Frozen отклоняет все корневые замены, даже неиспользуемые, и проверяет зафиксированный граф прямых и транзитивных зависимостей до запуска любого плагина. Ошибка в проекте, выбранном позже, поэтому не даст запустить плагины более ранних проектов. Проверка действует для обоих режимов экспорта дескрипторов, включая экспорт без плагинов. -Зависимость, выбранная по идентификатору через generate.modules, требует манифест и lock потребителя; собственный lock в скачанной зависимости не требуется. Невыбранные проекты игнорируются. --frozen не меняет существующие правила выбора и разрешения запуска плагинов через --project/--all. +Зависимость, выбранная по идентификатору через generate.modules, требует манифест и lock потребителя; собственный lock в скачанной зависимости не требуется. Невыбранные проекты игнорируются. --frozen не меняет существующие правила выбора и разрешения запуска плагинов через --gen-config/--project/--all. Точные коммиты из lock могут скачиваться в кеш; хеши проверяются и при повторном использовании кеша. Манифест и lock никогда не переписываются, HEAD/теги зависимостей не разрешаются. Frozen включается явно, а не по окружению CI; он не отключает сеть удалённым плагинам и не фиксирует локальные исполняемые файлы плагинов. Подробнее — в [менеджере пакетов](/ru/docs/cli/package-manager). diff --git a/content/docs/cli/package-manager/index.mdx b/content/docs/cli/package-manager/index.mdx index d3a9bb6..9a54c5f 100644 --- a/content/docs/cli/package-manager/index.mdx +++ b/content/docs/cli/package-manager/index.mdx @@ -134,6 +134,19 @@ There is no dependency re-resolution, HEAD/tag lookup, or manifest/lock creation ## Cache and revision-access errors +Git commands and cache-lock acquisition have a default limit of **five minutes per operation**. This is not a deadline for the whole dependency graph. Set EASYP_GIT_TIMEOUT to a positive duration such as 10m to change the limit; caller cancellation and earlier deadlines still take precedence. A timeout stops further repository candidates and full-history fallback. + +~~~bash +easyp --debug migrate +easyp --debug mod tidy +# Increase the limit for one invocation. +EASYP_GIT_TIMEOUT=10m easyp --debug mod tidy +~~~ + +Long dependency phases report progress every 15 seconds even without --debug. Debug logs add the dependency, revision, Git operation, snapshot/archive phases, elapsed times and file counts, so network access can be distinguished from source processing or waiting for a cache lock. + A hash mismatch in an installed module identifies the exact cache directory. Preserve it for investigation or quarantine only that entry, then retry easyp mod download. Do not rewrite protobuf.lock to hide the mismatch; the command does not automatically delete or repair the cache. +Producer policies explicitly selected through extends are read from verified Git objects at their locked revision. Validation does not fetch missing policy objects or write cache verification stamps. If that object source is missing or corrupt, run easyp mod download to restore it. A cached native snapshot remains usable for generation when no missing external policy fragment is requested. + An inaccessible Git repository is not evidence that a tag is absent. If history was fetched but the pinned commit is unavailable, restore access to the original revision instead of substituting HEAD. Tag revalidation and integrity checks remain enabled; no automatic offline fallback is introduced. diff --git a/content/docs/cli/package-manager/index.ru.mdx b/content/docs/cli/package-manager/index.ru.mdx index 0752726..f348f2a 100644 --- a/content/docs/cli/package-manager/index.ru.mdx +++ b/content/docs/cli/package-manager/index.ru.mdx @@ -134,6 +134,19 @@ Frozen отклоняет все корневые replace до об ## Ошибки кэша и доступа к ревизии +Git-команды и ожидание блокировки кеша по умолчанию ограничены **пятью минутами на операцию**. Это не общий срок разрешения всего графа зависимостей. Переменная EASYP_GIT_TIMEOUT принимает положительную длительность, например 10m; отмена вызывающей операции и более ранний deadline сохраняют приоритет. После таймаута поиск других репозиториев и fallback на полную историю прекращаются. + +~~~bash +easyp --debug migrate +easyp --debug mod tidy +# Увеличить лимит для одного запуска. +EASYP_GIT_TIMEOUT=10m easyp --debug mod tidy +~~~ + +Долгие этапы работы с зависимостями сообщают о прогрессе каждые 15 секунд даже без --debug. Debug-логи добавляют зависимость, ревизию, Git-операцию, этапы обработки снимка/архива, длительность и число файлов. Это помогает отличить сетевое ожидание от обработки исходников или ожидания блокировки кеша. + При несовпадении хеша установленного модуля ошибка указывает точный каталог кэша. Сначала сохраните его для расследования или изолируйте только эту запись, затем повторите easyp mod download. Не переписывайте protobuf.lock, чтобы скрыть несовпадение; команда сама не удаляет и не исправляет повреждённый кэш. +Политики производителя, явно подключённые через extends, читаются из проверенных Git-объектов закреплённой ревизии. Валидация не скачивает отсутствующие объекты политик и не записывает отметки проверки в кеш. Если этот источник объектов отсутствует или повреждён, восстановите его через easyp mod download. Установленный нативный снимок остаётся пригодным для генерации, если недостающий внешний фрагмент политики не запрошен. + Недоступность Git-репозитория не означает, что тег отсутствует. Когда история получена, но закреплённого коммита в ней нет, восстановите доступ к исходной ревизии вместо замены на HEAD. Проверка тегов и защита от изменения их содержимого сохраняются; автоматического перехода на офлайн-разрешение нет. diff --git a/content/docs/guides/multi-target-generation.mdx b/content/docs/guides/multi-target-generation.mdx index 4b5a89e..6ee97ba 100644 --- a/content/docs/guides/multi-target-generation.mdx +++ b/content/docs/guides/multi-target-generation.mdx @@ -101,4 +101,49 @@ Do not combine --all and --project. Without either fla Projects selecting the same module use that module's manifest and dependency lock. Separate modules can have different dependency graphs, so review their locks and test the generated clients together. +## Profiles for one module + +For a module containing private.v1 and public.v1 packages, keep both profiles in the module directory beside protobuf.mod. Its roots and dependencies apply to both profiles. + +~~~yaml +# private.easyp.gen.yaml +version: v1 +generate: + packages: [private.v1] +plugins: + - name: go + out: ./gen/go + opts: + paths: source_relative +options: + go: + package_prefix: github.com/acme/app/gen/go +~~~ + +~~~yaml +# public.easyp.gen.yaml +version: v1 +generate: + packages: [public.v1] +plugins: + - name: go + out: ./gen/go + opts: + paths: source_relative +options: + go: + package_prefix: github.com/acme/app/gen/go +~~~ + +Run each profile from that directory: + +~~~bash +easyp generate --gen-config private.easyp.gen.yaml +easyp generate --gen-config public.easyp.gen.yaml +~~~ + +The selected packages become generation targets; required imports remain available for linking. Each file keeps the usual module-relative source filters and file-relative plugin outputs, so changing the filename requires no path adjustments. These profiles explicitly repeat the Go prefix: a standard easyp.gen.yaml in the same directory is independent. Only standard files in ancestor directories provide inherited options. + +--gen-config selects one file and cannot be combined with --project or --all. Recursive discovery continues to look for standard easyp.gen.yaml files. Use separate commands to run multiple named profiles. + See the [generator reference](/docs/reference/easyp-gen-yaml) and [build reproducibility guide](/docs/guides/reproducibility). diff --git a/content/docs/guides/multi-target-generation.ru.mdx b/content/docs/guides/multi-target-generation.ru.mdx index 1f79ade..274e6a4 100644 --- a/content/docs/guides/multi-target-generation.ru.mdx +++ b/content/docs/guides/multi-target-generation.ru.mdx @@ -101,4 +101,49 @@ easyp generate --all Проекты, выбравшие один модуль, используют его манифест и lock зависимостей. У разных модулей графы зависимостей могут отличаться: проверяйте их lock-файлы и тестируйте сгенерированные клиенты вместе. +## Профили для одного модуля + +Для модуля с пакетами private.v1 и public.v1 разместите оба профиля в каталоге модуля рядом с protobuf.mod. Его корни и зависимости применяются к обоим профилям. + +~~~yaml +# private.easyp.gen.yaml +version: v1 +generate: + packages: [private.v1] +plugins: + - name: go + out: ./gen/go + opts: + paths: source_relative +options: + go: + package_prefix: github.com/acme/app/gen/go +~~~ + +~~~yaml +# public.easyp.gen.yaml +version: v1 +generate: + packages: [public.v1] +plugins: + - name: go + out: ./gen/go + opts: + paths: source_relative +options: + go: + package_prefix: github.com/acme/app/gen/go +~~~ + +Запускайте каждый профиль из этого каталога: + +~~~bash +easyp generate --gen-config private.easyp.gen.yaml +easyp generate --gen-config public.easyp.gen.yaml +~~~ + +Выбранные пакеты становятся целями генерации; необходимые импорты остаются доступны для связывания. Каждый файл сохраняет обычные фильтры исходников от каталога модуля и пути результатов от каталога конфига, поэтому смена имени файла не требует правки путей. В примерах Go prefix явно повторён: стандартный easyp.gen.yaml в том же каталоге независим. Наследуемые опции задают только стандартные файлы в родительских каталогах. + +--gen-config выбирает один файл и несовместим с --project или --all. Рекурсивный поиск по-прежнему находит стандартные easyp.gen.yaml. Для нескольких именованных профилей используйте отдельные команды. + См. [справочник генератора](/ru/docs/reference/easyp-gen-yaml) и [руководство по воспроизводимости](/ru/docs/guides/reproducibility). diff --git a/content/docs/introduction/install.mdx b/content/docs/introduction/install.mdx index 6478ab8..ec3b82b 100644 --- a/content/docs/introduction/install.mdx +++ b/content/docs/introduction/install.mdx @@ -39,15 +39,15 @@ points to the same image as `ghcr.io/easyp-tech/easyp:v0.17.0`. ## Opt into v1 nightly -Nightly tags use `v1.0.0-nightly.YYYYMMDD.sequence`. Choose an exact published tag from [GitHub Releases](https://github.com/easyp-tech/easyp/releases). The tag `v1.0.0-nightly.20261005.1` below is an example, not a promise that this release exists; replace it with a published tag before running any command. Nightly releases do not update the stable Homebrew formula or Docker `latest` image. +Nightly tags use `v1.0.0-nightly.YYYYMMDD.sequence`. The commands below pin [v1.0.0-nightly.20261009.1](https://github.com/easyp-tech/easyp/releases/tag/v1.0.0-nightly.20261009.1). To select another version, choose an exact published tag from [GitHub Releases](https://github.com/easyp-tech/easyp/releases). Nightly releases do not update the stable Homebrew formula or Docker `latest` image. ### Go: CLI and MCP Building v1 requires **Go 1.26.6 or later**. Install both binaries at the same exact version in a separate directory to keep your stable CLI on `PATH`: ```bash -# Example only: replace with an actual published nightly tag. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Select an exact published nightly tag. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin" mkdir -p "$NIGHTLY_BIN" GOBIN="$NIGHTLY_BIN" go install "github.com/easyp-tech/easyp/cmd/easyp@${NIGHTLY_TAG}" @@ -62,8 +62,8 @@ Invoke the nightly CLI by its full path. Configure your MCP client to run the `e The v1 archive contains both `easyp` and `easyp-mcp`. Download the asset matching your platform and verify it with the release checksums. For Linux amd64: ```bash -# Example only: replace with an actual published nightly tag. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Select an exact published nightly tag. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' NIGHTLY_VERSION="${NIGHTLY_TAG#v}" NIGHTLY_ASSET="easyp-${NIGHTLY_VERSION}-linux-amd64.tar.gz" NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin" @@ -82,8 +82,8 @@ Invoke the CLI and MCP binaries by their full paths in this separate directory. The nightly CLI image uses its exact tag in GHCR: ```bash -# Example only: replace with an actual published nightly tag. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Select an exact published nightly tag. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' docker run --rm -v "$PWD:/workspace" -w /workspace \ "ghcr.io/easyp-tech/easyp:${NIGHTLY_TAG}" --version ``` diff --git a/content/docs/introduction/install.ru.mdx b/content/docs/introduction/install.ru.mdx index ff6118e..d40ce86 100644 --- a/content/docs/introduction/install.ru.mdx +++ b/content/docs/introduction/install.ru.mdx @@ -39,15 +39,15 @@ title: "Установка EasyP" ## Явная установка v1 nightly -Nightly-теги имеют формат `v1.0.0-nightly.YYYYMMDD.sequence`. Выберите точный опубликованный тег в [GitHub Releases](https://github.com/easyp-tech/easyp/releases). Тег `v1.0.0-nightly.20261005.1` ниже — пример, а не утверждение, что такой релиз существует; замените его опубликованным тегом перед запуском команд. Nightly не обновляет стабильную формулу Homebrew или Docker-образ `latest`. +Nightly-теги имеют формат `v1.0.0-nightly.YYYYMMDD.sequence`. Команды ниже закреплены на [v1.0.0-nightly.20261009.1](https://github.com/easyp-tech/easyp/releases/tag/v1.0.0-nightly.20261009.1). Для другой версии выберите точный опубликованный тег в [GitHub Releases](https://github.com/easyp-tech/easyp/releases). Nightly не обновляет стабильную формулу Homebrew или Docker-образ `latest`. ### Go: CLI и MCP Для сборки v1 требуется **Go 1.26.6 или новее**. Установите оба бинарника в одной точной версии в отдельный каталог, чтобы сохранить стабильный CLI в `PATH`: ```bash -# Только пример: замените тег реально опубликованным nightly. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Выберите точный опубликованный nightly-тег. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin" mkdir -p "$NIGHTLY_BIN" GOBIN="$NIGHTLY_BIN" go install "github.com/easyp-tech/easyp/cmd/easyp@${NIGHTLY_TAG}" @@ -62,8 +62,8 @@ GOBIN="$NIGHTLY_BIN" go install "github.com/easyp-tech/easyp/cmd/easyp-mcp@${NIG Архив v1 содержит `easyp` и `easyp-mcp`. Скачайте файл для своей платформы и проверьте его по контрольным суммам релиза. Пример для Linux amd64: ```bash -# Только пример: замените тег реально опубликованным nightly. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Выберите точный опубликованный nightly-тег. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' NIGHTLY_VERSION="${NIGHTLY_TAG#v}" NIGHTLY_ASSET="easyp-${NIGHTLY_VERSION}-linux-amd64.tar.gz" NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin" @@ -82,8 +82,8 @@ tar -xzf "$NIGHTLY_ASSET" --strip-components=1 -C "$NIGHTLY_BIN" Nightly-образ CLI в GHCR выбирается по точному тегу: ```bash -# Только пример: замените тег реально опубликованным nightly. -NIGHTLY_TAG='v1.0.0-nightly.20261005.1' +# Выберите точный опубликованный nightly-тег. +NIGHTLY_TAG='v1.0.0-nightly.20261009.1' docker run --rm -v "$PWD:/workspace" -w /workspace \ "ghcr.io/easyp-tech/easyp:${NIGHTLY_TAG}" --version ``` diff --git a/content/docs/migration/easyp-v0.mdx b/content/docs/migration/easyp-v0.mdx index a00c2be..e1baa24 100644 --- a/content/docs/migration/easyp-v0.mdx +++ b/content/docs/migration/easyp-v0.mdx @@ -102,7 +102,7 @@ Import roots stay unchanged and generated files keep their source-relative paths `generate.paths` matches literal module-directory-relative files or directory subtrees, with `.` meaning all sources; `mcp` does not select `mcp-copy`. Paths intersect optional package selectors, and every selector must match a resulting source across the selected modules. Unknown selectors fail before plugins or descriptor writes, even without plugins or under `--all`. Required imports outside these paths remain available. These paths are separate from plugin `opts.paths`, which controls output layout. -Path selection requires an updated v1 build; the initial v1.0.0-nightly.20261005.1 and commit 8be79c7 do not provide it. When migration uses the complete-package fallback, the preview still warns that future files in those packages become targets regardless of their directory. +When migration uses the complete-package fallback, the preview warns that future files in those packages become targets regardless of their directory. Variable placeholders are not expanded into saved values. If a placeholder or selector prevents safe analysis, conversion fails rather than persisting credentials or guessing its meaning. @@ -116,11 +116,13 @@ A full commit SHA is preserved, including a full SHA embedded in an old pseudo-v Git's annotated-tag spelling, such as `v0.4.0^{}`, is accepted for a full SemVer tag in the historical lock. The tag, commit and original hash are still verified, and the old lock stays byte-identical. Peeled branches, abbreviated refs, repeated suffixes and pseudo-version-shaped peeled tags are rejected. +Keep easyp.lock when it is available; deleting it before migration is unnecessary. Without an old lock digest, migration skips historical whole-repository/archive hashing. An explicit git_repo.url pin such as gitlab/products/svc@<full-commit-SHA> still selects that revision and is never replaced with HEAD. Long dependency phases report progress; use easyp --debug migrate for operation timings and file counts. See [dependency timeouts and diagnostics](/docs/cli/package-manager#cache-and-revision-access-errors). + Released v0 installers archived Git's *.proto pathspec and stripped legacy root prefixes before hashing. Migration reproduces that archive at the pinned revision; it also retains verification of the existing whole-tree hash format. Omitted selected or reachable proto sources and changes to verified archive bytes require manual migration. An unused export-ignore source outside a verified filtered Git selection is permitted when historical hash, target names and reachable bindings match. A whole input that would gain an extra target still fails. The v1 content hash is then calculated independently over the materialized logical snapshot. Old and new hashes cover different path layouts and cannot be copied or compared as interchangeable values. A missing historical dependency pin is not replaced with current HEAD. -Internal symlinks to files, directories, import roots and metadata are supported. Protobuf import names follow the logical path of the alias. Local targets must remain inside their owning source boundary; Git targets must be relative and resolve entirely from the pinned tree. Selected dangling links, cycles, submodule crossings and undeclared nested repositories fail. Invalid unused auxiliary links are omitted. Git snapshots contain regular resolved bytes, including safe non-proto aliases, regardless of `core.symlinks`. +Internal symlinks to files, directories, import roots and metadata are supported. Protobuf import names follow the logical path of the alias. Local targets must remain inside their owning source boundary; Git targets must be relative and resolve entirely from the pinned tree. Selected dangling links, cycles, submodule crossings and undeclared nested repositories fail. Invalid unused auxiliary links are omitted. Native Git snapshots contain regular resolved bytes for selected proto files and canonical metadata, regardless of `core.symlinks`; unrelated code and build aliases are omitted. Explicitly extended policy fragments with arbitrary names are read separately from pinned Git objects. If the legacy configuration file itself is a symlink, migration replaces that logical file with regular v1 content and creates a regular backup of its original contents. The former target stays unchanged; rollback restores the original link. Inputs and link topology are checked again before applying. diff --git a/content/docs/migration/easyp-v0.ru.mdx b/content/docs/migration/easyp-v0.ru.mdx index fddac24..b992449 100644 --- a/content/docs/migration/easyp-v0.ru.mdx +++ b/content/docs/migration/easyp-v0.ru.mdx @@ -102,7 +102,7 @@ plugins: `generate.paths` выбирает буквальные пути файлов от каталога модуля или поддеревьев каталогов; `.` означает все исходники, а `mcp` не совпадает с `mcp-copy`. Пути пересекаются с необязательными selectors пакетов. Каждый selector должен совпасть с итоговым исходником хотя бы в одном выбранном модуле. Неизвестные selectors отклоняются до запуска плагинов и записи descriptors, в том числе без плагинов или с `--all`. Необходимые импорты вне этих путей остаются доступными. Эти пути отличаются от plugin `opts.paths`, управляющего раскладкой результатов. -Выборка по путям требует обновлённой сборки v1: первый v1.0.0-nightly.20261005.1 и коммит 8be79c7 её не поддерживают. Если мастер использует fallback по полным пакетам, preview по-прежнему предупреждает, что будущие файлы этих пакетов станут целями независимо от каталога. +Если мастер использует fallback по полным пакетам, preview предупреждает, что будущие файлы этих пакетов станут целями независимо от каталога. Подстановки переменных не сохраняются в раскрытом виде. Если переменная или selector мешает безопасному анализу, перенос останавливается, а не записывает секреты и не угадывает смысл настройки. @@ -116,11 +116,13 @@ plugins: Запись аннотированного Git-тега вроде `v0.4.0^{}` допустима для полного SemVer-тега в историческом lock. Тег, commit и исходный хеш по-прежнему проверяются, а старый lock сохраняется побайтово. Peeled-ветки, сокращённые refs, повторные суффиксы и peeled-теги в форме псевдоверсии отклоняются. +Сохраните easyp.lock, если он есть: удалять его перед миграцией не нужно. Без прежнего digest миграция пропускает историческое хеширование всего репозитория/архива. Явный pin в git_repo.url, например gitlab/products/svc@<full-commit-SHA>, по-прежнему выбирает эту ревизию и не заменяется на HEAD. Долгие этапы сообщают о прогрессе; команда easyp --debug migrate добавляет длительность операций и число файлов. См. [таймауты и диагностику зависимостей](/ru/docs/cli/package-manager#ошибки-кэша-и-доступа-к-ревизии). + Выпущенные версии v0 архивировали Git-pathspec *.proto и убирали legacy-префиксы корней перед вычислением хеша. Мигратор воспроизводит этот архив в закреплённой ревизии; проверка существующего формата хеша полного дерева тоже сохраняется. Пропуск выбранного или достижимого proto-источника и изменение проверенных архивных байтов требуют ручной миграции. Неиспользуемый источник с export-ignore вне проверенной выборки Git допустим, если исторический hash, имена targets и достижимые связи совпадают. Целый input, который получил бы лишний target, по-прежнему отклоняется. После проверки новый хеш v1 рассчитывается независимо по материализованному логическому снимку. Старый и новый хеши относятся к разным раскладкам путей; их нельзя просто копировать или считать взаимозаменяемыми. Отсутствующий исторический pin не заменяется текущим HEAD. -Внутренние симлинки на файлы, каталоги, import roots и метаданные поддерживаются. Имя protobuf-импорта определяется логическим путём ссылки. Локальная цель должна оставаться внутри границы своего источника; Git-ссылка должна быть относительной и разрешаться целиком в закреплённом дереве. Оборванные ссылки, циклы, переходы в submodule и необъявленные вложенные репозитории среди выбранных входов вызывают ошибку. Некорректные неиспользуемые служебные ссылки пропускаются. Git-снимок содержит обычные файлы с разрешёнными байтами, включая безопасные служебные алиасы, независимо от `core.symlinks`. +Внутренние симлинки на файлы, каталоги, import roots и метаданные поддерживаются. Имя protobuf-импорта определяется логическим путём ссылки. Локальная цель должна оставаться внутри границы своего источника; Git-ссылка должна быть относительной и разрешаться целиком в закреплённом дереве. Оборванные ссылки, циклы, переходы в submodule и необъявленные вложенные репозитории среди выбранных входов вызывают ошибку. Некорректные неиспользуемые служебные ссылки пропускаются. Нативный Git-снимок содержит обычные файлы с разрешёнными байтами выбранных proto и стандартных метаданных независимо от `core.symlinks`; посторонний код и служебные ссылки сборки пропускаются. Явно подключённые фрагменты политик с произвольными именами читаются отдельно из закреплённых Git-объектов. Если legacy-конфигурация сама является симлинком, миграция заменяет файл по этому логическому пути обычным v1-файлом и создаёт обычную резервную копию прежнего содержимого. Бывшая цель остаётся неизменной; откат восстанавливает исходную ссылку. Перед применением входные файлы и цепочка ссылок проверяются повторно. diff --git a/content/docs/reference/easyp-gen-yaml.mdx b/content/docs/reference/easyp-gen-yaml.mdx index 71bf44f..9500527 100644 --- a/content/docs/reference/easyp-gen-yaml.mdx +++ b/content/docs/reference/easyp-gen-yaml.mdx @@ -243,6 +243,10 @@ The separate version field is also unavailable for patheasyp generate selects the closest config in the current directory or a workspace ancestor. Repeat --project to choose multiple consumers explicitly; --all separately opts into recursive selection. --workspace sets the boundary for module paths and inheritance. +Use easyp generate --gen-config private.easyp.gen.yaml to select one native generation file with a different name. The path is relative to the invocation directory, or absolute, and must remain inside the workspace. This flag is mutually exclusive with --project and --all; the global policy selector --config cannot replace it. A missing or invalid file fails without a fallback. Defaults and recursive discovery still use easyp.gen.yaml. + +The selected file's directory remains the base for plugin output paths. Module selectors and source filters keep their existing workspace/module coordinates. Options inherit only from standard easyp.gen.yaml files in ancestor directories, not a sibling file in the same directory. See [named generation configs](/docs/cli/generator#named-generation-configs). + plugins[].with_imports defaults to false. True adds transitive imports to that plugin's files to generate. Import descriptors remain available for linking when false. The --descriptor_set_out and --descriptor_set_out_dir flags are mutually exclusive; --include_imports controls exported contents only, independently of with_imports. See [project selection and descriptor export](/docs/cli/generator). ## Managed-option validation diff --git a/content/docs/reference/easyp-gen-yaml.ru.mdx b/content/docs/reference/easyp-gen-yaml.ru.mdx index 36d8f6f..ecf2752 100644 --- a/content/docs/reference/easyp-gen-yaml.ru.mdx +++ b/content/docs/reference/easyp-gen-yaml.ru.mdx @@ -241,6 +241,10 @@ plugins: По умолчанию easyp generate выбирает ближайший конфиг в текущем или родительском каталоге workspace. Повторяйте --project для явного выбора нескольких потребителей; --all отдельно включает рекурсивный выбор. --workspace задаёт границу для путей модулей и наследования. +Команда easyp generate --gen-config private.easyp.gen.yaml выбирает один нативный файл генерации с другим именем. Путь считается от каталога запуска или задаётся абсолютно и должен оставаться внутри workspace. Флаг несовместим с --project и --all; общий флаг выбора политик --config его не заменяет. Отсутствующий или некорректный файл вызывает ошибку без fallback. Автоматический и рекурсивный поиск по-прежнему используют easyp.gen.yaml. + +Каталог выбранного файла остаётся базой путей результатов плагинов. Пути модулей и фильтры исходников сохраняют прежние координаты workspace/модуля. Опции наследуются только из стандартных easyp.gen.yaml в родительских каталогах, а не из соседнего файла в том же каталоге. См. [конфиги генерации с разными именами](/ru/docs/cli/generator#конфиги-генерации-с-разными-именами). + plugins[].with_imports по умолчанию равен false. Значение true добавляет транзитивные импорты в список файлов для генерации только этого плагина. Дескрипторы импортов для связывания доступны и при false. Флаги --descriptor_set_out и --descriptor_set_out_dir взаимоисключающие; --include_imports меняет только содержимое экспорта, независимо от with_imports. См. [выбор проектов и экспорт дескрипторов](/ru/docs/cli/generator). ## Проверка managed-опций diff --git a/content/docs/reference/protobuf-lock.mdx b/content/docs/reference/protobuf-lock.mdx index 6110a9f..69729f9 100644 --- a/content/docs/reference/protobuf-lock.mdx +++ b/content/docs/reference/protobuf-lock.mdx @@ -74,7 +74,9 @@ During tidy, get, and update, every fetch mod download uses the locked commit even after a tag moves, provided that commit remains available. -The hash uses Go's dirhash.Hash1 over the materialized logical snapshot at the commit, with repository-relative paths. Safe internal aliases contribute their resolved bytes under their logical names; Git objects are read directly, without checkout filters. Buf filters apply before hashing and installation. Invalid unused auxiliary links are omitted. Installed-cache identity includes the source, commit, hash and canonical root selection. EasyP verifies it on download and when reusing an installed module; corrupt installations are rejected. +The hash uses Go's dirhash.Hash1 over the materialized logical snapshot at the commit, with repository-relative paths. The snapshot contains selected .proto files and canonical EasyP/Buf configuration metadata; unrelated application code, documentation and build files are omitted. Safe internal aliases for selected files contribute their resolved bytes under their logical names; Git objects are read directly, without checkout filters. Buf filters apply before hashing and installation. Invalid unused auxiliary links are omitted. Installed-cache identity includes the source, commit, hash and canonical root selection. EasyP verifies it on download and when reusing an installed module; corrupt installations are rejected. + +An explicitly extended producer-policy fragment with an arbitrary filename is read on demand from verified Git objects at the locked commit. It does not require copying the repository's unrelated files into the installed snapshot. See [policy inheritance](/docs/cli/configuration). The v1 cache reuses an object store per Git remote. A known exact commit can be fetched without contacting the remote. A cold request first tries a depth-one fetch of the exact commit; if the server rejects that request, EasyP falls back to advertised reachable history. The original commit is still required: HEAD is never substituted. Tag lookups are refreshed separately so cache reuse cannot hide a retag. A commit absent from cache can still require access to its source. diff --git a/content/docs/reference/protobuf-lock.ru.mdx b/content/docs/reference/protobuf-lock.ru.mdx index 94f6c8c..f6f124a 100644 --- a/content/docs/reference/protobuf-lock.ru.mdx +++ b/content/docs/reference/protobuf-lock.ru.mdx @@ -74,7 +74,9 @@ modules: mod download использует коммит из lock даже после переноса тега, если этот коммит доступен. -hash вычисляется через Go dirhash.Hash1 по материализованному логическому снимку коммита с путями относительно репозитория. Безопасные внутренние алиасы добавляют разрешённые байты под своими логическими именами; Git-объекты читаются напрямую, без checkout-фильтров. Buf-фильтры применяются до хеширования и установки. Некорректные неиспользуемые служебные ссылки пропускаются. Ключ установленного кеша включает источник, commit, hash и канонический набор корней. Хеш проверяется и при скачивании, и при повторном использовании установленного модуля; повреждённая установка отклоняется. +hash вычисляется через Go dirhash.Hash1 по материализованному логическому снимку коммита с путями относительно репозитория. Снимок содержит выбранные .proto и стандартные конфиги EasyP/Buf; посторонний код приложения, документация и файлы сборки пропускаются. Безопасные внутренние алиасы выбранных файлов добавляют разрешённые байты под своими логическими именами; Git-объекты читаются напрямую, без checkout-фильтров. Buf-фильтры применяются до хеширования и установки. Некорректные неиспользуемые служебные ссылки пропускаются. Ключ установленного кеша включает источник, commit, hash и канонический набор корней. Хеш проверяется и при скачивании, и при повторном использовании установленного модуля; повреждённая установка отклоняется. + +Явно подключённый через наследование фрагмент политики производителя с произвольным именем читается по запросу из проверенных Git-объектов закреплённого коммита. Копировать посторонние файлы репозитория в установленный снимок для этого не нужно. См. [наследование политик](/ru/docs/cli/configuration). Для каждого Git remote кеш v1 повторно использует хранилище объектов. Известный точный коммит можно получить без обращения к remote. При холодном запросе сначала выполняется shallow-загрузка точного коммита с глубиной один; если сервер её отклоняет, используется доступная история объявленных ссылок. Всё равно требуется исходный коммит: HEAD вместо него не подставляется. Проверки тегов обновляются отдельно, поэтому кеш не скрывает перенос тега. Отсутствующий в кеше коммит всё ещё может потребовать доступа к источнику.