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

package/dist/workspace/model/provider.d.ts

@@ -0,0 +1,140 @@
+import { Disposable } from '../../primitives/disposable.js';
+import { ResourceRef } from '../../primitives/resource.js';
+/**
+ * Адрес узла внутри модели.
+ *
+ * Для Host — непрозрачная строка. Домен выдаёт восемь символов base36 и кладёт их в `$nodeId`,
+ * но проверять это здесь означало бы, что платформа знает формат: следующий провайдер
+ * с другой схемой идентификаторов не смог бы существовать, ничего при этом не нарушив.
+ */
+export type NodeId = string;
+/**
+ * Проба содержимого — чтобы кандидаты читали ресурс ОДИН раз на всех.
+ *
+ * Форма совпадает с `EditorProbe` из вклада редактора (см. `plugin-and-shell.md`) намеренно:
+ * один и тот же объект передаётся и в `canOpen` редактора, и в {@link DocumentModelProvider.applies},
+ * а структурная совместимость держит их одним типом без общей зависимости.
+ */
+export interface EditorProbe {
+    /** Текст ресурса; читается один раз и переиспользуется всеми кандидатами. */
+    text(): Promise<string>;
+}
+/**
+ * Описание правки модели.
+ *
+ * Сериализуемость обязательна: то же самое описание уходит в журнал операций (фундамент
+ * под совместную работу и под разбор хода ассистента), а значит в `params` не должно быть
+ * ни функций, ни ссылок на узлы модели — только данные.
+ */
+export interface EditOp {
+    /** `'insert' | 'move' | 'set-prop' | …` — словарь принадлежит провайдеру, не ядру. */
+    readonly type: string;
+    readonly target?: NodeId;
+    readonly params?: Record<string, unknown>;
+}
+/** Результат применения операции к модели. */
+export interface ApplyResult<M> {
+    readonly model: M;
+    /** Операция, отменяющая эту. Ядру нужна не для Ctrl+Z (там снимки), а для журнала. */
+    readonly inverse: EditOp;
+    /** Куда переехало выделение: узел мог сместиться или родиться. */
+    readonly focus?: NodeId;
+}
+/**
+ * Разбор, печать и правка одного формата.
+ *
+ * `parse`, `print` и `apply` — синхронные и чистые. Это не стилистика: на синхронности
+ * `apply` стоит гейт ассистента (ход проверяется до применения, а не после), а на чистоте —
+ * отмена через снимки: если бы `apply` мутировала модель, снимок перестал бы быть снимком.
+ *
+ * `apply` ОБЯЗАНА сохранять неизменённые поддеревья по ссылке. Разбор каждый раз даёт новый
+ * объект целиком, и именно поэтому документ с моделью не пересобирается из текста на каждое
+ * действие: structural sharing — то, на чём держится и отмена, и сравнение, и перерисовка.
+ */
+export interface DocumentModelProvider<M> {
+    /** Уникален среди провайдеров; попадает в диагностику разбора. */
+    readonly id: string;
+    /**
+     * Берётся ли этот провайдер за такой ресурс.
+     *
+     * Решение по одному лишь расширению не годится: `.json` бывает и схемой формы, и конфигом
+     * пакета. Провайдеру, которому нужно содержимое, проба на пути открытия отдаёт его
+     * синхронно: оболочка кладёт туда уже прочитанный текст, и сузить тип можно `'peek' in probe`.
+     */
+    applies(ref: ResourceRef, probe: EditorProbe): boolean;
+    /** @throws если текст не разбирается — это НЕ авария, а состояние расхождения. */
+    parse(text: string): M;
+    print(model: M): string;
+    apply(model: M, op: EditOp): ApplyResult<M>;
+    /**
+     * Где в тексте лежит каждый узел модели: идентификатор узла → путь в дереве печати
+     * (ключи объектов и индексы массивов).
+     *
+     * Нужен текстовому редактору, чтобы подчеркнуть находку на узле, у которого в тексте нет
+     * своего идентификатора. Спрашивается у провайдера, а не выводится оболочкой: путь узла —
+     * знание о формате. Необязателен: без него такие находки остаются без места в тексте.
+     * Зовётся часто — на каждую публикацию находок, — поэтому ответ стоит запоминать по модели.
+     */
+    nodePaths?(model: M): ReadonlyMap<NodeId, readonly (string | number)[]>;
+    /**
+     * JSON Schema формата — для подсказок текстового редактора: имена ключей, допустимые
+     * значения, описания при наведении.
+     *
+     * Проверкой она НЕ служит: находки публикуют валидаторы в общий свод, и второй канал
+     * подчёркиваний от редактора был бы невидим платформе. `null` — подсказывать нечем
+     * (например, каталог, из которого схема строится, ещё не загружен).
+     *
+     * Необязателен. Зовётся на каждое открытие документа — ответ стоит запоминать.
+     */
+    jsonSchema?(): JsonSchemaHint | null;
+    /** Схема из {@link jsonSchema} устарела — её надо спросить заново. */
+    onDidChangeJsonSchema?(cb: () => void): Disposable;
+    /**
+     * Подсказки в строковом значении под курсором — то, чего JSON Schema выразить не может,
+     * потому что зависит от содержимого документа (пути модели, имена из самого файла).
+     *
+     * `model` — последняя разобранная модель: пока человек печатает, текст бывает неразборчив,
+     * а подсказка нужна именно тогда. Пустой список — «здесь подсказывать нечего».
+     */
+    completeString?(model: M, site: TextStringSite): readonly TextCompletion[];
+}
+/** JSON Schema, которой провайдер описывает свой формат. */
+export interface JsonSchemaHint {
+    /**
+     * Идентификатор схемы. Стабилен, пока схема та же: по нему редактор решает,
+     * перерегистрировать её или нет.
+     */
+    readonly uri: string;
+    readonly schema: unknown;
+}
+/** Строковое значение в тексте документа, внутри которого стоит курсор. */
+export interface TextStringSite {
+    /** Путь значения в дереве печати — ключи объектов и индексы массивов. */
+    readonly path: readonly (string | number)[];
+    /** Содержимое строки без кавычек, как оно записано в тексте (экранирование не снято). */
+    readonly value: string;
+    /** Позиция курсора внутри {@link value}. */
+    readonly offset: number;
+}
+/** Одна подсказка в строковом значении. */
+export interface TextCompletion {
+    /** Что показать в списке. */
+    readonly label: string;
+    /** Пояснение справа от метки. */
+    readonly detail?: string;
+    /** Что вставить вместо {@link replace}. */
+    readonly insert: string;
+    /** Заменяемый участок ВНУТРИ `site.value`: полуинтервал `[start, end)`. */
+    readonly replace: {
+        readonly start: number;
+        readonly end: number;
+    };
+}
+/**
+ * Точка расширения провайдеров модели.
+ *
+ * Тип вклада — `DocumentModelProvider<unknown>`: ядро не параметризуется моделью, потому что
+ * держит их разом несколько и ни об одной ничего не знает. Типизированный доступ появляется
+ * там, где провайдер известен, — у самого плагина.
+ */
+export declare const DocumentModelPoint: import('../../internal.js').ExtensionPoint<DocumentModelProvider<unknown>>;

