@reformer/builder-plugin-api 1.0.0-beta.1

package/dist/plugin/types.d.ts

@@ -0,0 +1,136 @@
+import { CapabilityAccess } from '../primitives/capability.js';
+import { PluginCommandRegistry } from '../primitives/command.js';
+import { Disposable } from '../primitives/disposable.js';
+import { EventBus } from '../primitives/event.js';
+import { ExtensionRegistry } from '../primitives/extension-point.js';
+import { ServiceRegistry } from '../primitives/service.js';
+import { PluginI18n } from '../services/i18n.js';
+import { PluginStorage, SecretStorage } from './storage.js';
+/**
+ * Всё, что плагин получает от платформы. Другого способа дотянуться до Host у него нет.
+ *
+ * Контекст создаётся рантаймом на каждую активацию заново (см. `createPluginContext`)
+ * и перестаёт быть действительным после деактивации: подписки из него сняты, вклады убраны.
+ * Держать контекст в модульной переменной плагина и пользоваться им после выключения —
+ * ошибка, которую рантайм не в состоянии предотвратить, но которая проявится сразу:
+ * зарегистрированное после деактивации уже никто не снимет.
+ */
+export interface PluginContext {
+    /** Идентификатор плагина, которому принадлежит контекст. Совпадает с `Plugin.id`. */
+    readonly id: string;
+    /**
+     * Реестр сервисов — общий, не вид на него.
+     *
+     * Регистрация чужого токена не запрещена технически (изоляция здесь — гигиена, а не граница
+     * безопасности), но занят токен может быть только один раз: повторная регистрация бросает.
+     */
+    readonly services: ServiceRegistry;
+    /**
+     * Возможности — ВИД на тот же реестр служб, а не второе хранилище.
+     *
+     * Разница со `services` не в данных, а в вопросе. `services` отвечает «дай реализацию по
+     * токену»; `capabilities` отвечает «выполнен ли контракт, который я объявил в `requires`»,
+     * и потому умеет три вещи, которых у реестра нет: назвать в отказе версию и возможного
+     * провайдера (`require`), деградировать штатно (`get`) и дождаться появления реализации
+     * (`observe`) — без опроса по таймеру.
+     *
+     * Правило «сервис ищется в момент использования» здесь В СИЛЕ целиком: `require` в `activate`
+     * запрещён ровно так же, как `services.require` чужого сервиса, — провайдер имеет право
+     * подняться позже. `observe` для того и существует.
+     */
+    readonly capabilities: CapabilityAccess;
+    /**
+     * Точки расширения — **вид реестра для этого плагина** (`RootExtensionRegistry.forPlugin`),
+     * а не корневой реестр.
+     *
+     * Разница несущая: в виде нет ни параметра `pluginId`, ни метода `forPlugin`, поэтому плагин
+     * физически не располагает способом внести вклад анонимно или от чужого имени. Ответ
+     * на вопрос «откуда здесь эта панель» гарантирован строением API, а не дисциплиной.
+     */
+    readonly extensions: ExtensionRegistry;
+    /** Реестр команд. Снятие команды — через `dispose()` регистрации, то есть через `subscriptions`. */
+    /**
+     * Реестр команд — ВИД на него для этого плагина: `register` проставляет владельца сам.
+     *
+     * Владелец нужен не реестру, а палитре: заголовок команды разрешается словарём того,
+     * кто её внёс. Без этого `titleKey` команды плагина искался бы в словаре Host и всегда
+     * промахивался. Метода `forPlugin` в виде нет — зарегистрировать команду от чужого
+     * имени не получится, потому что пути к этому не существует.
+     */
+    readonly commands: PluginCommandRegistry;
+    /** Шина событий. Доставка синхронная, ошибка подписчика не касается отправителя. */
+    readonly events: EventBus;
+    /**
+     * Словарь плагина: его строки в ЕГО пространстве имён.
+     *
+     * Ключи префиксуются идентификатором плагина автоматически, поэтому `editor.label` двух
+     * разных плагинов — две разные строки; общего пространства имён у словарей нет и быть
+     * не должно. `contribute` регистрирует словарь (обычно в `activate`, но можно и по частям —
+     * например, вместе с ленивой панелью), `t` переводит.
+     *
+     * Показывать переведённое в React надо через `useTranslate` из этого же пакета: `t` отвечает,
+     * как строка звучит СЕЙЧАС, и сама по себе смену языка не переживает.
+     *
+     * Что НЕ переводится здесь: тексты диагностик (`errors.<code>`). Одна и та же ошибка обязана
+     * выглядеть одинаково в редакторе, в панели проблем и в логе, поэтому её строки живут
+     * в словаре оболочки, а плагин просит перевод, а не переводит сам.
+     */
+    readonly i18n: PluginI18n;
+    /** Изолированное хранилище плагина. Пространство имён — идентификатор плагина. */
+    readonly storage: PluginStorage;
+    /** Секреты плагина. По умолчанию — только память сессии, см. {@link SecretStorage}. */
+    readonly secrets: SecretStorage;
+    /**
+     * Всё, что сюда положено, освобождается при деактивации.
+     *
+     * Массив, а не реестр: плагин пишет в него `push`, и это единственная операция, которая
+     * от него требуется. Рантайм освобождает список сам — этим снимается целый класс утечек
+     * «выключили плагин, а его панель и команда остались навсегда».
+     *
+     * Обратная сторона: вклад, **не** положенный в `subscriptions`, при деактивации не снимется.
+     * Рантайм не в состоянии это обнаружить: он не знает, что именно плагин зарегистрировал.
+     */
+    readonly subscriptions: Disposable[];
+}
+/**
+ * Контракт плагина.
+ *
+ * `id` — пространство имён владельца во всех реестрах (`editor-schema`, `ai`): по нему
+ * подписаны вклады, по нему изолированы хранилище и секреты, по нему плагин включается
+ * и выключается.
+ */
+export interface Plugin {
+    readonly id: string;
+    /**
+     * Регистрирует всё, что даёт плагин. Вызывается рантаймом один раз на активацию.
+     *
+     * Синхронный по решению выше. Асинхронную работу запускать можно и нужно, но **не ждать**:
+     * `void activate` не даёт вернуть промис, поэтому запущенное обязано само доложить о себе
+     * через сервис или вклад.
+     *
+     * Исключение отсюда не роняет запуск: рантайм ловит его, помечает плагин отказавшим
+     * и продолжает активировать остальные (см. `createPluginRegistry`).
+     */
+    activate(ctx: PluginContext): void;
+    /**
+     * Необязательный обратный вызов при выключении.
+     *
+     * Нужен только для того, что не выражается через `subscriptions`: остановить таймер, отменить
+     * запрос, закрыть соединение. Снимать вклады руками здесь не надо — это делает рантайм,
+     * освобождая `subscriptions` сразу после `deactivate`.
+     */
+    deactivate?(): void;
+}
+/**
+ * Объявляет плагин.
+ *
+ * Функция выглядит тождественной и почти ею является — её ценность в трёх вещах:
+ * вывод типов на `ctx` в месте объявления (без неё автор пишет аннотацию руками или теряет
+ * типы), проверка `id` в момент объявления, а не в момент регистрации, и единственное имя,
+ * которое загрузчик подставляет плагину каталога как `@builder/sdk`.
+ *
+ * Результат заморожен: `id` — ключ во всех реестрах, и его изменение после регистрации
+ * означало бы вклады, найденные по одному имени и снимаемые по другому. Состояние плагина
+ * живёт в замыкании `activate`, а не на объекте, поэтому заморозка ничего не отнимает.
+ */
+export declare function definePlugin(p: Plugin): Plugin;

