# Перекиньте мост к чужому репозиторию {#root} @status:doc/work @audience:author,user [p01] Иногда текст, который должен читать ваш агент, живёт в репозитории, чей автор никогда не слышал о vibe. Пакет-мост делает его устанавливаемым всё равно: вы сопровождаете чужой репозиторий и публикуете обычный пакет, который его оборачивает, с авторством и лицензией оригинала, отделёнными от ваших. [p02] ```prompt Создай в этом проекте пакет-мост org.example/spec-kit, который оборачивает репозиторий https://github.com/example/spec-kit на его текущем теге выпуска как источник по ссылке, держи авторов и лицензию оригинала отдельно от наших и проверь пакет, прежде чем я его опубликую. ``` - needs: навык vibevm, установленный у вашего агента; доступ по сети к исходному репозиторию outcome: слот пакета с `bridge = true` и одним `[[embedded_source]]`, называющим адрес, коммит и хеш исходника оригинала; `vibe check` не находит ошибок - assert: `vibe check --path vibevm/vibepacks/org.example/spec-kit/v0.1.0 --quiet` ## Что происходит {#what-happens} [p03] Агент размечает пакет через `vibe init package`, помечает его мостом в манифесте и объявляет исходный репозиторий встроенным источником: его публичный адрес, точный коммит, хеш дерева исходников и лицензию оригинала. Установка пакета скачивает ровно этот исходник в машинное [хранилище](../glossary/index.xml#store) потребителя рядом с собственными файлами пакета. Мост никогда не становится вторым пакетом: обёрнутый репозиторий — это git-содержимое, о котором резолвер ничего не знает. > [p04] A **bridge package** closes the gap without the author's involvement: a > *maintainer* volunteers to steward someone else's repository and publishes an > ordinary vibevm package that **wraps** it. > > > [p05] `[package].bridge = true` marks a package as a bridge. > > > [p06] Either way, the embedded repo is **not** a second vibevm package: it is git > content, never entered into the dependency resolver > ([PROP-002](PROP-002-decentralized-registry.xml): one git repo = one package; > the submodule is part of *this* package's content, not a node). > > ## Три способа держать оригинал {#three-classes} [p07] Вендоренный: вы скопировали дерево оригинала в пакет и закоммитили. Это самый дешёвый мост, простые файлы и флаг, с [хуками](../glossary/index.xml#hook), если раскладку надо подправить. На подмодуле: ваш workspace ссылается на оригинал через git-подмодуль, который прямая git-установка сохраняет живым, а публикация сплющивает в обычные файлы. По ссылке: репозиторий пакета держит только ваши метаданные и адаптеры, а `[[embedded_source]]` называет адрес оригинала, неизменяемый коммит, хеш дерева исходников и лицензию; установка скачивает ровно этот исходник. > [p08] **Vendored ("git in git")** — the maintainer copied the upstream tree into > the package and committed it. This needs **none** of PROP-021/022 machinery: > it is plain files in a `snapshot` package. A vendored bridge is therefore the > cheapest case — the flag (§2.1) plus, if the layout needs shaping, hooks. > > > [p09] **Submodule-backed authoring** — the maintainer workspace references upstream > through a Git submodule ([PROP-021](PROP-021-submodule-sources.xml)). A direct > Git-source install preserves that live Git composition. Registry publication > deliberately flattens a clean populated gitlink into ordinary package files, > removes `.gitmodules`, and reports `submodule vendored at `; > the published package is therefore a truthful vendored snapshot, not a > dangling promise that consumers will recurse into the maintainer's repo. > > > [p10] **Reference-backed** — the package repository contains only maintainer-authored > metadata and adapters. `[[embedded_source]]` declares the original public Git > URL, an immutable full commit, an independently verified source-tree hash and > upstream licence provenance. Installation fetches that exact source directly > into the consumer's machine cache; selected `[[skill]]` content or > `[[skill.resource]]` files are projected from the authenticated cached tree. > The upstream is not copied into the bridge repository, is not resolved as a > vibevm dependency node, and its own `vibe.toml`, hooks and submodules are never > executed implicitly. The installed bridge itself remains a normal physical > `vibedeps` slot; source-aware loaders combine that owner root with named, > separately authenticated external roots without pretending the latter are > UPL package payload. > > [p11] ```toml [package] name = "spec-kit" group = "org.example" kind = "flow" version = "0.1.0" bridge = true license = "UPL-1.0" [[embedded_source]] name = "spec-kit" url = "https://github.com/example/spec-kit" commit = "0123456789abcdef0123456789abcdef01234567" content_hash = "sha256:…" upstream_authors = ["The Spec Kit contributors"] upstream_license = "MIT" ``` [p12] Объявленный источник аутентифицируется дважды, когда приходит: чекаут должен стоять на объявленном коммите, а хеш его дерева должен равняться объявленному. `ref_hint`, например имя тега, только для людей и никогда не выбирает байты. > [p13] **dependency-declared** — a package's manifest uses `[[embedded_source]]` > to name an upstream Git source independently of the package repository. The > declaration carries a portable name, public credential-free HTTPS URL, full > immutable commit, expected `sha256:` source-tree hash, optional ref hint, and > upstream licence provenance. This supports snapshot/binary-distributed bridge > packages without copying the upstream tree into their repository. > > > [p14] A dependency-declared source is authenticated twice: its resolved checkout > must equal the declared commit and its deterministic source-tree hash must > equal `content_hash`. `ref_hint` is diagnostic only and never selects bytes. > > ## Чья это работа {#whose-work} [p15] `authors` в манифесте называет людей, которые написали мост, его метаданные и адаптеры, и никогда авторов обёрнутых байтов; каждый встроенный источник записывает собственных `upstream_authors`, а списки, локи и [индексы](../glossary/index.xml#index-registry) держат два списка порознь. То же с лицензиями: `license` описывает только мост, каждый источник записывает лицензию оригинала и неизменяемую ссылку на неё, и мост никогда не выдаёт байты оригинала за перелицензированные. [Координата](../glossary/index.xml#coordinate) называет продукт, который ставит потребитель, а не кодовую базу, в которой писали упаковку: мост к Spec Kit может жить по адресу `org.speckit/speckit`, кто бы его ни сопровождал. > [p16] `[package].authors` names only the people or organisations that authored > the package's own metadata, adapters and other maintainer-owned payload. It > never absorbs the authors of referenced bytes. Every `[[embedded_source]]` > records those separately as a non-empty `upstream_authors` list. Listings, > locks and indexes preserve both lists under their own labels; they never > concatenate them into one ambiguous authorship claim. > > > [p17] A bridge records two distinct legal surfaces: `[package].license` describes > only the maintainer-authored bridge package, while every external embedded > source records its upstream licence and an immutable licence URL. A bridge > never presents upstream bytes as relicensed by the bridge maintainer. > > > [p18] The package's qualified coordinate > ([PROP-008](PROP-008-qualified-naming.xml)) names the **product a consumer > installs**, not the codebase in which its packaging machinery happened to be > written. Packaging Spec Kit does not make it `org.vibevm/*`; its product > coordinate may be `org.speckit/speckit`. Packaging Matt Pocock's collection > may be `com.mattpocock/skills`. The distinct steward remains visible through > `[package].authors`, the package distribution `source_url`, `bridge = true`, > and the upstream repository/PURL recorded by `[[embedded_source]]` and > `describes`. > > ## Подмодули на входе и на выходе {#submodules} [p19] vibe скачивает подмодули пакета, когда скачивает пакет, обновляет их вместе с ним и делает их содержимое доступным везде, где пакет оказывается: копирует в снимок для копирующих режимов, оставляет живыми для чекаута на месте. Публикация — граница: репозиторий [реестра](../glossary/index.xml#registry) — самодостаточный снимок, поэтому публикатор проверяет, что каждый заполненный подмодуль стоит на своём проиндексированном коммите и чист, копирует его файлы внутрь, удаляет `.gitmodules` и сообщает, что сплющил. > [p20] vibevm fetches a package's submodules when it fetches the package, updates them > when it updates the package, and makes the submodule content available wherever > the package is materialised — embedded into the snapshot for the > copy-based modes, or living natively for `in-place` > ([PROP-022](../vibe-workspace/PROP-022-materialization-modes.xml)). > > > [p21] **Publication boundary.** Workspace/direct Git source acquisition may carry > real submodules, but a per-package registry repository is a self-contained > package snapshot. Publish inspects each populated gitlink before copying, > requires its checkout to match the indexed commit and be clean, copies its > files as ordinary payload, drops `.git` and `.gitmodules`, and reports the > path plus exact vendored commit. Registry consumers therefore fetch no hidden > second repository; `resolved_commit` identifies the published package repo, > while the publication report preserves the flattened upstream evidence. > > ## Особые случаи и правила {#edge-cases} [p22] Мост публикуется и ставится как любой пакет; добавляет он происхождение. Оригинал может уйти вперёд без вас: поднять мост — значит поменять объявленный коммит и хеш и опубликовать новую версию.