package/dist/workspace/model/text-editor-focus.d.ts

@@ -0,0 +1,22 @@
+import { ResourceId } from '../../primitives/resource.js';
+import { Capability } from '../../primitives/capability.js';
+export interface TextEditorFocusRegistry {
+    /** В фокусе ли текстовый редактор этого документа. */
+    isFocused(id: ResourceId): boolean;
+    /** Сообщает о смене фокуса. `false` снимает запись, а не хранит её: пустая карта дешевле. */
+    setFocused(id: ResourceId, focused: boolean): void;
+    /** Есть ли фокус хоть где-нибудь. Нужно диагностике и тестам. */
+    hasFocus(): boolean;
+}
+/**
+ * Возможность «кто сейчас печатает»: токен службы плюс версия контракта.
+ *
+ * Провайдер — оболочка (`services/host-capabilities`), а не редактор, и это то же решение,
+ * что у самого реестра: писать в него обязан КАЖДЫЙ текстовый редактор, поэтому принадлежать
+ * он не может ни одному. Регистрируется до активации плагинов, поэтому редактор вправе взять
+ * его `require` прямо в `activate` — правило «сервис ищется в момент использования»
+ * (`plugin/types.ts`) касается сервисов ЧУЖИХ плагинов, а не платформы.
+ */
+export declare const TextEditorFocusCapability: Capability<TextEditorFocusRegistry>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const TextEditorFocusToken: Capability<TextEditorFocusRegistry>;