package/dist/primitives/capability.d.ts

@@ -0,0 +1,72 @@
+import { Disposable } from './disposable.js';
+import { ServiceToken } from './service.js';
+/**
+ * Токен службы с объявленной версией контракта.
+ *
+ * Расширение, а не обёртка: всё, что принимает `ServiceToken`, принимает и capability.
+ */
+export interface Capability<T> extends ServiceToken<T> {
+    /** Версия контракта: три числа, `1.0.0`. Диапазоны здесь недопустимы — это объявление. */
+    readonly version: string;
+}
+/** Объявление «я даю такую-то возможность такой-то версии». Форма поля `provides` манифеста. */
+export interface CapabilityDeclaration {
+    readonly id: string;
+    readonly version: string;
+}
+/** Требование «мне нужна такая-то возможность в таком-то диапазоне». Форма поля `requires`. */
+export interface CapabilityRequirement {
+    readonly id: string;
+    /** Диапазон в записи `./semver`: `^1`, `~1.2`, `>=1.2.3`, `1.x`, `*`. */
+    readonly range: string;
+}
+/** Кто именно объявил возможность. `by` — идентификатор плагина, и он нужен диагностике. */
+export interface CapabilityProvider extends CapabilityDeclaration {
+    readonly by: string;
+}
+/**
+ * Объявляет capability.
+ *
+ * Проверки — в момент объявления, а не в момент использования, по той же причине, что
+ * у `defineService` и `definePlugin`: пустой идентификатор превратил бы диагностику
+ * в «возможность «» не предоставлена», а диапазон вместо версии (`^1` в поле `version`)
+ * сделал бы сравнение бессмысленным, причём молча — `satisfies('^1', '^1')` это `false`.
+ */
+export declare function defineCapability<T>(spec: CapabilityDeclaration): Capability<T>;
+/**
+ * Удовлетворяет ли объявление требованию.
+ *
+ * Неразбираемый диапазон даёт `false`: требование, которое нельзя прочитать, не выполнено
+ * ничем. Разбор манифеста отвергает такое требование раньше и с внятным текстом — эта
+ * функция всего лишь не делает вид, что понимает написанное.
+ */
+export declare function meetsRequirement(declaration: CapabilityDeclaration, requirement: CapabilityRequirement): boolean;
+/**
+ * Вид на реестр служб в терминах capability — то, что получает плагин как `ctx.capabilities`.
+ *
+ * Три метода отвечают на три разных вопроса, и подменять один другим нельзя:
+ * «возьму, если есть» (`get`), «без этого мне нечего делать» (`require`), «скажи, когда
+ * появится» (`observe`).
+ */
+export interface CapabilityAccess {
+    /** `undefined` — возможности нет. Вызывающий обязан деградировать, а не падать. */
+    get<T>(cap: Capability<T>): T | undefined;
+    /**
+     * Бросает, если возможности нет, — с текстом, называющим и требование, и того, кто мог бы
+     * его удовлетворить.
+     *
+     * Годится только там, где отсутствие возможности и есть отказ операции: внутри команды,
+     * обработчика, тела панели. В `activate` его звать нельзя — порядок активации ничего
+     * не значит, и провайдер имеет полное право подняться позже (см. `../plugin/types`).
+     */
+    require<T>(cap: Capability<T>): T;
+    /**
+     * Сообщает о появлении и об исчезновении реализации.
+     *
+     * Зовёт обработчик СРАЗУ с текущим значением (`undefined`, если возможности нет), и это
+     * решение, а не побочный эффект: наблюдатель почти всегда рисует состояние, и без
+     * немедленного вызова каждый его потребитель писал бы `get` плюс `observe` — две строки,
+     * между которыми помещается гонка.
+     */
+    observe<T>(cap: Capability<T>, listener: (impl: T | undefined) => void): Disposable;
+}

