Машинные форматы и JSON-отчёты
01Каждая команда умеет отвечать в JSON для скриптов и агентов. Эта страница перечисляет документы, их схемы и поля конверта, которые несёт каждый документ.
vibe list --json --path hello-vibe{
"ok": true,
"command": "list",
"project": "<TMP>/work/hello-vibe",
"count": 1,
"packages": [
{
"kind": "flow",
"name": "wal",
"version": "1.0.0",
"bridge": false,
"authors": [
"Oleg Chirukhin"
],
"source_url": "file:///<TMP>/registry/org.vibevm.world/wal/v1.0.0",
"content_hash": "sha256:58eccc204df7e63e78e8d15f9416b6fd528e786b74d9e0e5e2fcb859716ea0d0",
"boot_snippet": null,
"files_written": []
}
]
}Одно правило для каждого формата
03Всё, что читает чужой парсер, будь то отчёт, который разбирает скрипт, файл, который пишет другой язык, или манифест, который получает браузер, описано схемой и зарегистрировано в одном реестре. Типы Rust и типы TypeScript генерируются из схемы, никогда не пишутся руками, так что две стороны не могут разойтись. Незарегистрированный формат не просто не поощряется: его нельзя выразить в системе типов, которая его пишет.
04 цитата из спецификации
16. JTD + codegen for wire contracts
05 spec: The format registry
4.1 The format registry.formats/REGISTRY.tomlinventories every surface a foreign parser reads: id, epoch, schema path, recoverable-or-not, independent-parser count, sunset date, golden-corpus path. From it theFormatIdenum is generated, and all wire I/O goes throughwire::publish(FormatId, …)/wire::load(FormatId, …)— an unregistered format is inexpressible in the type system, not merely discouraged. An unnumbered format is a format that will be broken without anyone noticing.
06Схемы — документы JSON Typedef под schemas/ в дереве исходников. Реестр — formats/REGISTRY.toml. Для каждого формата он записывает эпоху, схему, можно ли пересобрать формат из другого состояния и сколько парсеров его читают. Он же называет корпус золотых документов, с которым сверяется сборка.
07 spec: A format's policy is computed, not chosen
A format's policy is computed, not chosen, from
two axes: is it recoverable without a human, and how many independent parsers
exist. Recoverable + one parser → hard gate + silent rebuild (lockfile,
caches). Recoverable + many parsers → epochs, parallel publication, generated
clients, narrow projection (catalog, CLI JSON). Unrecoverable + one parser →
epoch-in-file + codemod (configs). Unrecoverable + many parsers is the worst
quadrant — minimise it, epoch it, migrate it by bot (vibe.toml is the only
resident, and creating a new format in this quadrant requires an explicit
owner decision recorded in the format registry).
Конверт
08Документ --json — один JSON-объект на команду или поток объектов для команд, которые отчитываются по стадиям, например установка. Каждый объект несёт ok, command, которая его произвела, и поля отчёта, которые называет схема; когда вызывающий представился через --invoked-by, объект несёт invoked_by, а под --unattended — unattended: true.
Документы
| Команда | Документ | Схема |
|---|---|---|
vibe init --json |
отчёт скаффолда | init_report.jtd.json |
vibe install --json |
план, затем отчёт | install_plan.jtd.json, install_report.jtd.json |
vibe update --json |
отчёт обновления | update_report.jtd.json |
vibe uninstall --json |
отчёт удаления | uninstall_report.jtd.json |
vibe reinstall --json |
отчёт регенерации | reinstall_report.jtd.json |
vibe list --json |
установленные пакеты | list_report.jtd.json |
vibe registry publish --json, vibe registry sync --json |
отчёты публикации и синхронизации | registry_publish_report.jtd.json, registry_sync_report.jtd.json |
vibe extensions --json, vibe extensions analyze --json |
реестр расширений и анализ полосы | extensions_report.jtd.json, extensions_analyze.jtd.json |
глаголы жизненного цикла с --json |
план, отчёт, состояние и отложенные задачи | lifecycle_plan.jtd.json, lifecycle_report.jtd.json, lifecycle_state.jtd.json, lifecycle_tasks.jtd.json |
vibe deploy, vibe deployments --json |
намерение выкладки, квитанции, обратный план и контрольные точки | deploy_intent.jtd.json, deploy_receipt.jtd.json |
vibe requirements --json |
отчёт о требованиях | requirements_report.jtd.json |
vibe tree --json |
дерево пакетов | документ JSON Schema, package-tree.schema.v1.json |
vibe doc manifest --json, vibe doc todo --format json, vibe doc surface --record |
манифест страниц пакета документации, очередь сопровождения, снимок поверхности версии и диф двух снимков | doc_manifest.jtd.json, doc_todo.jtd.json, doc_surface.jtd.json, doc_surface_diff.jtd.json |
10Поля каждой схемы из таблицы, сгенерированные из файлов схем в порядке выше:
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32У документов сервера индекса, контракта и плана зачистки (scrape), трассы компилятора и нативного ABI есть собственные схемы в той же папке; реестр перечисляет их все.
Особые случаи и правила
33Документ, который не описывает ни одна схема, — дефект, а не задумка; кампания, которая писала это руководство, занесла найденные в бэклог продукта, а примеры на этих страницах помечают такие документы как непроверенные, а не как прошедшие.
34Форматы несут эпоху; пока продукт ещё не публичен, несовместимое изменение формата бесплатно и без миграции, и реестр так и говорит. Опубликованный формат меняется только с заметкой о разрыве и, где нужно, с миграцией.
35 spec: vibe.toml is the most expensive format…
6.2 vibe.toml is the most expensive format in the
system — authored, unrecoverable, resident in foreign repositories, and an
external surface de facto because agents read files, not APIs. It is the one
place we honestly pay the stability tax: an epoch marker in the file,
introduced before first publication (absence ≠ "assume 1"; absence is the
distinct pre-epoch state, interpreted by a heuristic exactly once in history);
strictness with did-you-mean hints in our namespace (in a hand-written file an
unknown key is a typo and the author is present — the asymmetry with the
machine-written catalog is principled, not inconsistent); a named reserve
section we never touch; a generated projection as the published copy, so
foreign tools read a recoverable artifact while the hand-written original
remains our internal concern; migration by codemod + bot PR; and a minimal
surface — every new manifest key is a years-long obligation and requires a
break note, a codemod, and generated documentation.
36Сырой разбор инструментами оболочки считается парсером: реестр предполагает, что кто-то направляет отчёт в JSON-инструмент, и относится к формату соответственно.
37 spec: Foreign curl | jq will happen…
Foreign curl | jq will happen regardless of
generated clients, and there will never be a signal of it (raw files in git
give no telemetry, by design). The honest posture: assume raw parsing exists,
keep the narrow gate genuinely boring, and treat any change to it at the
highest severity class.