package/dist/workspace/resource-names.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Правила имён и целевых путей для операций над ресурсами — всё, что проверяется без источника.
+ *
+ * Отделено от исполнения (`resource-ops` оболочки билдера — правила уехали в пакет контракта,
+ * исполнение осталось там, где есть источник) по той же причине, по которой
+ * правила дерева отделены от его отрисовки: имя, которое браузер не примет, и каталог,
+ * вставляемый в самого себя, — это ошибки РЕШЕНИЯ, а не ввода-вывода, и проверять их
+ * обращением к файловой системе значило бы узнавать о них последними.
+ *
+ * ## Почему подбор уникального имени берёт готовый список
+ *
+ * В v1 `uniqueName` (`io/fs-ops.ts:275-285`) спрашивал файловую систему до тысячи раз подряд,
+ * причём каждая проверка стоила ДВУХ обращений (`existsIn` пробовал имя сначала как файл,
+ * потом как каталог). На локальном диске это незаметно, по сети — минуты. Здесь имя
+ * подбирается ПО СПИСКУ уровня, который вызывающий и так прочитал одним `list`, поэтому
+ * цена подбора — ноль обращений, и правило проверяется без файловой системы вовсе.
+ *
+ * @module shell/platform/workspace/resource-names
+ */
+/**
+ * Почему имя не годится. Код, а не фраза: по коду интерфейс строит текст на своём языке,
+ * а тест сравнивает решение, а не перевод.
+ */
+export type NameRejection = 
+/** Пустое имя или одни пробелы. */
+'empty'
+/** Разделитель пути внутри имени: создаём ОДНУ запись, а не дерево. */
+ | 'separator'
+/** `.` или `..` — переход по дереву, а не имя. */
+ | 'dots'
+/** Символ, запрещённый файловыми системами (`\ / : * ? " < > |`) или управляющий. */
+ | 'forbidden-character'
+/** Имя, зарезервированное Windows (`CON`, `PRN`, `NUL`, `COM1`…). */
+ | 'reserved'
+/** Точка или пробел в конце: Windows молча их срежет, и имя окажется не тем. */
+ | 'trailing'
+/** Длиннее предела одного сегмента пути. */
+ | 'too-long';
+/**
+ * Предел длины сегмента.
+ *
+ * 255 — общий знаменатель ext4, APFS и NTFS. Ограничение проверяется по кодовым единицам
+ * UTF-16, а не по байтам: точная байтовая длина зависит от кодировки файловой системы,
+ * а завышенный запас здесь безопаснее заниженного.
+ */
+export declare const MAX_NAME_LENGTH = 255;
+/**
+ * Проверяет имя одной записи. `null` — имя годится.
+ *
+ * Проверка идёт по правилам САМОЙ СТРОГОЙ из целевых систем, а не текущей: проект,
+ * созданный в Linux, открывают в Windows, и имя `aux.ts` там не создастся вовсе. Отказать
+ * при вводе честнее, чем отдать проект, который у соседа не разворачивается.
+ */
+export declare function validateResourceName(name: string): NameRejection | null;
+/**
+ * Делит имя на основу и расширение так, как этого ждёт человек, разводящий копии.
+ *
+ * Точка ищется ПОСЛЕДНЯЯ, а не первая: у `schema.form.json` расширением человек считает
+ * `.json`, и копия обязана называться `schema.form-2.json`, а не `schema-2.form.json`
+ * (v1 брала первую точку и делала именно второе). Ведущая точка расширением не считается:
+ * `.gitignore` — это имя целиком, и `-2.gitignore` было бы другим файлом.
+ */
+export declare function splitName(name: string): {
+    readonly stem: string;
+    readonly ext: string;
+};
+/**
+ * Свободное имя в уровне: `name`, иначе `name-2`, `name-3`…
+ *
+ * `taken` — имена, уже занятые в каталоге (обычно результат одного `list`). Сравнение
+ * без учёта регистра: на APFS и NTFS `Schema.json` и `schema.json` — одна запись, и копия,
+ * различающаяся только регистром, затёрла бы оригинал на половине машин команды.
+ *
+ * Предел подбора — {@link MAX_UNIQUE_ATTEMPTS}; дальше к основе приписывается переданный
+ * `salt`. Соль параметром, а не `Date.now()` внутри: правило обязано быть проверяемым,
+ * а функция, чей ответ зависит от часов, проверяется только приблизительно.
+ */
+export declare function uniqueName(taken: Iterable<string>, name: string, salt?: string): string;
+/**
+ * Сколько номеров перебирается, прежде чем имя разводится солью.
+ *
+ * Тысяча копий одного файла в одном каталоге — это не работа, а авария, и продолжать
+ * перебор дальше означало бы её маскировать.
+ */
+export declare const MAX_UNIQUE_ATTEMPTS = 999;
+/**
+ * Лежит ли путь внутри каталога (или является им самим) — по строкам, без обращения к источнику.
+ *
+ * Нужна ровно одному правилу, зато несущему: каталог нельзя скопировать или перенести
+ * внутрь самого себя, иначе обход не завершится вовсе.
+ */
+export declare function isInside(path: string, dir: string): boolean;