package/dist/primitives/command.d.ts

@@ -0,0 +1,262 @@
+import { Disposable } from './disposable.js';
+import { WhenContext } from './when-context.js';
+import { WhenExpr } from './when-expr.js';
+/**
+ * Как команда выглядит для модели. Заполняется осознанно — см.
+ * {@link CommandRegistry.agentCommands}.
+ */
+export interface CommandAgentSpec {
+    /** Описание для модели, а не ключ i18n: модель читает по-английски и перевода не ждёт. */
+    readonly description: string;
+    /** JSON Schema аргументов. Проверяется до вызова — это работа моста ассистента (Э10). */
+    readonly schema: object;
+}
+/** Вклад в точку расширения `command`. */
+export interface CommandContribution {
+    /** Уникальный идентификатор с пространством имён владельца: `workspace.save`. */
+    readonly id: string;
+    /**
+     * Ключ i18n, не литерал: иначе одна из локалей становится главной, а перевод —
+     * привязанным к месту объявления команды.
+     *
+     * Разрешается словарём ВЛАДЕЛЬЦА (см. {@link CommandContribution.pluginId}), а не Host:
+     * иначе команда плагина гарантированно промахивается мимо ключа и показывает маркер.
+     */
+    readonly titleKey: string;
+    /**
+     * Кто внёс команду. Проставляет РЕЕСТР, а не объявление, — тем же приёмом, что у вкладов
+     * (`ExtensionRegistry.forPlugin`): будь это параметр, его забыли бы, ошиблись
+     * бы в нём или подставили чужой.
+     *
+     * Отсутствие означает команду самой оболочки, и её `titleKey` — ключ словаря Host.
+     * Разница видна пользователю: без владельца заголовок команды плагина был бы маркером
+     * промаха вроде `⟦editor-schema.command.delete⟧`.
+     */
+    readonly pluginId?: string;
+    /**
+     * Действие. Может быть синхронным или асинхронным; реестр вызывает его синхронно
+     * (см. {@link CommandRegistry.execute}).
+     */
+    readonly run: (args?: unknown) => unknown | Promise<unknown>;
+    /**
+     * Применимость. Отсутствие означает «доступна всегда».
+     *
+     * Предикат обязан быть чистым и дешёвым: его зовут на каждую перерисовку палитры и на
+     * каждое нажатие, которое диспетчер сопоставит с сочетанием.
+     */
+    readonly enabled?: (ctx: WhenContext) => boolean;
+    /** Например `mod+s`, `mod+alt+v`. `mod` = Cmd на macOS, Ctrl на остальных. */
+    readonly keybinding?: string;
+    /**
+     * Условие ПРИВЯЗКИ КЛАВИШИ: `focus == tree`, `activeResourceKind == form.schema`.
+     * Разбирается на регистрации, синтаксис — см. `./when-expr`.
+     *
+     * ## Чем отличается от `enabled` — водораздел, а не два способа одного
+     *
+     * `when` отвечает «где и в каком режиме» (состояние платформы: куда направлен фокус, что
+     * открыто), `enabled` — «есть ли чему сработать» (приватное состояние владельца: есть ли
+     * что отменять, лежит ли что-то в буфере). Первое обязано быть ДАННЫМИ — их сравнивают,
+     * чтобы решить, чья клавиша выигрывает, показывают человеку в таблице клавиш и пишут в
+     * файл раскладки. Второе данными быть не может: оно читает то, чего у платформы нет.
+     *
+     * Прямая польза, ради которой поле и заведено: `delete` в проекте зарегистрирован дважды —
+     * деревом файлов и редактором схемы, — и сегодня их разводит только порядок регистрации,
+     * который по контракту рантайма плагинов ничего не значит. С условиями `focus == tree` и
+     * `focus == canvas` они становятся ДОКАЗУЕМО непересекающимися.
+     *
+     * ## Проверяет его диспетчер клавиш, а НЕ этот реестр
+     *
+     * `isEnabled` и `execute` условие не смотрят, и это осознанно: `when` ограничивает клавишу,
+     * а не команду. Смотри его реестр — пункт контекстного меню «Переименовать» пропал бы в тот
+     * момент, когда меню открыто правым щелчком без фокуса на строке, то есть ровно тогда, когда
+     * он нужен. Из палитры, меню и от ассистента команда вызывается по-прежнему по `enabled`.
+     */
+    readonly when?: string;
+    /**
+     * Разрешить сочетание, когда фокус в поле ввода. По умолчанию — нет.
+     *
+     * Помечаются единицы: сохранение, палитра команд. Всё остальное в поле ввода принадлежит
+     * тому, кто в это поле печатает.
+     *
+     * Поле живёт здесь, рядом с `keybinding`, а не вносится дополнением объявления из диспетчера:
+     * раз `keybinding` уже здесь, знание о клавиатуре в этом модуле уже есть, и разносить два
+     * поля одного понятия по разным файлам — хуже, чем держать их вместе.
+     */
+    readonly allowInEditable?: boolean;
+    /** Опционально: как эта команда выглядит для модели. */
+    readonly agent?: CommandAgentSpec;
+}
+/** Команда, у которой есть блок `agent`, — с сужением типа, чтобы не проверять его повторно. */
+export type AgentVisibleCommand = CommandContribution & {
+    readonly agent: CommandAgentSpec;
+};
+/**
+ * Причина отказа. Код, а не переведённая фраза: по коду ассистент чинится сам, по фразе — нет,
+ * и одна ошибка выглядит одинаково в интерфейсе, логе и тесте.
+ */
+export type CommandErrorKind = 'invalid-id' | 'invalid-keybinding' | 'invalid-when' | 'duplicate' | 'not-found' | 'disabled';
+/**
+ * Отказ реестра команд.
+ *
+ * `message` — диагностика для разработчика; интерфейс обязан строить текст из {@link kind}
+ * и {@link params}, а не показывать его пользователю.
+ */
+export declare class CommandError extends Error {
+    readonly kind: CommandErrorKind;
+    /** Параметры кода: `commandId`, `keybinding`. */
+    readonly params: Readonly<Record<string, string>>;
+    constructor(kind: CommandErrorKind, message: string, params?: Readonly<Record<string, string>>, options?: ErrorOptions);
+}
+/**
+ * Приводит сочетание к каноническому виду: `mod+shift+K` → `mod+shift+k`.
+ *
+ * Чистая функция и единственное место, где решается, как выглядит сочетание. Регистрация
+ * и будущий диспетчер зовут её обе — иначе они разойдутся в написании, и расхождение
+ * проявится не отказом, а молчаливо не сработавшей клавишей.
+ *
+ * Что делает: снимает регистр и пробелы, разворачивает синонимы (`cmd` → `meta`,
+ * `esc` → `escape`, `option+left` → `alt+arrowleft`), выстраивает модификаторы в
+ * фиксированном порядке. Чего не делает: не разрешает `mod` в платформенный модификатор
+ * и не проверяет, существует ли такая клавиша, — первое знает только диспетчер, второе
+ * отсекло бы раскладки и клавиши, о которых мы не подумали.
+ *
+ * @throws {CommandError} `invalid-keybinding`, если есть пустая часть, повторён модификатор,
+ * клавиш больше одной или их нет вовсе.
+ */
+export declare function normalizeKeybinding(keybinding: string): string;
+/** Объявление в объёме, которого хватает для условия: диспетчеру больше ничего не нужно. */
+export interface WhenBearing {
+    readonly when?: string;
+}
+/**
+ * Разобранное условие команды. Без условия — {@link WHEN_TRUE}, то есть «всегда».
+ *
+ * Разбор здесь никогда не бросает: до этой точки объявление уже прошло регистрацию, которая
+ * отвергает неразбираемое условие. Команда, собранная в обход реестра с испорченным условием,
+ * получает «никогда» — тихо пропустить её безопаснее, чем уронить обработчик нажатия.
+ */
+export declare function whenOf(command: WhenBearing): WhenExpr;
+/**
+ * Кладёт в кэш уже разобранное условие.
+ *
+ * Нужна реестру: он разбирает условие на РЕГИСТРАЦИИ, чтобы отвергнуть неразбираемое сразу,
+ * — и без этой функции разобранное им пришлось бы выбросить, а {@link whenOf} разбирал бы
+ * то же самое второй раз при первом нажатии. Сам кэш наружу не отдаётся: он тайна модуля,
+ * и ключом в нём служит объект объявления, а не его идентификатор.
+ */
+export declare function rememberWhen(command: WhenBearing, expr: WhenExpr): void;
+/**
+ * Сколько нажатий может быть в аккорде.
+ *
+ * Два, как в VS Code и WebStorm. Не потому, что три технически сложнее, а потому что аккорд
+ * из трёх ступеней человек не воспроизводит по памяти, и такая клавиша существует только
+ * в списке.
+ */
+export declare const MAX_CHORD_STEPS = 2;
+/**
+ * Разбирает аккорд: `mod+k mod+s` в две ступени, обычное сочетание — в одну.
+ *
+ * Разделитель ступеней — пробел, и здесь есть ловушка, ради которой написана первая строка:
+ * пробел ВНУТРИ ступени незначим (`mod + alt + V` — одно сочетание, и это закреплено тестом
+ * реестра). Наивное деление по пробелам сломало бы существующее написание. Правило звучит
+ * так: **пробел, прилегающий к `+`, — украшение; пробел между двумя завершёнными ступенями —
+ * разделитель.**
+ *
+ * @throws {CommandError} `invalid-keybinding` — ступеней больше {@link MAX_CHORD_STEPS}
+ * либо ступень не разбирается.
+ */
+export declare function normalizeChord(keybinding: string): readonly string[];
+/** Где именно упал чужой код. Пока причина одна, но она не последняя. */
+export interface CommandErrorInfo {
+    readonly commandId: string;
+    readonly phase: 'enabled';
+}
+export interface CommandRegistryOptions {
+    /**
+     * Откуда брать контекст, если он не передан явно. По умолчанию — {@link NEUTRAL_WHEN_CONTEXT}.
+     *
+     * Поставщик, а не аргумент на каждом вызове: контекст обязан быть один на приложение.
+     * Если бы его собирал каждый вызывающий, палитра, диспетчер и ассистент разошлись бы в том,
+     * что считается «текущим состоянием», — и охранные условия вернулись бы туда, откуда
+     * их убрали.
+     */
+    readonly getContext?: () => WhenContext;
+    /**
+     * Куда сообщать об ошибке в чужом коде. По умолчанию — `console.error`.
+     *
+     * Тот же канал и та же причина, что у шины событий: упавший предикат — это чужая поломка,
+     * и она не должна ни ронять палитру, ни исчезать бесследно.
+     */
+    readonly onError?: (error: unknown, info: CommandErrorInfo) => void;
+}
+/** Вид реестра команд для плагина: то же, что {@link CommandRegistry}, но без `forPlugin`. */
+export type PluginCommandRegistry = Omit<CommandRegistry, 'forPlugin'>;
+export interface CommandRegistry {
+    /**
+     * Регистрирует команду. `dispose()` снимает её — на этом держится выключение плагина
+     * и уход команд вместе с закрытым редактором.
+     *
+     * @throws {CommandError} `invalid-id` — пустой идентификатор; `duplicate` — идентификатор
+     * занят; `invalid-keybinding` — сочетание не разбирается.
+     */
+    register(command: CommandContribution): Disposable;
+    /**
+     * Вид реестра для плагина: `register` проставляет владельца сам. Повторный вызов
+     * с тем же идентификатором возвращает тот же объект — идентичность стабильна, чтобы вид
+     * годился в зависимости хуков.
+     *
+     * В самом виде метода `forPlugin` нет: плагин не располагает способом зарегистрировать
+     * команду от чужого имени, потому что пути к этому не существует, а не потому, что так
+     * договорились.
+     */
+    forPlugin(pluginId: string): PluginCommandRegistry;
+    /** Команда по идентификатору или `undefined`. */
+    get(id: string): CommandContribution | undefined;
+    /**
+     * Все зарегистрированные, в порядке регистрации. Порядок показа решает палитра.
+     *
+     * Между изменениями возвращается **та же** ссылка на массив. Это не оптимизация, а
+     * требование `useSyncExternalStore`: он сравнивает снимки по ссылке и падает с «результат
+     * getSnapshot должен кэшироваться», получая новый массив на каждый вызов. Снимок
+     * сбрасывается ровно тогда же, когда зовутся наблюдатели {@link onDidChange}.
+     */
+    getAll(): readonly CommandContribution[];
+    /**
+     * Уведомление о появлении и снятии команды.
+     *
+     * Существует потому, что набор команд меняется ПОСЛЕ первой отрисовки: команды оболочки
+     * регистрируются эффектами компонентов (палитра, справка), а команды плагинов — при
+     * активации. Без этого события меню, построенное на первом кадре, навсегда осталось бы
+     * без них — и показывало бы пустой «Вид» рядом с работающим сочетанием клавиш.
+     *
+     * Реестр вкладов решает ту же задачу тем же способом (`observe`), и намеренно одинаково:
+     * два разных механизма подписки на два соседних реестра пришлось бы каждый раз вспоминать.
+     */
+    onDidChange(cb: () => void): Disposable;
+    /**
+     * Применима ли команда. Незнакомый идентификатор — `false`: палитра и меню спрашивают
+     * про то, что сами же перечислили, и отказ им здесь не нужен.
+     */
+    isEnabled(id: string, ctx?: WhenContext): boolean;
+    /**
+     * Выполняет команду, предварительно проверив применимость.
+     *
+     * `run` вызывается синхронно — до первого `await` внутри самой команды. Это нужно, чтобы
+     * команда могла участвовать в контуре правки и укладываться в одну запись отмены;
+     * асинхронен только её результат.
+     *
+     * @throws {CommandError} `not-found` или `disabled` — отказом, а не тихим ничем: молчание
+     * здесь неотличимо от «команда отработала и ничего не сделала», и ассистент по нему
+     * не поймёт, что промахнулся.
+     */
+    execute(id: string, args?: unknown, ctx?: WhenContext): Promise<unknown>;
+    /**
+     * Команды, у которых объявлен блок `agent`, — поверхность инструментов ассистента.
+     *
+     * Применимость здесь **не фильтруется**, и это осознанно: набор инструментов уходит
+     * в каждый запрос к модели, поэтому он обязан быть устойчивым — иначе префикс запроса
+     * меняется от фокуса пользователя и кэширование префикса перестаёт работать. Применимость
+     * проверяется в момент вызова, там же, где у человека.
+     */
+    agentCommands(): readonly AgentVisibleCommand[];
+}

