@rsconcept/rstool 0.5.2 → 0.6.1

package/README.md

@@ -78,7 +78,7 @@ From `rsconcept/rstool` (or run `powershell -File scripts/dev/LocalDevSetup.ps1`
 - `npm test`
 - `npm run build` — produce `dist/` via tsdown
 - `npm run wrapper` — dev stdio wrapper via `tsx`
-- `npm run example:client`, `npm run example:build-schema`, `npm run example:build-rsmodel`
+- `npm run example:client`, `npm run example:build-schema`, `npm run example:build-rsmodel` — see [`examples/README.md`](examples/README.md) for the full list (kinship scripts, session JSON)
 
 ## Stdio protocol
 

package/docs/PORTAL-API.md

@@ -1,6 +1,8 @@
 # Portal REST API
 
-Справка только для чтения существующих КС, ОСС и RSModel. `rstool` сам не ходит в REST API: он работает с in-memory сессиями.
+Справка для чтения существующих КС, ОСС и RSModel из Portal и переноса КС в `rstool`.
+`rstool` сам не ходит в REST API: он работает с in-memory сессиями.
+Агент получает JSON Portal отдельно, затем переносит конституенты через контракт `rstool`.
 
 ## Хосты
 
@@ -16,17 +18,93 @@
 - Модель → `GET /api/models/:id`.
 - OpenAPI JSON → `GET https://api.portal.acconcept.ru/schema`.
 
+Для UI-ссылки `https://portal.acconcept.ru/rsforms/856` агент должен ходить на:
+
+```text
+GET https://api.portal.acconcept.ru/api/rsforms/856
+GET https://api.portal.acconcept.ru/api/rsforms/856/details
+```
+
+Не переноси UI query/hash вроде `?tab=editor`.
+
+## Доступ
+
+- `access_policy: "public"` читается без авторизации.
+- Приватная схема или модель вернёт `403` и не предназначена для агентов.
+- Если нужны только `title`, `alias`, `description`, `owner`, `access_policy`, не запрашивай `/details`.
+
+## Формат `GET /api/rsforms/:id/details`
+
+Ответ содержит метаданные объекта библиотеки и массив `items[]` с конституентами.
+Для анализа КС обычно нужны только корневые `title`, `alias`, `description` и поля каждой конституенты.
+
+| Portal JSON           | `rstool`                 | Примечание                                            |
+| --------------------- | ------------------------ | ----------------------------------------------------- |
+| `id`                  | `draft.id`               | Стабильный id внутри сессии                           |
+| `alias`               | `draft.alias`            | `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`        |
+| `cst_type`            | `draft.cstType`          | Значения совпадают с `CstType`                        |
+| `definition_formal`   | `draft.definitionFormal` | Пустая строка допустима только для `basic`/`constant` |
+| `term_raw`            | `draft.term`             | Для редактирования сохраняй raw, не resolved          |
+| `definition_raw`      | `draft.definitionText`   | Для редактирования сохраняй raw, не resolved          |
+| `convention`          | `draft.convention`       | Соглашение, не формальная проверка                    |
+| `term_resolved`       | не переносить            | Только отображение после resolver                     |
+| `definition_resolved` | не переносить            | Только отображение после resolver                     |
+| `typification_manual` | обычно не переносить     | Переопределение типизации                             |
+| `term_forms`          | обычно не переносить     | Словоформы термина                                    |
+| `crucial`             | обычно не переносить     | UI/Portal-флаг                                        |
+| `value_is_property`   | обычно не переносить     | Переопределение класса интерпретируемости             |
+
+`inheritance`, `attribution`, `oss`, `models`, `versions`, `editors` полезны для контекста Portal, но не нужны для базовой проверки RSLang в `rstool`.
+
 ## Как перенести КС в rstool
 
 1. Получи `GET /api/rsforms/:id/details`.
-2. Создай `createSession`.
-3. Перенеси конституенты через `addOrUpdateConstituenta`: `alias`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention`.
-4. Работай локально: анализ, правки, вычисления.
-5. Для передачи результата используй `exportSession`.
+2. Создай `createSession({ title, alias, comment: description })`.
+3. Иди по `items[]` в порядке ответа API.
+4. Для каждого элемента вызови `addOrUpdateConstituenta(sessionId, { draft })`.
+5. Проверь `listDiagnostics(sessionId)`.
+6. Работай локально: анализ, правки, вычисления, маленькая КМ.
+7. Для сохранения рабочей сессии используй `exportSession`.
+8. Для загрузки схемы обратно в Portal используй `exportPortalSchema`.
+
+Portal JSON из `/details` **не является** форматом `exportSession` и не передаётся
+в `importSession` напрямую. Его нужно перенести через `addOrUpdateConstituenta`
+или через отдельный адаптер, если он появится в контракте.
+
+Минимальный маппинг:
+
+```ts
+const session = tool.createSession({
+  title: portal.title,
+  alias: portal.alias,
+  comment: portal.description
+});
+
+for (const item of portal.items) {
+  tool.addOrUpdateConstituenta(session.sessionId, {
+    draft: {
+      id: item.id,
+      alias: item.alias,
+      cstType: item.cst_type,
+      definitionFormal: item.definition_formal ?? '',
+      term: item.term_raw ?? '',
+      definitionText: item.definition_raw ?? '',
+      convention: item.convention ?? ''
+    }
+  });
+}
+```
+
+## Практика для агентов
+
+- Запрашивай API host, а не UI host: `https://api.portal.acconcept.ru/api/...`.
+- Для больших схем используй увеличенный таймаут. В PowerShell вызывай `curl.exe`,
+  а не alias `curl` (`Invoke-WebRequest`), если нужен CLI-синтаксис curl.
+- Сначала бери метаданные, если нужно только название или доступность схемы.
 
 ## Не делай
 
 - Не парси HTML SPA.
-- Не переноси UI query/hash вроде `?tab=editor` в REST.
 - Не запрашивай UI напрямую, используй преобразованные API запросы.
+- Не передавай `/details` JSON в `importSession`.
 - Не запрашивай `/details`, если нужны только метаданные.

package/examples/README.md

@@ -0,0 +1,59 @@
+# Примеры rstool
+
+Полные исполняемые сценарии поверх `RSToolWrapperClient` (stdio-обёртка) и готовые JSON-сессии для импорта. Короткие фрагменты кода для агентов — в [`../skills/rstool-helper/EXAMPLES.md`](../skills/rstool-helper/EXAMPLES.md); воркфлоу — [`../skills/rstool-helper/GUIDE.md`](../skills/rstool-helper/GUIDE.md).
+
+## Как запускать
+
+**Из checkout репозитория** (`rsconcept/rstool`):
+
+```bash
+npm install
+npm run build          # обёртка для скриптов
+npm run example:client # и остальные example:* / kinship:cli — см. ниже
+```
+
+**После `npm install @rsconcept/rstool`** (нужен `tsx` или аналог):
+
+```bash
+npx tsx node_modules/@rsconcept/rstool/examples/agent-client.ts
+```
+
+Скрипты пишут JSON рядом с собой в `examples/`; запускайте из корня пакета (каталог, где лежит `package.json` rstool).
+
+## Скрипты
+
+| Файл | npm-скрипт | Назначение |
+|------|------------|------------|
+| [`agent-client.ts`](agent-client.ts) | `example:client` | Минимальный цикл: сессия, upsert, анализ, значения, диагностики через stdio |
+| [`build-sample-rsform.ts`](build-sample-rsform.ts) | `example:build-schema` | Собрать учебную RSForm (X1, S1, D1) и сохранить сессию |
+| [`build-sample-rsmodel.ts`](build-sample-rsmodel.ts) | `example:build-rsmodel` | RSForm + привязки + вычисления → учебная RSModel |
+| [`build-kinship-rsform.ts`](build-kinship-rsform.ts) | `example:build-kinship-schema` | Полная концептуальная схема «родственные отношения» (много конституент) |
+| [`build-kinship-rsmodel.ts`](build-kinship-rsmodel.ts) | `example:build-kinship-rsmodel` | Загрузить kinship RSForm, задать семью, вычислить модель (в т.ч. D3) |
+| [`kinship/cli.ts`](kinship/cli.ts) | `kinship:cli` | Интерактивное редактирование людей (X1) и связей (S1) в kinship-модели |
+
+## JSON-сессии
+
+Готовые снимки `exportSession` — для `importSession`, тестов и CLI:
+
+| Файл | Содержимое |
+|------|------------|
+| [`sample-rsform-session.json`](sample-rsform-session.json) | Учебная RSForm (результат `build-sample-rsform`) |
+| [`sample-rsmodel-session.json`](sample-rsmodel-session.json) | Учебная RSModel с вычисленными значениями |
+| [`kinship-rsform-session.json`](kinship-rsform-session.json) | Схема родства без привязок |
+| [`kinship-rsmodel-session.json`](kinship-rsmodel-session.json) | Kinship-модель с примерной семьёй (по умолчанию для `kinship:cli`) |
+
+Пересобрать JSON: соответствующий `build-*.ts` перезапишет файл в `examples/`.
+
+## Папка `kinship/`
+
+Вспомогательный код для сценария «родственные отношения», не отдельный пакет:
+
+| Файл | Роль |
+|------|------|
+| [`constants.ts`](kinship/constants.ts) | Id конституент (X1, S1, D3, A1, …) и путь сессии по умолчанию |
+| [`session.ts`](kinship/session.ts) | Обёртка над сессией: загрузка/сохранение, команды над X1 и S1 |
+| [`x1-actions.ts`](kinship/x1-actions.ts) | Парсинг и применение изменений списка людей |
+| [`x1-actions.test.ts`](kinship/x1-actions.test.ts) | Тесты логики X1 (`npm test`) |
+| [`cli.ts`](kinship/cli.ts) | REPL: `list`, `add`, `remove`, `rename`, `set`, `save`, … |
+
+См. также [`../docs/CONSTITUENTA.md`](../docs/CONSTITUENTA.md) (разбор kinship-схемы) и [`../docs/MODEL-TESTING.md`](../docs/MODEL-TESTING.md).

package/examples/agent-client.ts

@@ -0,0 +1,76 @@
+import { CstType, RSToolWrapperClient, type AddOrUpdateConstituentaInput, type AnalyzeExpressionInput } from '../src';
+
+interface CreateSessionResult {
+  sessionId: string;
+  contractVersion: string;
+}
+
+async function runExample() {
+  const client = new RSToolWrapperClient();
+  try {
+    await client.waitUntilReady();
+
+    const session = await client.call<CreateSessionResult>('createSession');
+    console.log('Session created:', session);
+
+    const baseInput: AddOrUpdateConstituentaInput = {
+      draft: {
+        id: 1,
+        alias: 'X1',
+        cstType: CstType.BASE,
+        definitionFormal: ''
+      }
+    };
+    await client.call('addOrUpdateConstituenta', {
+      sessionId: session.sessionId,
+      input: baseInput
+    });
+
+    const upsertInput: AddOrUpdateConstituentaInput = {
+      draft: {
+        id: 2,
+        alias: 'D1',
+        cstType: CstType.TERM,
+        definitionFormal: '1+2'
+      }
+    };
+    const upsert = await client.call('addOrUpdateConstituenta', {
+      sessionId: session.sessionId,
+      input: upsertInput
+    });
+    console.log('Upsert result:', upsert);
+
+    await client.call('setConstituentaValue', {
+      sessionId: session.sessionId,
+      input: { target: 1, value: { 0: 'zero', 1: 'one' } }
+    });
+
+    const evalResult = await client.call('evaluateConstituenta', {
+      sessionId: session.sessionId,
+      input: { constituentId: 2 }
+    });
+    console.log('Evaluation result:', evalResult);
+
+    const analyzeInput: AnalyzeExpressionInput = {
+      expression: '(',
+      cstType: CstType.TERM
+    };
+    const analysis = await client.call('analyzeExpression', {
+      sessionId: session.sessionId,
+      input: analyzeInput
+    });
+    console.log('Analysis result:', analysis);
+
+    const diagnostics = await client.call('listDiagnostics', {
+      sessionId: session.sessionId
+    });
+    console.log('Diagnostics count:', Array.isArray(diagnostics) ? diagnostics.length : diagnostics);
+  } finally {
+    await client.close();
+  }
+}
+
+runExample().catch(error => {
+  console.error(error);
+  process.exit(1);
+});