@llmguard/opencode 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -333
- package/bin/manifest.json +1 -1
- package/package.json +3 -5
- package/MANUAL-TEST-G.md +0 -167
- package/RELEASE.md +0 -122
package/README.md
CHANGED
|
@@ -1,335 +1,54 @@
|
|
|
1
1
|
# LLMGuard для OpenCode
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
Сборка не меняет пользовательскую конфигурацию, trust и credentials.
|
|
56
|
-
Версия готового пакета берётся из native `package.json`; build ничего не публикует.
|
|
57
|
-
Корневой `dist/opencode/package/index.js` — native v2 server, `tui.js` — TUI.
|
|
58
|
-
Для v1 loader используется `plugin.js`; программный facade — `@llmguard/opencode/v1`.
|
|
59
|
-
Каталог `native` остаётся совместимым вариантом с парой entrypoints.
|
|
60
|
-
|
|
61
|
-
## Готовый архив
|
|
62
|
-
|
|
63
|
-
```sh
|
|
64
|
-
npm ci --ignore-scripts
|
|
65
|
-
sh scripts/build-ts.sh # tsc + GUI (vite) -> dist/build
|
|
66
|
-
scripts/build.sh --all --output dist/artifacts # шесть helper-ов, CGO=0 (или --target linux/amd64)
|
|
67
|
-
go run ./tools/pack pack # dist/package, dist/llmguard-opencode-<version>.tgz и .zip (+ .sha256)
|
|
68
|
-
go run ./tools/pack verify dist/llmguard-opencode-<version>.tgz
|
|
69
|
-
go run ./tools/pack verify --smoke dist/llmguard-opencode-<version>.zip
|
|
70
|
-
scripts/check.sh # всё выше плюс Go/TS тесты, lint, typecheck
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Нужны Go 1.27, Node.js 24 и npm 11. `dist/build` — TS-only staging; `dist/package` — npm tree (из него собран `.tgz`);
|
|
74
|
-
`.zip` — portable native plugin (только native v2 graph). `pack` ничего не компилирует: проверяет каждый helper по Go build
|
|
75
|
-
info (entrypoint, OS/CPU, без cgo), требует все шесть целей и отказывается
|
|
76
|
-
от helper-а, собранного против локального core (`--release`). Package-only не исправляет missing/stale inputs.
|
|
77
|
-
|
|
78
|
-
ZIP содержит JavaScript и готовые CGO=0 helpers для linux/darwin/windows ×
|
|
79
|
-
amd64/arm64, manifest helper и Go license. Go и npm-зависимости в runtime
|
|
80
|
-
не нужны. Версия берётся из `package.json`. Native execution пока проверен
|
|
81
|
-
только на linux/amd64; остальные платформы и musl unverified.
|
|
82
|
-
Архив содержит native `index.js`/`tui.js`/`gui-experimental.cjs`, граф runtime, `INSTALL.md`, пример
|
|
83
|
-
конфигурации, README и manifest с SHA-256 файлов. V1 и dev-зависимости исключены.
|
|
84
|
-
Сборка проверяет автономный импорт и запуск helper за пределами checkout; вручную можно запустить
|
|
85
|
-
`node verify.mjs` в распакованном каталоге (Node.js 24).
|
|
86
|
-
В `plugins` указывается распакованный корень пакета. Сборка не устанавливает
|
|
87
|
-
и не активирует плагин; публикация не выполняется.
|
|
88
|
-
|
|
89
|
-
## Меню `/llmguard`
|
|
90
|
-
|
|
91
|
-
TUI открывает расширенный штатный диалог (до 116 колонок, с ограничением
|
|
92
|
-
по доступной ширине терминала) со списком подключений: название, сервер, сокращённый SID,
|
|
93
|
-
наличие сохранённого ключа и отметка активного подключения. Поиск работает по
|
|
94
|
-
названию, полному адресу и полному SID. Выбор строки не меняет маршрут.
|
|
95
|
-
|
|
96
|
-
- **Ctrl+S** проверяет выбранное подключение и при успехе применяет его и включает
|
|
97
|
-
защиту для всех сессий сервера. Ошибка проверки оставляет активное подключение.
|
|
98
|
-
- **Enter** открывает редактор выбранного подключения, **Ctrl+N** создаёт новое.
|
|
99
|
-
Поля редактируются в произвольном порядке. Сохранение каталога не меняет
|
|
100
|
-
активный runtime snapshot. Escape сохраняет несекретный черновик до выгрузки TUI.
|
|
101
|
-
- **Ctrl+T** проверяет выбранное подключение без сохранения и переключения.
|
|
102
|
-
Используется отдельный Go helper и фиксированный тестовый текст; решение `deny`
|
|
103
|
-
не означает обрыв связи.
|
|
104
|
-
- **Ctrl+D** предлагает отключить защиту для всех сессий этого сервера.
|
|
105
|
-
- **Ctrl+R**, когда есть черновик, возвращает к его редактированию.
|
|
106
|
-
|
|
107
|
-
Ключ вводится обычным видимым prompt и сохраняется в локальном plugin storage
|
|
108
|
-
серверного OpenCode вместе с профилем. Это открытый текст, не системный keyring.
|
|
109
|
-
После перезапуска восстанавливаются ключи сохранённых профилей и отдельный
|
|
110
|
-
snapshot активного маршрута. Пустой ввод оставляет ключ именно этого подключения.
|
|
111
|
-
Полные ключи не возвращаются клиенту и не записываются в историю модели или логи.
|
|
112
|
-
В поле сохранённого ключа показываются первые четыре и последние два символа
|
|
113
|
-
через многоточие; ключи короче 10 символов полностью маскируются.
|
|
114
|
-
Каталог поддерживает до 100 подключений.
|
|
115
|
-
Существующее подключение показывается как OpenCode без записи при чтении.
|
|
116
|
-
|
|
117
|
-
Ключи и HTTP-проверки принадлежат Go helper; TUI управляет только настройками.
|
|
118
|
-
URL может включать префикс reverse proxy. При настройке через окружение редактирование
|
|
119
|
-
и переключение каталога недоступны. Если защита включена, но конфигурация потеряла
|
|
120
|
-
ключ, операции остаются заблокированными до исправления или явного отключения.
|
|
121
|
-
Неизвестный результат записи не повторяется автоматически; устаревшая ревизия
|
|
122
|
-
каталога отклоняется, черновик сохраняется. Desktop использует тот же каталог и те же RPC подключения; сохранение проекта
|
|
123
|
-
в обоих интерфейсах не меняет активный runtime snapshot.
|
|
124
|
-
|
|
125
|
-
SDK TUI 2.2.5 не предоставляет API языка: RU/EN автоматически выбираются по
|
|
126
|
-
локали терминального клиента (`LC_ALL`, `LC_MESSAGES`, `LANG`), английский — fallback.
|
|
127
|
-
Тема, поиск, фокус и клавиатурная навигация принадлежат штатному диалогу OpenCode.
|
|
128
|
-
В списке Ctrl-команды имеют приоритет перед командами поиска; при переходе
|
|
129
|
-
в редактор или закрытии списка этот перехват отключается.
|
|
130
|
-
Клавиатурные footer actions требуют поддержки соответствующего API хостом;
|
|
131
|
-
проверка типов SDK не заменяет приёмку на установленном OpenCode.
|
|
132
|
-
|
|
133
|
-
TUI и Desktop используют одно серверное подключение, сохранённый ключ и
|
|
134
|
-
переключатель защиты для всех проектов. Каждый location сохраняет собственные
|
|
135
|
-
restoration maps и audit cwd. Новые location сразу используют текущее подключение.
|
|
136
|
-
Закрытие или отключение UI не выключает защиту для других клиентов. Выключайте
|
|
137
|
-
её явным переключателем LLMGuard; последний выгруженный server instance освобождает helper.
|
|
138
|
-
Настройки передаются отдельным RPC и не отправляются как prompt модели.
|
|
139
|
-
|
|
140
|
-
Для ключа после рестартов можно использовать окружение **серверного** процесса:
|
|
141
|
-
`LLMGUARD_TOKEN` либо совместимый `LLMGUARD_API_KEY`. Введённый через TUI ключ имеет
|
|
142
|
-
приоритет и сохраняется после перезапуска. URL/SID также можно задать через `LLMGUARD_BASE_URL` и
|
|
143
|
-
`LLMGUARD_PROJECT_SID`; тогда оба берутся из окружения и редактирование профиля
|
|
144
|
-
заблокировано. `LLMGUARD_ALLOW_LOOPBACK_HTTP=true` явно разрешает локальный HTTP.
|
|
145
|
-
`LLMGUARD_TIMEOUT_MS` задаёт таймаут Guard-check (по умолчанию 10000; максимум 180000) — для развёртываний, где модельный PII-анализ на CPU занимает дольше
|
|
146
|
-
стандартного лимита; иначе длинные проверки завершаются fail-closed.
|
|
147
|
-
Частичная пара URL/SID не дополняется сохранёнными значениями.
|
|
148
|
-
|
|
149
|
-
При удалённом сервере `/llmguard` использует его location и RPC: профиль и ключ
|
|
150
|
-
применяются на сервере, не на машине терминала. Никакие настройки реального
|
|
151
|
-
OpenCode автоматически не устанавливаются и не активируются.
|
|
152
|
-
|
|
153
|
-
## OpenCode Desktop
|
|
154
|
-
|
|
155
|
-
Один пакет включает сервер, TUI и GUI. Для Desktop с GUI API SDK 2.2.5 добавьте
|
|
156
|
-
пакет в `plugins` глобального `~/.config/opencode/opencode.json(c)`.
|
|
157
|
-
Откройте Settings → LLMGuard или команду «LLMGuard: настройки и статус».
|
|
158
|
-
|
|
159
|
-
Desktop использует общий с TUI серверный каталог подключений. Слева — поиск
|
|
160
|
-
по названию, полному URL и полному SID, название, сервер, сокращённый SID,
|
|
161
|
-
наличие ключа и отметка активного проекта. Справа — открытый редактор;
|
|
162
|
-
при ширине области меньше 620 px он переносится под список. Язык RU/EN и тема
|
|
163
|
-
наследуются от клиента, отдельного переключателя языка нет.
|
|
164
|
-
|
|
165
|
-
Выбор строки только открывает её редактор. «Сохранить» обновляет каталог,
|
|
166
|
-
«Подключить» сначала проверяет сохранённый проект через Go helper и затем
|
|
167
|
-
применяет его ко всем сессиям сервера. «Проверить» в подвале не меняет маршрут.
|
|
168
|
-
Тест отправляет только фиксированный текст, без содержимого сессий.
|
|
169
|
-
Подвал всегда показывает активный маршрут, состояние защиты и результат операции.
|
|
170
|
-
«Отключить» требует подтверждения: запросы всех сессий этого сервера пойдут без Guard.
|
|
171
|
-
|
|
172
|
-
Ключ сохраняется в локальном plugin storage серверного OpenCode; в browser storage или chat он не записывается. Новый проект требует
|
|
173
|
-
ключ; пустой ключ при редактировании сохраняет ключ только этого проекта.
|
|
174
|
-
Поле очищается сразу при отправке и при выгрузке UI. Сервер не возвращает ключи.
|
|
175
|
-
|
|
176
|
-
Фоновое чтение каждые пять секунд сохраняет черновик. Смена выбранного проекта,
|
|
177
|
-
создание нового и отмена изменённого черновика требуют подтверждения сброса.
|
|
178
|
-
При изменении каталога другим клиентом устаревший черновик нельзя сохранить:
|
|
179
|
-
нужно отменить его и проверить актуальные данные. При неизвестном результате
|
|
180
|
-
записи форма не повторяет запрос автоматически; проверьте список перед повтором.
|
|
181
|
-
Если поиск скрывает выбранный проект, его нельзя проверить или подключить.
|
|
182
|
-
|
|
183
|
-
Настройки обращаются к серверу приложения напрямую, без выбора проекта OpenCode
|
|
184
|
-
или открытой сессии. Подключение и защита общие с TUI, подключённым к этому серверу.
|
|
185
|
-
GUI API экспериментальный: unit-тесты и браузерная демонстрация с подставными
|
|
186
|
-
host components не заменяют проверку на реальном Desktop. Native Desktop
|
|
187
|
-
покрытие запросов модели по этой проверке не подтверждалось.
|
|
188
|
-
|
|
189
|
-
## Адресное маскирование OpenCode 2
|
|
190
|
-
|
|
191
|
-
Hooks `context`, `compaction`, `generate`, `title` отправляют `model.before` с
|
|
192
|
-
проекцией `{texts: [...]}` и применяют только авторизованный кандидат к выбранным
|
|
193
|
-
строкам:
|
|
194
|
-
|
|
195
|
-
- `system[].text`;
|
|
196
|
-
- текст и reasoning в `messages[].content`, текстовая compaction summary;
|
|
197
|
-
- строки аргументов `tool-call.input`;
|
|
198
|
-
- текст/JSON/error value в `tool-result.result`, только текстовые элементы content.
|
|
199
|
-
|
|
200
|
-
`tool.execute.before` восстанавливает известные bindings этой сессии и проверяет
|
|
201
|
-
выбранные строковые аргументы через `tool.before` с `tool_input: {texts: [...]}`.
|
|
202
|
-
Для этого события OpenCode rules-engine сохраняет оригиналы при срабатывании
|
|
203
|
-
`mask`: маскирование защищает границу модели и не меняет локальные записи файлов
|
|
204
|
-
или аргументы инструментов. Правила `block`, ошибки и неполное покрытие продолжают
|
|
205
|
-
запрещать выполнение; исходные аргументы проверяются до запуска инструмента.
|
|
206
|
-
Результат инструмента снова маскируется перед следующим запросом к модели.
|
|
207
|
-
Числа и другие значения не сериализуются и не заменяются. `tool.execute.after`
|
|
208
|
-
только наблюдает: результат или сообщение ошибки записывается в Guard, но
|
|
209
|
-
никогда не блокирует, не скрывает и не «отменяет» уже выполненное действие
|
|
210
|
-
(как PostToolUse у Codex). Deny здесь — только запись в историю; маскирование
|
|
211
|
-
результата происходит в следующем `model.before`, который снова проверяет
|
|
212
|
-
выбранный текст перед моделью.
|
|
213
|
-
|
|
214
|
-
При `model.before` плагин добавляет bound
|
|
215
|
-
`source_payload.text_layout` (`version: 1`, `items: [{role, kind}]`),
|
|
216
|
-
выровненный по позициям `texts`: system/compaction-summary → `system/context`
|
|
217
|
-
(включая сообщения с ролью `system` внутри `messages`),
|
|
218
|
-
прежние сообщения → `history` (tool-result и сообщения с ролью `tool` → `tool`), а последний текст
|
|
219
|
-
последнего user-сообщения → `current_prompt`. Это позволяет истории Guard
|
|
220
|
-
показывать ввод пользователя как активное сообщение, а не инструкции или
|
|
221
|
-
контекст. Если user-текста в запросе нет или роль сообщения неизвестна,
|
|
222
|
-
метаданные не отправляются и действует прежнее поведение. Валидация схемы —
|
|
223
|
-
в rules-engine; layout не входит в coverage и связан digest запроса.
|
|
224
|
-
|
|
225
|
-
Прочие поля, metadata, IDs, неизвестные типы частей, media, ссылки и бинарные
|
|
226
|
-
данные остаются без изменений. Они не заявляются как проверенные. Tool definitions,
|
|
227
|
-
provider options/headers, raw native/encrypted provider данные и изменения других
|
|
228
|
-
плагинов после нашего hook не входят в покрытие. Дополнительный prompt compaction,
|
|
229
|
-
который OpenCode добавляет после hooks, также не входит в отправленную проекцию.
|
|
230
|
-
Отказ, ошибка, timeout и неприменимый кандидат для выбранных полей прерывают hook.
|
|
231
|
-
|
|
232
|
-
Bindings живут в памяти: до удаления сессии, смены подключения или unload;
|
|
233
|
-
максимум 128 сессий, 4096 bindings и 1 MiB символов на сессию.
|
|
234
|
-
|
|
235
|
-
## Восстановление ответа модели (v2)
|
|
236
|
-
|
|
237
|
-
Hook `http.response` восстанавливает только точные bindings текущей сессии в
|
|
238
|
-
ответе провайдера до того, как OpenCode разберёт поток: TUI, локальная история и
|
|
239
|
-
аргументы инструментов получают исходные значения, а не маркеры. Условия:
|
|
240
|
-
HTTP 200 и `Content-Type` `application/json` или `text/event-stream`. Наличие
|
|
241
|
-
`Content-Encoding` не мешает: fetch-рантаймы распаковывают тело прозрачно,
|
|
242
|
-
оставляя заголовок, поэтому решение принимается по первому байту тела —
|
|
243
|
-
JSON/SSE-текст (`{`, `[`, `data:`/`event:`/`id:`/`retry:`/`:`/BOM/пробел)
|
|
244
|
-
демаскируется, а сжатые magic bytes и бинарные тела проходят без изменений.
|
|
245
|
-
SSE восстанавливается по декодированным delta-полям OpenAI Chat Completions,
|
|
246
|
-
Responses и Anthropic Messages. Маркер удерживается между SSE-событиями,
|
|
247
|
-
отдельно для каждого choice/item/block и текстового поля; сетевые чанки могут
|
|
248
|
-
иметь произвольные границы. JSON-ответ буферизуется в пределах лимита.
|
|
249
|
-
В обоих случаях
|
|
250
|
-
восстановленный plaintext никогда не интерпретируется как новый маркер, оригинал
|
|
251
|
-
вставляется с JSON-экранированием, а рост тела ограничен. Из ответа убираются
|
|
252
|
-
`Content-Length`, `Content-MD5`, `Digest`, `ETag` и ставится `Cache-Control:
|
|
253
|
-
no-store`.
|
|
254
|
-
|
|
255
|
-
Если ответ нельзя восстановить (не 200, сжатие, другой media type, hook не
|
|
256
|
-
вызван для провайдера), ответ проходит без изменений — **маркеры остаются
|
|
257
|
-
видимыми**, блокировки нет. Диагностика hook'ов пишется в
|
|
258
|
-
`~/.local/share/opencode/log/llmguard-hooks.log` (путь можно переопределить
|
|
259
|
-
`LLMGUARD_TRACE_FILE`): только время, hook и код причины (`no_bindings`,
|
|
260
|
-
`media=…`, `binary_body`, `no_token_in_body`, `demasked=N`, …) — без содержимого
|
|
261
|
-
сообщений и секретов. Для диагностики разметки каждый HTTP-ответ получает
|
|
262
|
-
случайный `response` ID. Записи `markup channel=answer|reasoning|snapshot`
|
|
263
|
-
показывают флаги `before/after` для system-reminder, message, conversation и
|
|
264
|
-
инструкции заголовка: `1/1` — присутствовало до и после, `0/1` — появилось
|
|
265
|
-
после обработки. Сравниваются декодированные текстовые поля с учётом границ
|
|
266
|
-
delta; тексты, токены и ID сессий не записываются. `markup_complete` и число
|
|
267
|
-
наблюдавшихся полей позволяют отличить проверенный поток от неподдержанного
|
|
268
|
-
или неразобранного ответа. Диагностика завершается на terminal SSE-событии либо
|
|
269
|
-
при закрытии тела; отменённый раньше поток может не иметь итоговой записи.
|
|
270
|
-
`title.result` и `compaction.result`, выставленные
|
|
271
|
-
другим плагином, восстанавливаются из bindings перед сохранением. Маркеры в
|
|
272
|
-
аргументах инструментов дополнительно восстанавливаются перед новой проверкой
|
|
273
|
-
Guard (`tool.execute.before`). Строковые JSON-аргументы инструментов
|
|
274
|
-
(`arguments`/`partial_json`) остаются замаскированными в HTTP-ответе:
|
|
275
|
-
восстановление выполняется после разбора, перед проверкой инструмента.
|
|
276
|
-
JSON-экранированные маркеры (включая `\u003c`) поддерживаются в текстовых полях.
|
|
277
|
-
Переполнение лимита после начала чтения завершает поток ошибкой.
|
|
278
|
-
WebSocket-ответы и другие форматы delta не покрыты этим HTTP hook.
|
|
279
|
-
Реальная приёмка на установленном OpenCode 2 с
|
|
280
|
-
SSE-провайдером не выполнялась.
|
|
281
|
-
|
|
282
|
-
## Существующий OpenCode 1 entrypoint
|
|
283
|
-
|
|
284
|
-
`dist/opencode/package/plugin.js` сохраняет v1 hooks: messages/system transform, before/after tool
|
|
285
|
-
и text.complete. У него конфигурация через окружение, без нового TUI. В v1
|
|
286
|
-
text.complete восстанавливает bound tokens в завершённом тексте; это не проверка
|
|
287
|
-
финального ответа Guard. Формат конфигурации v1 — `plugin` с file URL к файлу,
|
|
288
|
-
а не v2 `plugins` с путём к каталогу.
|
|
289
|
-
|
|
290
|
-
## Проверки и границы приёмки
|
|
291
|
-
|
|
292
|
-
```sh
|
|
293
|
-
scripts/check.sh
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
Проверяются меню и отмена ввода, RPC, серверные настройки, отсутствие ключа в
|
|
297
|
-
storage/ответах, реальный Guard HTTP transport с локальным сервером, deny/error,
|
|
298
|
-
coverage, correlation, авторизованные замены и сохранение непроецируемых полей.
|
|
299
|
-
Для developer tests нужны Go 1.27 и Node 24 в PATH; `scripts/check.sh` явно готовит helper/package один раз; скрытого npm pretest нет. Сетевым тестам нужен loopback. Проверка типов официального SDK и callback-тесты
|
|
300
|
-
не заменяют реальную приёмку в установленном OpenCode 2 с моделью; она пока не
|
|
301
|
-
выполнена. Пакет не устанавливался и не активировался.
|
|
302
|
-
|
|
303
|
-
Источники: [OpenCode 2 plugins](https://dev.opencode.ai/v2/docs/build/plugins),
|
|
304
|
-
[TUI API](https://dev.opencode.ai/v2/docs/build/plugins/cli),
|
|
305
|
-
[RPC](https://dev.opencode.ai/v2/docs/build/plugins/rpc/),
|
|
306
|
-
[переход v1 → v2](https://dev.opencode.ai/v2/docs/build/plugins/migrate-v1).
|
|
307
|
-
[opencode-vibeguard](https://github.com/inkdust2021/opencode-vibeguard) использован
|
|
308
|
-
как референс точек v1-перехвата; его локальные правила и детекторы не перенесены.
|
|
309
|
-
|
|
310
|
-
## Изменения прямого API в 0.1.0
|
|
311
|
-
|
|
312
|
-
`@llmguard/opencode` экспортирует default native v2 server. `createOpenCodeHooks`,
|
|
313
|
-
`OpenCodeGuardError` и тип `PluginOptions` доступны через `@llmguard/opencode/v1`. Удалены `GuardClient`, `ClientError`,
|
|
314
|
-
`Operation`, `RunnerError`, `decodeRequest`/`decodeResponse`, `validateResult`,
|
|
315
|
-
`restorationValues`, `requestDigest`, `sameShape`, wire DTO/core interfaces и
|
|
316
|
-
связанные constants. Это breaking change для прямых пользователей прежнего
|
|
317
|
-
core facade. Подмены старых классов с изменённым sync/async contract нет.
|
|
318
|
-
Release version вручную задаётся в package.json; npm metadata имеет private:false,
|
|
319
|
-
root/test workspaces остаются private. Это не выполняет публикацию; таблица exports — в RELEASE.md.
|
|
320
|
-
|
|
321
|
-
Generic JSON codec/NumberToken, limits, session maps и provider restoration
|
|
322
|
-
остаются внутренними runtime-модулями, без package exports. Native v1/v2 hooks
|
|
323
|
-
используют bundled Go helper; fallback в TS при отказе helper отсутствует.
|
|
324
|
-
TLS проверяет Go: `NODE_EXTRA_CA_CERTS` больше не настраивает Guard transport;
|
|
325
|
-
для собственного CA используйте доверенное хранилище сертификатов на стороне
|
|
326
|
-
сервера OpenCode. Установку собственного CA эта сборка не выполняет.
|
|
327
|
-
|
|
328
|
-
Текущая ручная матрица: [MANUAL-TEST-G.md](MANUAL-TEST-G.md).
|
|
329
|
-
|
|
330
|
-
Системные hooks v1 и v2 добавляют общую инструкцию LLMGuard о точном копировании
|
|
331
|
-
маркеров, включая обе угловые скобки, до проверки Guard. Инструкция проверяется
|
|
332
|
-
и применяется вместе с остальным системным текстом; пустой system также поддержан.
|
|
333
|
-
Это подсказка модели, а не гарантия сохранности произвольно изменённых маркеров.
|
|
334
|
-
|
|
335
|
-
Версия принадлежит целому пакету и берётся из `package.json`. Helper не содержит встроенной версии и не согласовывает её через IPC; для аудита он читает манифест своего пакета. Комплектность бинарников проверяется по хешам.
|
|
3
|
+
Плагин проверяет текст модельных запросов и вызовы инструментов через LLMGuard.
|
|
4
|
+
Guard определяет, разрешить, замаскировать или заблокировать данные. OpenCode 2
|
|
5
|
+
локально восстанавливает известные маркеры текущей сессии в поддерживаемых JSON
|
|
6
|
+
и SSE-ответах, а в аргументах инструментов — перед проверкой вызова.
|
|
7
|
+
|
|
8
|
+
Маскирование применяется к поддерживаемым текстовым полям. Метаданные, числа и
|
|
9
|
+
неизвестные части проходят без проверки. Если формат ответа вне области
|
|
10
|
+
восстановления, маркеры остаются видимыми. Наблюдение после выполнения инструмента
|
|
11
|
+
не отменяет выполненное действие.
|
|
12
|
+
|
|
13
|
+
В настройках можно включить проверку вложений через Guard file API. Плагин
|
|
14
|
+
применяет разрешённое маскирование к простым текстовым файлам, если их можно
|
|
15
|
+
безопасно заменить. В остальных случаях требование замаскировать вложение
|
|
16
|
+
блокирует запрос.
|
|
17
|
+
|
|
18
|
+
## Подключение в OpenCode 2
|
|
19
|
+
|
|
20
|
+
1. Распакуйте ZIP релиза в постоянный каталог. Добавьте абсолютный путь корня
|
|
21
|
+
пакета в массив `plugins` файла `opencode.json` или `opencode.jsonc`.
|
|
22
|
+
Готовый пример находится в `opencode.example.json`. Для удалённого OpenCode
|
|
23
|
+
распакуйте пакет и измените настройки на сервере.
|
|
24
|
+
2. Перезапустите OpenCode. Откройте `/llmguard` в TUI или **Settings → LLMGuard**
|
|
25
|
+
в Desktop, если его экспериментальный GUI API совместим с SDK 2.2.5.
|
|
26
|
+
3. Добавьте URL Guard, SID проекта и ключ. HTTPS используется по умолчанию.
|
|
27
|
+
В TUI используйте **Ctrl+N** для добавления, **Ctrl+T** для проверки и
|
|
28
|
+
**Ctrl+S** для подключения и включения защиты. В Desktop используйте
|
|
29
|
+
отдельные кнопки проверки и подключения.
|
|
30
|
+
|
|
31
|
+
Защита включается явно и применяется ко всем сессиям сервера OpenCode.
|
|
32
|
+
Сохранение изменений в каталоге оставляет активное подключение до повторного
|
|
33
|
+
подключения. Ключ хранится в серверном хранилище плагина без шифрования.
|
|
34
|
+
Для отключения защиты используйте действие LLMGuard (**Ctrl+D** в TUI).
|
|
35
|
+
Закрытие TUI, Desktop или отключение расширения GUI оставляет серверную
|
|
36
|
+
настройку активной.
|
|
37
|
+
|
|
38
|
+
ZIP содержит готовые бинарники. Подтверждён запуск helper на Linux x64.
|
|
39
|
+
Нативная приёмка остальных систем, Desktop и реальных SSE-провайдеров
|
|
40
|
+
остаётся отдельной проверкой. Целостность ZIP можно проверить через
|
|
41
|
+
`node verify.mjs` в распакованном каталоге с Node.js 24.
|
|
42
|
+
|
|
43
|
+
## OpenCode 1 и программный API
|
|
44
|
+
|
|
45
|
+
Для OpenCode 1 используйте npm-поставку `@llmguard/opencode` с legacy entrypoint
|
|
46
|
+
`plugin.js`. В OpenCode 1 настройка `plugin` принимает file URL к entrypoint.
|
|
47
|
+
Конфигурация Guard задаётся через окружение `LLMGUARD_BASE_URL`,
|
|
48
|
+
`LLMGUARD_PROJECT_SID` и `LLMGUARD_TOKEN`.
|
|
49
|
+
|
|
50
|
+
С версии 0.1.0 корневой импорт указывает на сервер OpenCode 2, а
|
|
51
|
+
`createOpenCodeHooks`, `OpenCodeGuardError` и `PluginOptions` доступны из
|
|
52
|
+
`@llmguard/opencode/v1`. `createOpenCodeHooks` принимает только `options`.
|
|
53
|
+
Прежние экспорты внутреннего Guard API удалены. Для v2 доступны subpaths
|
|
54
|
+
`/server`, `/tui` и `/rpc` (`/settings-rpc` остаётся алиасом).
|
package/bin/manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"description": "
|
|
2
|
+
"description": "Checks OpenCode model requests and tool calls with Guard, masks supported text, and restores known values in supported responses.",
|
|
3
3
|
"engines": {
|
|
4
4
|
"node": "\u003e=24 \u003c25"
|
|
5
5
|
},
|
|
@@ -39,13 +39,11 @@
|
|
|
39
39
|
"**/*.js",
|
|
40
40
|
"**/*.d.ts",
|
|
41
41
|
"bin/**",
|
|
42
|
-
"licenses/**"
|
|
43
|
-
"MANUAL-TEST-G.md",
|
|
44
|
-
"RELEASE.md"
|
|
42
|
+
"licenses/**"
|
|
45
43
|
],
|
|
46
44
|
"license": "UNLICENSED",
|
|
47
45
|
"name": "@llmguard/opencode",
|
|
48
46
|
"private": false,
|
|
49
47
|
"type": "module",
|
|
50
|
-
"version": "0.1.
|
|
48
|
+
"version": "0.1.1"
|
|
51
49
|
}
|
package/MANUAL-TEST-G.md
DELETED
|
@@ -1,167 +0,0 @@
|
|
|
1
|
-
# Ручная приёмка OpenCode с Go core
|
|
2
|
-
|
|
3
|
-
Текущая ручная матрица для OpenCode 0.1.0 с Go core; имя файла сохранено для
|
|
4
|
-
существующих ссылок. [RELEASE.md](RELEASE.md) описывает exports и упаковку.
|
|
5
|
-
Root entrypoint — native v2; программный v1 facade доступен через ./v1.
|
|
6
|
-
Старая установленная копия новой сборкой не обновляется.
|
|
7
|
-
|
|
8
|
-
Это инструкция, не отчёт о пройденной полной live-матрице. Synthetic helper/npm/ZIP
|
|
9
|
-
acceptance проверен на linux/amd64; пользователь подтвердил работу обоих билдов,
|
|
10
|
-
но каждый сценарий ниже требует отдельного результата. Codex имеет свою приёмку.
|
|
11
|
-
|
|
12
|
-
## 1. Подготовить отдельный тестовый запуск
|
|
13
|
-
|
|
14
|
-
1. Используйте linux/amd64 и Node.js 24. Go для установленного плагина не нужен.
|
|
15
|
-
Native mapping проверен типами SDK `@opencode/plugin` 2.1.4; запишите фактическую
|
|
16
|
-
версию своего OpenCode. Другие версии, ОС/архитектуры и musl пока unverified.
|
|
17
|
-
2. Подготовьте отдельную тестовую папку/сессию и тестовый Guard project/key.
|
|
18
|
-
Используйте только вымышленные строки и безвредные команды.
|
|
19
|
-
3. Зафиксируйте политику тестового проекта: какой synthetic input должен получить
|
|
20
|
-
allow, deny и transform. Например, настройте блокировку строки
|
|
21
|
-
`LLMGUARD_MANUAL_DENY_20261028` и маскирование тестового телефона `2025550147`.
|
|
22
|
-
Эти строки сами по себе не создают правил: ожидаемый результат должен следовать
|
|
23
|
-
из реально настроенной политики. Если детектору нужен иной synthetic sample,
|
|
24
|
-
используйте его и запишите ожидаемый результат. Политику не меняет плагин.
|
|
25
|
-
4. Для доказательства маскирования нужен доступ к безопасному тестовому provider
|
|
26
|
-
request capture или контролируемому mock provider. Экран чата и финальный
|
|
27
|
-
ответ сами по себе не доказывают, что provider не получил оригинал.
|
|
28
|
-
|
|
29
|
-
## 2. Распаковать и подключить свежий архив
|
|
30
|
-
|
|
31
|
-
Из корня checkout можно пересобрать архив:
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
sh scripts/build-ts.sh && scripts/build.sh --all --output dist/artifacts && go run ./tools/pack pack
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
Свежий архив — `dist/llmguard-opencode-<version>.zip`.
|
|
38
|
-
Распакуйте в новый отдельный каталог, например `/tmp/llmguard-manual/opencode-0.1.0`.
|
|
39
|
-
Сохраните executable permissions. Внутри находятся `index.js`, `tui.js`,
|
|
40
|
-
`runtime/bin` и manifest.
|
|
41
|
-
|
|
42
|
-
В распакованном корне выполните:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
node verify.mjs
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
Ожидается exit 0 и сообщение `files, entrypoints, codec and bundled helper verified`.
|
|
49
|
-
Это проверка файлов/handshake/локальной validation; она не обращается к Guard,
|
|
50
|
-
не включает защиту и не доказывает работу OpenCode hooks.
|
|
51
|
-
|
|
52
|
-
В конфигурации тестового OpenCode замените прежнюю запись LLMGuard абсолютным
|
|
53
|
-
путём нового распакованного корня:
|
|
54
|
-
|
|
55
|
-
```json
|
|
56
|
-
{
|
|
57
|
-
"plugins": ["/tmp/llmguard-manual/opencode-0.1.0"]
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
Сохраните другие plugins/settings. Не подключайте одновременно старую и новую
|
|
62
|
-
копии LLMGuard. Полностью остановите и запустите сервер OpenCode и TUI:
|
|
63
|
-
обычное переподключение TUI не доказывает загрузку новой сборки. Для удалённого OpenCode каталог и ключ должны находиться на его сервере.
|
|
64
|
-
Для native v2 выбирайте корень готового ZIP или npm build; программный v1 facade
|
|
65
|
-
теперь находится в `v1.js`, loader — в `plugin.js`.
|
|
66
|
-
|
|
67
|
-
## 3. Настроить через `/llmguard`
|
|
68
|
-
|
|
69
|
-
1. Откройте `/llmguard`. На чистой настройке защита выключена. Если сохранён
|
|
70
|
-
прежний enabled=true, сначала явно выключите защиту.
|
|
71
|
-
2. В «Настроить подключение» введите origin rules-engine и SID тестового проекта.
|
|
72
|
-
Используйте HTTPS; для Guard по HTTP отдельно выберите «Разрешить HTTP».
|
|
73
|
-
3. В «Ключ Guard» введите тестовый ключ. Ввод открытый; ключ должен оставаться в
|
|
74
|
-
памяти server instance, а не в connection storage, сообщениях или диагностике.
|
|
75
|
-
4. Проверьте «Статус подключения» и «Проверить связь с Guard». Connected=true при
|
|
76
|
-
deny означает доступный Guard, принявший решение политики, а не сбой транспорта.
|
|
77
|
-
Probe использует фиксированный текст, не содержимое вашей сессии.
|
|
78
|
-
5. Если status сообщает environment override, URL/SID берутся из окружения сервера
|
|
79
|
-
(`LLMGUARD_BASE_URL`, `LLMGUARD_PROJECT_SID`). Уберите override в тестовом запуске
|
|
80
|
-
либо используйте нужный тестовый endpoint. Не публикуйте токены из окружения.
|
|
81
|
-
6. Явно выберите «Включить защиту». Редактирование подключения/ключа через TUI
|
|
82
|
-
предварительно выключает защиту; после успешной настройки включите её снова.
|
|
83
|
-
|
|
84
|
-
## 4. Матрица проверок
|
|
85
|
-
|
|
86
|
-
| Проверка | Действие | Что считается успехом |
|
|
87
|
-
| --------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
-
| Allow | Отправьте строку, которую тестовая политика разрешает | Запрос проходит; есть соответствующий Guard event |
|
|
89
|
-
| Deny | Отправьте настроенный deny canary | Операция блокируется; canary не отправляется provider; есть Guard deny |
|
|
90
|
-
| Transform | Попросите повторить настроенный synthetic phone | Исходящий provider request содержит masked token вместо телефона |
|
|
91
|
-
| Restoration | Provider возвращает тот же masked token как текст ответа | В ответе этой сессии восстанавливается synthetic phone; оригинал не берётся из token syntax |
|
|
92
|
-
| Session scope | В другой новой сессии верните token из предыдущей | Старый token не раскрывается через bindings другой сессии |
|
|
93
|
-
| Tool before | Попросите вызвать безвредный `printf`/аналог с разрешённым текстом, затем с deny canary | Разрешённый вызов проходит; запрещённый не исполняется. Не подменяйте проверку tool.before обычным model deny |
|
|
94
|
-
| Tool args restoration | Передайте bound token в аргумент безвредного tool | Известный token восстанавливается перед свежей проверкой Guard; разрешение прошлой проверки не переиспользуется |
|
|
95
|
-
| Tool after | Безвредный tool выдаёт synthetic sample | Уже выполненный tool не откатывается; его текст наблюдается Guard и проверяется при следующем model request |
|
|
96
|
-
| Disable | Выключите защиту и повторите deny canary | Guard check не блокирует новый запрос. Этот шаг может отправить canary provider, поэтому нужен только вымышленный текст |
|
|
97
|
-
| Enable again | Включите защиту и повторите deny canary | Блокировка возвращается |
|
|
98
|
-
|
|
99
|
-
Для model hooks ожидаются source event names `session.context`,
|
|
100
|
-
`session.compaction`, `session.generate`, `session.title`; для tools —
|
|
101
|
-
`tool.execute.before`/`tool.execute.after`. Не каждый prompt обязан вызвать все
|
|
102
|
-
четыре model hook. Отдельно инициируйте compaction/title/generate средствами
|
|
103
|
-
вашей версии OpenCode. Если hook не удалось вызвать/наблюдать, отметьте unverified.
|
|
104
|
-
|
|
105
|
-
Не оценивайте transform только по ответу модели: она может не повторить token,
|
|
106
|
-
изменить его или не вызвать tool. Нужны provider boundary и фактический Guard event.
|
|
107
|
-
Attachments, media, metadata и числовые поля не должны переписываться; выберите
|
|
108
|
-
тест с такими полями, если ваша версия OpenCode позволяет их наблюдать.
|
|
109
|
-
|
|
110
|
-
## 5. Отказы и lifecycle
|
|
111
|
-
|
|
112
|
-
1. **Guard недоступен:** оставьте enabled=true, остановите только тестовый Guard
|
|
113
|
-
или используйте отдельный недоступный тестовый endpoint. Новый непустой
|
|
114
|
-
запрос должен блокироваться, а защита — оставаться включённой. Восстановите
|
|
115
|
-
Guard: повторный запрос должен проходить свежую проверку.
|
|
116
|
-
2. **Неверный ключ:** через TUI введите заведомо нерабочий тестовый ключ, снова
|
|
117
|
-
включите защиту. Probe/content не должны получать успешный allow из старого
|
|
118
|
-
подключения. Верните правильный ключ; включите защиту снова.
|
|
119
|
-
3. **Helper недоступен:** используйте только отдельную распакованную тестовую
|
|
120
|
-
копию. При работающем тестовом OpenCode, валидном подключении и enabled=true
|
|
121
|
-
переименуйте её `runtime/bin/linux-amd64/helper`, затем завершите только helper
|
|
122
|
-
PID этого экземпляра (например SIGTERM). Определите PID по полному пути и
|
|
123
|
-
родительскому процессу; не используйте массовый `pkill helper`. Новый непустой
|
|
124
|
-
запрос должен блокироваться, защита — оставаться включённой, TS fallback —
|
|
125
|
-
отсутствовать. Восстановите прежнее имя бинарника и полностью перезапустите
|
|
126
|
-
OpenCode: число автоматических рестартов ограничено. Пока имя изменено,
|
|
127
|
-
checksum verification ожидаемо не пройдёт. Не пытайтесь воспроизвести этот
|
|
128
|
-
случай простым закрытием TUI: его cleanup явно выключает защиту, и это уже
|
|
129
|
-
другой сценарий.
|
|
130
|
-
4. **Смена ключа/подключения:** после успешного transform смените ключ/профиль,
|
|
131
|
-
повторно включите защиту. Старый token не должен раскрыться через старые maps;
|
|
132
|
-
новый исходящий запрос должен пройти свежий Guard check.
|
|
133
|
-
5. **Перезапуск:** без `LLMGUARD_TOKEN`/`LLMGUARD_API_KEY` сессионный ключ теряется,
|
|
134
|
-
URL/SID и explicit enabled state сохраняются. При enabled=true и отсутствии
|
|
135
|
-
ключа содержимое блокируется до настройки или явного disable. С environment
|
|
136
|
-
key соединение настраивается заново, но bindings предыдущего процесса не живут.
|
|
137
|
-
6. **Unload:** отключение TUI plugin выключает защиту на том же server location;
|
|
138
|
-
полное завершение server plugin завершает его helper. Проверьте отсутствие
|
|
139
|
-
оставшегося helper этого экземпляра после остановки OpenCode.
|
|
140
|
-
|
|
141
|
-
Если Guard работает дольше 10 секунд, задайте `LLMGUARD_TIMEOUT_MS` в окружении
|
|
142
|
-
тестового сервера (например `30000`, максимум `180000`) и перезапустите его.
|
|
143
|
-
Нужный budget выбирается явно, таймаут не разрешает исходный запрос. При timeout
|
|
144
|
-
ожидается блокировка; повторный ручной запрос должен создавать новую проверку.
|
|
145
|
-
|
|
146
|
-
## 6. Что прислать для разбора
|
|
147
|
-
|
|
148
|
-
Для каждого случая запишите: actual OpenCode/Node/OS версии, hash архива,
|
|
149
|
-
сценарий, ожидаемый/фактический результат, был ли tool исполнен, подтверждён ли
|
|
150
|
-
provider boundary и Guard event. Секреты, исходные чувствительные данные и
|
|
151
|
-
полные provider payloads не нужны. Достаточно synthetic sample и correlation IDs.
|
|
152
|
-
|
|
153
|
-
Локальная диагностика — `${XDG_DATA_HOME:-~/.local/share}/opencode/log/llmguard-hooks.log`
|
|
154
|
-
либо явно заданный `LLMGUARD_TRACE_FILE`. Там только kinds/reason codes; наличие
|
|
155
|
-
записи само по себе не доказывает блокировку provider. Статусы каждого случая:
|
|
156
|
-
passed / failed / unverified. Результат текущей synthetic приёмки не переносится
|
|
157
|
-
на ручные проверки автоматически.
|
|
158
|
-
|
|
159
|
-
## Desktop GUI (native acceptance pending)
|
|
160
|
-
|
|
161
|
-
- Подключить собранный пакет глобально на Desktop с API SDK 2.2.5; проверить загрузку GUI и helper вне checkout.
|
|
162
|
-
- Открыть Settings → LLMGuard без активной сессии; сразу доступны поля подключения; проверить URL/SID/HTTP, скрытый ввод ключа, проверку связи, явное включение и выключение.
|
|
163
|
-
- Проверить allow/deny, masking/restoration запроса, stream ответа и tool args с реальным Guard.
|
|
164
|
-
- Открыть два проекта и TUI на одном сервере: ключ/подключение/переключатель общие, новый проект сразу защищён, закрытие одного UI не выключает защиту.
|
|
165
|
-
- Перейти из сессии в Settings: поля подключения доступны независимо от проекта; маскирование разных проектов не смешивает bindings и audit cwd.
|
|
166
|
-
- Проверить недоступный Guard, падение helper, отмену запроса, reload и restart сервера с потерей сессионного ключа.
|
|
167
|
-
- Проверить реальную установку на каждой заявляемой OS/CPU; cross-build и тесты не являются native acceptance.
|
package/RELEASE.md
DELETED
|
@@ -1,122 +0,0 @@
|
|
|
1
|
-
# Поставка OpenCode
|
|
2
|
-
|
|
3
|
-
Один npm tarball содержит JS/declarations, шесть CGO=0 Go helpers и
|
|
4
|
-
`bin/manifest.json` с версией, IPC major, target/size и SHA-256 каждого binary.
|
|
5
|
-
Toolchain и compile inputs остаются в private build.json.
|
|
6
|
-
Go и Codex на машине OpenCode не нужны. Install/postinstall scripts отсутствуют.
|
|
7
|
-
Hashes проверяют комплектность байтов, а не доверие к автору пакета.
|
|
8
|
-
|
|
9
|
-
## Migration 0.0.x → 0.1.0
|
|
10
|
-
|
|
11
|
-
| Import | API |
|
|
12
|
-
| --------------------------- | ----------------------------------------------------------- |
|
|
13
|
-
| `@llmguard/opencode` | default native v2 server |
|
|
14
|
-
| `@llmguard/opencode/server` | тот же default server |
|
|
15
|
-
| `@llmguard/opencode/tui` | default TUI |
|
|
16
|
-
| `@llmguard/opencode/rpc` | settingsRPC; `./settings-rpc` остаётся alias |
|
|
17
|
-
| `@llmguard/opencode/plugin` | единственный default function для v1 loader |
|
|
18
|
-
| `@llmguard/opencode/v1` | createOpenCodeHooks, OpenCodeGuardError, type PluginOptions |
|
|
19
|
-
|
|
20
|
-
Root exports GuardClient, Operation, validators и прежний root v1 facade удалены.
|
|
21
|
-
Перенесите программный import createOpenCodeHooks на `@llmguard/opencode/v1`.
|
|
22
|
-
Второй аргумент Checker запрещён, включая явный undefined: это ошибка загрузки.
|
|
23
|
-
Native v1 event names/возвраты сохранены. Внутренние bridge/runtime/core subpaths
|
|
24
|
-
не экспортируются. Тесты policy path используют настоящий helper и mock Guard.
|
|
25
|
-
|
|
26
|
-
Версия вручную меняется только в `package.json`. Номер в
|
|
27
|
-
секции migration описывает прежнюю смену API, а не текущую release identity.
|
|
28
|
-
У helper нет встроенной версии и независимого релиза. Guard `source.adapter_version`
|
|
29
|
-
читается из `package.json` установленного пакета; IPC1 описывает формат сообщений
|
|
30
|
-
и не передаёт версии компонентов. Пакет собирается и обновляется целиком.
|
|
31
|
-
Состояние registry не выводится из локальной сборки.
|
|
32
|
-
Root/test workspaces остаются private. Release package имеет private:false;
|
|
33
|
-
это само по себе ничего не публикует. `UNLICENSED` фиксирует отсутствие выданной
|
|
34
|
-
open-source лицензии проекта; Go runtime license включена отдельно.
|
|
35
|
-
|
|
36
|
-
## Сборка и проверка вне checkout
|
|
37
|
-
|
|
38
|
-
Из корня, с Go 1.27, Node.js 24 и npm 11:
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
npm ci --ignore-scripts
|
|
42
|
-
sh scripts/build-ts.sh && scripts/build.sh --all --output dist/artifacts && go run ./tools/pack pack
|
|
43
|
-
npm exec -- node tests/manual/package-prototype.mjs
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Последняя команда создаёт настоящий npm pack .tgz, устанавливает только его во
|
|
47
|
-
временный каталог offline/ignore-scripts и запускает проверку с пустым PATH,
|
|
48
|
-
изолированным HOME и без LLMGUARD_* environment. Результат acceptance.json и путь
|
|
49
|
-
к tarball печатаются в stdout. Проверяются exports, запрет private subpaths,
|
|
50
|
-
шесть hashes, permissions, helper/IPC handshake, v1/v2 transform/restore/
|
|
51
|
-
deny и fail-closed при отсутствующем helper. Mock Guard слушает только loopback.
|
|
52
|
-
Это не установка/активация в OpenCode. На Windows запускайте именно через
|
|
53
|
-
`npm exec -- node`: npm_execpath позволяет вызвать npm CLI без shell/npm.cmd.
|
|
54
|
-
|
|
55
|
-
Portable ZIP — отдельный convenience artifact: `go run ./tools/pack pack` собирает его вместе с npm tarball из уже
|
|
56
|
-
подготовленных inputs и не компилирует plugin executable или TS.
|
|
57
|
-
Он включает только native v2 graph; v1 программный API поставляется в npm tarball.
|
|
58
|
-
Проверка ZIP: распаковать вне checkout и выполнить `node verify.mjs` в каталоге
|
|
59
|
-
пакета. Никаких запросов к Guard или изменения пользовательских settings.
|
|
60
|
-
|
|
61
|
-
## Требования к будущей native acceptance
|
|
62
|
-
|
|
63
|
-
В `.gitlab-ci.yml` job `check` проверяет исходники и host helper; `build` выполняет cross-build один раз; `verify` тестирует полученные архивы, а публикация запускается вручную из main. Подробности: [PUBLISH.md](PUBLISH.md). Native acceptance на остальных платформах — отдельная будущая работа. Нужны matching native runners:
|
|
64
|
-
|
|
65
|
-
| Job | Native environment |
|
|
66
|
-
| ----------------------------------- | --------------------------------------------------------------- |
|
|
67
|
-
| linux-amd64-glibc | Linux x64 glibc |
|
|
68
|
-
| linux-arm64-glibc | Linux ARM64 glibc |
|
|
69
|
-
| darwin-amd64 | macOS Intel |
|
|
70
|
-
| darwin-arm64 | macOS ARM64 |
|
|
71
|
-
| windows-amd64 | Windows x64 |
|
|
72
|
-
| windows-arm64 | Windows ARM64 с native Node/Go |
|
|
73
|
-
| linux-amd64-musl / linux-arm64-musl | Alpine соответствующей архитектуры, native musl Node 24/Go 1.27 |
|
|
74
|
-
|
|
75
|
-
Каждый job делает checkout, устанавливает **native** Node 24/npm 11 и Go 1.27,
|
|
76
|
-
затем выполняет шаги сборки и `node tests/manual/package-prototype.mjs`. Сохранить .tgz и acceptance.json как artifacts.
|
|
77
|
-
Job считается passed только если platform/arch отчёта совпали с runner и native
|
|
78
|
-
acceptance завершился с exit 0; cross-build на другой ОС этого не заменяет.
|
|
79
|
-
Для musl сохранить `/etc/os-release` и libc identification вместе с отчётом.
|
|
80
|
-
|
|
81
|
-
Это требования к будущей native acceptance, а не включённый CI pipeline.
|
|
82
|
-
Core changes требуют regression всех затронутых Go consumers и обеих TS security
|
|
83
|
-
suites (`scripts/check.sh` каждого репозитория), но не автоматического build/release каждого плагина.
|
|
84
|
-
|
|
85
|
-
## Раздельные фазы и публикация
|
|
86
|
-
|
|
87
|
-
```sh
|
|
88
|
-
sh scripts/check.sh
|
|
89
|
-
sh scripts/build-package.sh
|
|
90
|
-
sh scripts/verify.sh
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
TS-only staging: `dist/build`. Prebuilt helpers: `dist/artifacts/bin/<os>-<arch>/helper`. Npm tree: `dist/package`;
|
|
94
|
-
tarball: `dist/llmguard-opencode-<version>.tgz`; ZIP: `dist/llmguard-opencode-<version>.zip` (рядом `.sha256`).
|
|
95
|
-
|
|
96
|
-
`packaging-result.json` рядом с outputs содержит product, version, platforms,
|
|
97
|
-
paths и SHA-256 фактических artifacts; hashes деревьев описаны в общем contract.
|
|
98
|
-
Tree hash не является hash будущего npm tarball: publisher должен вычислить
|
|
99
|
-
его отдельно. Этот result описывает outputs упаковщика. Ручная job npm_stage загружает готовый
|
|
100
|
-
tarball в staging npmjs.org. Maintainer подтверждает публикацию с 2FA, затем job release
|
|
101
|
-
проверяет SHA-512 опубликованного пакета и создаёт GitLab Release: [PUBLISH.md](PUBLISH.md).
|
|
102
|
-
Private build.json не попадает в публичный пакет.
|
|
103
|
-
|
|
104
|
-
CI должен проверить SemVer и уникальность относительно опубликованных релизов
|
|
105
|
-
именно OpenCode, но не вычислять/повышать version. Ручная release job поддерживает стабильные версии и npm latest; beta promotion
|
|
106
|
-
не реализован. Build/tests ничего не публикуют и не меняют установку или credentials.
|
|
107
|
-
Релиз OpenCode не выпускает Codex/Claude/Harness. SHA-256 не защищает от замены
|
|
108
|
-
manifest и binary одновременно; publisher и baseline требуют trusted storage.
|
|
109
|
-
|
|
110
|
-
## Если helper не запускается
|
|
111
|
-
|
|
112
|
-
Защищённая операция блокируется; TS fallback, download, compilation или перенос
|
|
113
|
-
binary в обход mount policy отсутствуют. Проверьте соответствие OS/CPU таблице,
|
|
114
|
-
комплектность bin/manifest.json и binary, executable permission и разрешение
|
|
115
|
-
запуска на выбранном filesystem. При noexec выберите разрешённое администратором
|
|
116
|
-
место установки; плагин не делает copy/remount самостоятельно. Read-only package
|
|
117
|
-
не требует записи в собственный каталог. Не отключайте Guard ради запуска.
|
|
118
|
-
|
|
119
|
-
Cross-build есть для всех шести tuples. Native execution текущего артефакта
|
|
120
|
-
подтверждается только его acceptance report; остальные runners и musl остаются
|
|
121
|
-
unverified до исполнения jobs. Реальная приёмка OpenCode с вашим provider/key —
|
|
122
|
-
отдельный этап, не заменяется mock acceptance.
|