package/dist/primitives/disposable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Освобождение ресурса — общий примитив для всех реестров.
+ *
+ * Каждая регистрация возвращает `Disposable`, и это не украшение: на нём держится снятие
+ * вкладов при выключении плагина. Плагин складывает всё в `subscriptions` своего контекста,
+ * а рантайм освобождает их сам — без этого выключение плагина оставляло бы его панели
+ * и команды в реестрах навсегда.
+ *
+ * @module shell/platform/primitives/disposable
+ */
+/** Что-то, что умеет освободить занятое. Повторный вызов обязан быть безвредным. */
+export interface Disposable {
+    dispose(): void;
+}
+/**
+ * Оборачивает функцию в {@link Disposable} с защитой от повторного вызова.
+ *
+ * Идемпотентность здесь несущая: реестр может освободить подписку сам (например, при
+ * замене вклада), а владелец потом вызовет `dispose()` ещё раз из своего списка.
+ */
+export declare function toDisposable(fn: () => void): Disposable;
+/** Освобождает набор подписок. Ошибка одной не мешает остальным. */
+export declare function disposeAll(items: readonly Disposable[]): void;

package/dist/primitives/event.d.ts

@@ -0,0 +1,38 @@
+import { Disposable } from './disposable.js';
+/**
+ * Типизированный ключ события: связывает идентификатор с типом полезной нагрузки.
+ *
+ * Тот же приём, что у токена сервиса, и по той же причине — строка с приведением типа
+ * на каждой подписке рано или поздно разъезжается с тем, что кладут в `emit`.
+ */
+export interface EventType<T> {
+    readonly id: string;
+    /** Только для вывода типов, в рантайме отсутствует. */
+    readonly __type?: T;
+}
+/**
+ * Объявляет тип события.
+ *
+ * Идентификатор — с пространством имён владельца (`workspace.didChange`, `editor.didFocus`):
+ * шина различает события только по нему, и совпадение у двух плагинов означает перекрёстную
+ * доставку с чужой нагрузкой.
+ */
+export declare function defineEvent<T>(id: string): EventType<T>;
+/** Шина: публикация и подписка. Больше ничего — всё остальное строится поверх. */
+export interface EventBus {
+    /**
+     * Синхронно доставляет нагрузку всем подписчикам этого типа.
+     *
+     * Возвращает управление только после того, как отработал последний подписчик. Ошибка
+     * любого из них не прерывает рассылку и не выходит наружу.
+     */
+    emit<T>(type: EventType<T>, payload: T): void;
+    /**
+     * Подписывает обработчик. `dispose()` отписывает ровно эту подписку — один и тот же
+     * обработчик, подписанный дважды, вызывается дважды и отписывается по одному.
+     *
+     * Отписка действует немедленно, в том числе изнутри доставки: подписчик, снятый другим
+     * подписчиком, уже не получит текущее событие.
+     */
+    on<T>(type: EventType<T>, cb: (payload: T) => void): Disposable;
+}