package/dist/workspace/write-options.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Пометка правки: кто правит и в каком логическом шаге.
+ *
+ * Прав она не даёт и ничего не разрешает — она ПОДПИСЫВАЕТ. Запись идёт в рабочую копию
+ * одной дверью, у человека и у ассистента одинаковой, а различие между ними живёт в журнале:
+ * половина ценности аудита в том, что правку человека и правку машины видно порознь.
+ *
+ * @module @reformer/builder-plugin-api/workspace/write-options
+ */
+/**
+ * Кто породил правку.
+ *
+ * Различие несущее: половина ценности аудита в том, что правку человека и правку машины
+ * видно порознь. Поэтому же записи с разным происхождением никогда не схлопываются.
+ */
+export type JournalOrigin = 'user' | 'agent' | 'external';
+export interface WriteOptions {
+    /**
+     * Кто правит. По умолчанию `'user'`: `writeText` без пометки зовут от имени человека,
+     * и в этом случае догадка верна.
+     *
+     * Словарь — целиком журнальный ({@link JournalOrigin}), а не сокращённый до «человек или
+     * машина»: рабочая область здесь ПЕРЕДАТОЧНОЕ звено, и сужать чужой словарь по дороге
+     * значило бы завести второй, который разъедется с первым.
+     */
+    readonly origin?: JournalOrigin;
+    /**
+     * Логический шаг, которому принадлежит правка: ход ассистента, мультикурсорная правка.
+     *
+     * Нужен для `Journal.undoTransaction` — отката шага целиком. Ход, приземлившийся ДВУМЯ
+     * записями (например, ход со второй попыткой), отменяется одним действием только если обе
+     * записи названы одним `txId`; без него отменять пришлось бы по одной, и промежуточное
+     * состояние формы человек увидел бы как результат.
+     */
+    readonly txId?: string;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@reformer/builder-plugin-api",
+  "version": "1.0.0-beta.1",
+  "description": "Public API surface for ReFormer Builder plugins: contracts, extension points and service tokens",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tooling": {
+      "types": "./dist/tooling.d.ts",
+      "import": "./dist/tooling.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "build:stackblitz": "vite build",
+    "test": "node ../../scripts/run-vitest.mjs"
+  },
+  "keywords": [
+    "reformer",
+    "builder",
+    "plugin",
+    "plugin-api",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Alexandr Bukhtatyy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlexandrBukhtatyy/ReFormer.git",
+    "directory": "packages/reformer-builder-plugin-api"
+  },
+  "homepage": "https://alexandrbukhtatyy.github.io/ReFormer/",
+  "bugs": {
+    "url": "https://github.com/AlexandrBukhtatyy/ReFormer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.2",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.8",
+    "@types/react": "^19.2.7"
+  }
+}