package/dist/primitives/extension-point.d.ts

@@ -0,0 +1,53 @@
+import { Disposable } from './disposable.js';
+/**
+ * Типизированное имя точки расширения.
+ *
+ * Ключ — `id`, а не идентичность объекта, по той же причине, что у токена сервиса:
+ * модуль с объявлением может оказаться в памяти дважды, и вклады не должны разъезжаться
+ * по двум разным точкам с одинаковым именем.
+ */
+export interface ExtensionPoint<T> {
+    readonly id: string;
+    /** Только для вывода типов, в рантайме отсутствует. */
+    readonly __type?: T;
+}
+/** Объявляет точку расширения. `id` виден в диагностике, поэтому пустым быть не может. */
+export declare function defineExtensionPoint<T>(id: string): ExtensionPoint<T>;
+/** Один вклад в точку расширения. Заморожен: порядок и происхождение не переписываются извне. */
+export interface Contribution<T> {
+    /** Уникален в пределах точки. Годится как React-ключ и как адрес в диагностике. */
+    readonly id: string;
+    /** Кто внёс. Проставляет реестр, а не вносящий. */
+    readonly pluginId: string;
+    /** Меньше — раньше. По умолчанию `0`. */
+    readonly order: number;
+    readonly value: T;
+}
+/** Необязательные свойства вклада, задаваемые вносящим. */
+export interface ContributionMeta {
+    /** Устойчивый идентификатор вклада; уникален в пределах точки. */
+    readonly id?: string;
+    /** Меньше — раньше. По умолчанию `0`. */
+    readonly order?: number;
+}
+/**
+ * Вид реестра для одного плагина — то, что лежит в `PluginContext.extensions`.
+ *
+ * `get` и `observe` видят вклады всех плагинов: панель слота рисуется целиком, кем бы
+ * её части ни были внесены. Разделение касается только записи.
+ */
+export interface ExtensionRegistry {
+    /**
+     * Вносит вклад от имени плагина, которому принадлежит этот вид реестра.
+     *
+     * Без `meta.id` идентификатор генерируется как `<pluginId>:<point>#<n>`; явный `id`
+     * обязан быть уникален в пределах точки. `meta.order` по умолчанию `0`.
+     *
+     * `dispose()` снимает вклад и уведомляет наблюдателей.
+     */
+    contribute<T>(point: ExtensionPoint<T>, item: T, meta?: ContributionMeta): Disposable;
+    /** Вклады, упорядоченные по `order`; при равенстве — по порядку регистрации. */
+    get<T>(point: ExtensionPoint<T>): readonly Contribution<T>[];
+    /** Для реактивности UI: вызывается при добавлении и при снятии вклада. */
+    observe<T>(point: ExtensionPoint<T>, cb: () => void): Disposable;
+}

package/dist/primitives/module-path.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Нормализация пути внутри набора файлов модуля: плагина или сайдкаров формы.
+ *
+ * Отдельно от `normalizePath` ресурсов — у них разный ответ на побег за корень. Адрес ресурса
+ * за корнем источника — ошибка программы, и там бросают. Путь модуля за корнем набора файлов —
+ * это то, что написал автор плагина или формы (`"main": "../../secrets.ts"`), и ответ на него
+ * обязан быть ДАННЫМИ: разбор манифеста превращает его в отказ с объяснением, линковщик —
+ * в ненайденный модуль. Бросок здесь уронил бы разбор чужого каталога целиком.
+ *
+ * Одна функция на линковщик, разбор манифеста и сборку плагина: разойдись они, валидатор
+ * пропускал бы точку входа, которую оболочка отвергнет.
+ *
+ * @module @reformer/builder-plugin-api/primitives/module-path
+ */
+/**
+ * Нормализует путь: убирает `.`, схлопывает `..`, приводит разделители к `/`.
+ *
+ * Возвращает `undefined`, если путь вылез за корень набора файлов. Это не педантизм: набор
+ * файлов — весь мир исполняемого кода, и `../../../etc` обязан быть отказом, а не промахом.
+ */
+export declare function normalizeModulePath(path: string): string | undefined;