pi-apexlang 0.2.2 → 0.4.0

package/docs/en/tool-reference.md

@@ -0,0 +1,85 @@
+# Tool reference
+
+[Documentation](README.md) · [Українська](../uk/tool-reference.md)
+
+The registered tool is named **`apexlang`**. Its model-visible API has exactly the eight actions below. The schema is in [index.ts](../../extensions/apexlang/index.ts), while action-specific requirements and command construction are in [apexlang-cli.mjs](../../extensions/lib/apexlang-cli.mjs).
+
+## Actions
+
+| Action | Required input beyond `action` | Effect |
+| --- | --- | --- |
+| `workspace_probe` | None; connection and workspace must be supplied together if used | Discovers bounded local context and candidate applications. |
+| `new_app_materialize` | `app_path`, `db_connection_name`, `workspace_name`; authoritative probe result | Creates the base scaffold after interactive confirmation, only at the exact suggested path. |
+| `local_validate` | `app_path` | Runs vocabulary, DSL, and validation-rule checks. `fix_vocab=true` rewrites vocabulary after confirmation. |
+| `compiler_truth_audit` | `app_path` | Audits against compiler metadata with component-attribute verification always enabled. |
+| `query_valid_props` | At least one of `component`, `component_type_id`, `template_component`, or `list=true` | Queries compiler properties or lists matching component types; requests JSON output. |
+| `runtime_preflight` | `db_connection_name`, `workspace_name` | Resolves/checks runtime setup; accepts optional `app_path`. |
+| `runtime_doctor` | `db_connection_name`, `workspace_name` | Diagnoses runtime setup; accepts optional `app_path`. |
+| `runtime_validate` | `app_path`, `db_connection_name`, `workspace_name` | Validates live, then offers the separate interactive import path after an authoritative pass. |
+
+The two direct project-writing operations are scaffold creation and vocabulary rewriting. Reports and temporary runtime copies may also be written by other actions. Server import is a separate confirmed branch of `runtime_validate`.
+
+## Parameters
+
+| Parameter | Type / values | Used by |
+| --- | --- | --- |
+| `action` | One of the eight names above | All calls |
+| `app_path` | Directory within the active workspace | Scaffold, local/audit/live validation; optional for preflight/doctor |
+| `db_connection_name` | Saved SQLcl alias, 1–128 characters; letters, digits, `_`, `.`, `-`; first character alphanumeric or `_` | Probe, scaffold, runtime actions |
+| `workspace_name` | 1–128 characters; letters, digits, `_`, `$`, `#`, `.`, `-`; first character alphanumeric | Paired with the saved connection |
+| `execution_mode` | `auto`, `build-root`, `path` | Runtime actions; delegated to Oracle runtime resolution |
+| `apex_root` | Runtime root path | Runtime actions |
+| `compiler_oracle_home` | Compiler metadata location or Oracle home | Compiler audit, property queries, initial live validation |
+| `component` | Semantic component identifier | Property query |
+| `component_type_id` | Numeric ID supplied as a string | Property query |
+| `template_component` | Universal Theme template component identifier | Property query |
+| `parent`, `group` | Component/property-group filters | Property query |
+| `when` | Array of up to 20 assumption strings | Property query |
+| `list` | Boolean | Property query |
+| `supporting_objects` | Boolean | Runtime preflight/doctor, validation, and the later import path |
+| `fix_vocab` | Boolean | Local validation |
+
+Control characters are rejected in text inputs. Paths also reject double quotes and ampersands. The schema exposes shared optional fields; the command builder determines which fields each action consumes. In particular, the roundtrip import builder does not forward `compiler_oracle_home` as a CLI option.
+
+## Example tool inputs
+
+These are tool argument objects, not shell commands. Replace illustrative values with verified project context.
+
+```json
+{"action":"workspace_probe"}
+```
+
+```json
+{"action":"local_validate","app_path":"applications/service-ops"}
+```
+
+```json
+{"action":"query_valid_props","list":true}
+```
+
+```json
+{"action":"runtime_preflight","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
+```
+
+```json
+{"action":"runtime_validate","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
+```
+
+## Results and pass criteria
+
+Successful tool responses contain text plus `details` such as `action`, `exitCode`, and `outputRoot`. Runtime validation also reports `liveValidationPassed` and `imported`, with choice/target details when applicable. Cancelled project changes return `cancelled=true`. Failed runs throw an error containing the available process output and report path; pre-execution input errors may have no reports yet.
+
+| Operation | Evidence checked by the extension |
+| --- | --- |
+| Local checks | Wrapper exits successfully and emits `APEXLANG_LOCAL_CHECK_OK`; individual reports carry diagnostics. |
+| Live check | Successful process result; `live_check_status=pass` **or** `validation_status=pass`; and `validation_sources.live_validator.status=pass`. |
+| New-target proof | A deliberately blocked result: `target_resolution_mode=create-new`, `target_resolution_status=not_found_in_workspace`, `create_new_confirmation_required=true`, `import_status=blocked`, `failure_class=create_new_confirmation_required`, and `ok=false`. |
+| Import | Successful process result and `validate_status=pass`, `import_status=pass`, `runtime_gate_status=pass`. |
+
+Exit code zero alone is insufficient for live-check or import success. The new-target proof is expected to stop at a confirmation boundary; it is not an imported application.
+
+## Warning compatibility
+
+The adapter contains a narrowly checked compatibility path for SQLcl results containing only compile warnings. It verifies current artifacts, transcript evidence, and applicable target identity before normalizing a result or continuing an approved import. Missing, stale, contradictory, or hard-error evidence remains blocking. The create-new branch does not use the existing-app compatibility import fallback.
+
+This mechanism is separate from the ORDS/SQLcl **advisory table**, which only adds diagnostic guidance. See [maintenance](maintenance.md) and the source functions `normalizeWarningOnlyValidation` and `runWarningCompatibleImport` in the [adapter](../../extensions/lib/apexlang-cli.mjs).

package/docs/uk/README.md

@@ -0,0 +1,41 @@
+# Документація pi-apexlang
+
+[English](../en/README.md) · [README проєкту](../../README.md)
+
+`pi-apexlang` поєднує агента розробки pi з ресурсами Oracle для APEXlang. Агент використовує шаблони та настанови Oracle для роботи з файлами застосунку; розширення надає інструмент із визначеними діями для пошуку контексту, створення каркаса, перевірки й діагностики середовища. Імпорт стає доступним через інтерактивний вибір після успішної перевірки на сервері.
+
+Це незалежна інтеграція, а не продукт Oracle. Репозиторій має назву `pi-apex`; назву та версію пакета визначено в [package.json](../../package.json).
+
+## Оберіть матеріал за задачею
+
+| Ваша задача | Посібник |
+| --- | --- |
+| Установити пакет і перевірити перший застосунок | [Початок роботи](getting-started.md) |
+| Зрозуміти компоненти та порядок імпорту | [Архітектура](architecture.md) |
+| Знайти дії, параметри та докази результату | [Довідник інструмента](tool-reference.md) |
+| Знайти звіти, з'ясувати причини помилок або оновити пакет | [Супровід](maintenance.md) |
+
+## Загальна схема
+
+![Робота з APEXlang: визначити контекст, виконати локальні та компіляторні перевірки, перевірити на сервері й обрати, чи імпортувати застосунок.](../assets/overview.uk.svg)
+
+[Масштабована інфографіка](../assets/overview.uk.svg) · [Зображення PNG](../assets/overview.uk.png)
+
+## Що означає успішна перевірка
+
+| Доказ | Що він підтверджує |
+| --- | --- |
+| Успішна локальна перевірка | Пройдено вбудовані перевірки словника, DSL і правил валідацій. |
+| Успішний аудит compiler-truth | Структуру й атрибути компонентів перевірено за вибраними метаданими компілятора. |
+| Підтверджена успішна серверна перевірка | Середовище повернуло докази успіху live-валідатора для знімка застосунку. |
+| Успішний імпорт | Перевірка, імпорт і контроль середовища повернули `pass`. |
+
+Самої локальної перевірки недостатньо, щоб підтвердити коректність застосунку на конкретному сервері. Успішна серверна перевірка сама по собі не означає, що застосунок імпортовано.
+
+## Основа документації
+
+Посібники описують версію пакета **0.4.0**, оновлену **2026-09-22** зі skill Oracle APEXlang релізу **2026.09.21**, зафіксованим у [`UPSTREAM.json`](../../UPSTREAM.json). Оновлення додає сценарії Media List і Comments, розширює підтримку Metric Card, Cards та Region Display Selector і посилює перевірки Smart Filter та Search. Див. включені до пакета [release notes Oracle](../../skills/apexlang/release-notes.json).
+
+Шляхи та назви підключень у прикладах умовні. Доступ до сервера, облікові дані й цілі розгортання визначає оператор.
+
+Твердження про реалізацію містять посилання на локальні джерела. Посилання на вимоги Oracle наведено в посібнику з початку роботи. Таблиця сумісності — рекомендаційний матеріал цього проєкту; дата її перевірки відрізняється від дати документації. Ці посібники не підтверджують перевірку чи імпорт у робочому серверному середовищі.

package/docs/uk/architecture.md

@@ -0,0 +1,73 @@
+# Архітектура
+
+[Документація](README.md) · [English](../en/architecture.md)
+
+## Компоненти
+
+| Шар | Відповідальність | Джерело |
+| --- | --- | --- |
+| Oracle skill | Маршрутизація задач, довідкові матеріали, шаблони та вбудоване середовище Oracle | [skills/apexlang](../../skills/apexlang) |
+| Розширення Pi | Реєстрація `apexlang`, схема параметрів, підтвердження та очищення сесії | [index.ts](../../extensions/apexlang/index.ts) |
+| Адаптер процесів | Масиви аргументів, перевірки шляхів і контексту, контроль хешів застосунку, запуск дочірніх процесів | [apexlang-cli.mjs](../../extensions/lib/apexlang-cli.mjs) |
+| Обгортка локальних перевірок | Перевірки словника, DSL і правил валідацій | [apexlang-local-validate.mjs](../../extensions/lib/apexlang-local-validate.mjs) |
+| Прискорення парсера | Кешування повторного розбору блоків і запитів вкладеності в межах одного Python-процесу | [apexlang-local-validator.py](../../extensions/lib/apexlang-local-validator.py) |
+| Міст до середовища | Виклик вбудованих валідації та roundtrip; підтримка керованого шляху SQLcl через PTY | [обгортка валідації](../../extensions/lib/apexlang-runtime-validate.mjs), [roundtrip-міст](../../extensions/lib/apexlang-runtime-roundtrip.mjs), [PTY-міст](../../extensions/lib/apexlang-sqlcl-pty.py) |
+| Рекомендації щодо сумісності | Виявлення масових діагностик і відображення рекомендацій щодо версій | [compatibility.ts](../../extensions/apexlang/compatibility.ts), [таблиця](../../extensions/apexlang/ords-sqlcl-compatibility.json) |
+
+Skill збережено без змін на коміті та з хешем, зазначеними в [UPSTREAM.json](../../UPSTREAM.json). Прискорення розширення обгортає валідатор Oracle; воно не редагує копію постачальника й не пропускає етапи перевірки. Pi знаходить skill через запис `pi.skills` пакета та поступово завантажує матеріали конкретної задачі.
+
+Обгортка валідації задає шляхи до граматики та Python-валідатора в пакеті для перевірок Media List за цільовою збіркою. Runtime Oracle 2026.09.21 шукає ці файли за шляхами дерева вихідного коду, яких немає в публічному skill-пакеті. Обгортка зберігає перевірки Oracle та обробку їхніх помилок.
+
+## Робочий процес
+
+```mermaid
+flowchart TD
+    A[Запит + застосунок або достовірні метадані] --> B[workspace_probe]
+    B --> C[Агент створює або редагує файли APEXlang]
+    B -. Необов'язковий підтверджений каркас .-> S[new_app_materialize]
+    S --> C
+    C --> D[query_valid_props + local_validate + compiler_truth_audit]
+    D --> E[runtime_preflight / runtime_doctor]
+    E --> F[runtime_validate: серверна перевірка]
+    F --> G{Є підтверджений успіх?}
+    G -- Ні --> H[Аналіз діагностик і виправлення]
+    H --> C
+    G -- Так --> I{Інтерактивний вибір}
+    I -- Лише перевірка / скасування / немає UI --> J[Завершення без імпорту]
+    I -- Імпорт --> K[Визначення цілі + перевірка хешу]
+    K --> L[Повторна перевірка й імпорт в одній сесії SQLcl]
+```
+
+Це рекомендований порядок роботи. Зареєстрований інструмент не є планувальником, який автоматично виконує всі вісім дій. Код застосунку редагує агент; у схемі інструмента немає універсальної дії `generate` чи `edit`.
+
+## Порядок імпорту
+
+1. `runtime_validate` має повернути успішний результат процесу, `live_check_status=pass` або `validation_status=pass`, а також `validation_sources.live_validator.status=pass`.
+2. За наявності UI розширення пропонує **Check APEXlang code** або **Check and import APEXlang code**. Без UI воно повертає результат серверної перевірки з `imported=false`.
+3. Вибір імпорту потребує коректного SHA-256 хешу застосунку та явного режиму цілі:
+
+   | Режим цілі | Необхідний доказ |
+   | --- | --- |
+   | Оновити наявний | Oracle визначає рівно один наявний застосунок на сервері. |
+   | Створити новий | Oracle доводить відсутність alias у вибраному workspace без права імпорту; після цього користувач підтверджує створення в додатковому діалозі. |
+
+4. Адаптер перевіряє, чи знімок застосунку досі відповідає погодженому хешу. Зміни дерева потребують повторної перевірки.
+5. Перевірка й імпорт виконуються разом в одній сесії SQLcl. Розширення повідомляє успішний імпорт лише за успішного результату процесу та `pass` у всіх полях: `validate_status`, `import_status`, `runtime_gate_status`.
+
+У переліку дій, доступному моделі, немає окремої дії імпорту. Кожен діалог підтвердження та вибору отримує сигнал скасування й таймаут п'ять хвилин. Відсутність вибору ніколи не дозволяє імпорт. Це механізми контролю пакета; вони не замінюють права збереженого підключення в базі даних.
+
+## Тимчасова копія та докази виконання
+
+Операції середовища з указаним застосунком потребують JSON-об'єкта в `deployments/default.json`. Адаптер приймає workspace з `workspace.name` або експортованого `app.workspace.name`, відхиляє конфлікти та порівнює назву з явним `workspace_name` без урахування регістру. Невизначений заповнювач `__REQUIRED_WORKSPACE_NAME__` відхиляється.
+
+Адаптер копіює застосунок до каталогу результатів сесії для попередньої перевірки середовища, діагностики, валідації, імпорту та перевірки відсутності нового застосунку. Він додає workspace і нормалізує переноси рядків у тимчасових `.apx` засобом Oracle перед обчисленням хешу. Файли проєкту залишаються незмінними. Тому валідація та імпорт використовують однаковий знімок із переносами LF. Хеш також нормалізує форматування JSON і додане `workspace.name`; інші властивості розгортання залишаються його частиною, а зміни вмісту коду потребують повторної валідації.
+
+Розширення створює тимчасовий каталог результатів `pi-apexlang-*` під час першого виклику й повторно використовує його в межах сесії. Тому звіти й контекст середовища мають спільний стабільний корінь сесії. Відомі докази validation/roundtrip очищаються перед відповідним новим запуском. На `session_shutdown` весь каталог результатів видаляється: скопіюйте потрібні докази до завершення сесії.
+
+## Межі виконання
+
+Шляхи застосунку залишаються в активному робочому каталозі Pi. Адаптер перевіряє реальні шляхи, відхиляє символічні посилання в деревах застосунків і відповідних вхідних файлах пошуку, а для переписування словника також відхиляє файли з кількома жорсткими посиланнями. Команди використовують масиви аргументів без shell-інтерполяції. Скасування, таймаут або перевищення обсягу виводу зупиняє дерево запущеного процесу.
+
+Інструмент працює послідовно. Налаштований таймаут команди — **10 хвилин на окремий запущений процес**, а не загальний ліміт багатоетапної дії. Типовий ліміт сумарного виводу процесу — **8 MiB**; текст для моделі обрізається на **80 000 символів** зі збереженням адреси повних звітів.
+
+Виконувані приклади цих меж наведено в [тестах адаптера](../../test/runner.test.mjs) і [тестах розширення](../../test/extension.test.mjs).

package/docs/uk/getting-started.md

@@ -0,0 +1,77 @@
+# Початок роботи
+
+[Документація](README.md) · [English](../en/getting-started.md)
+
+## Вимоги
+
+Для локальної роботи потрібні встановлений pi, Node.js **22.19.0 або новіший** і команда `python3` у `PATH`. Мінімальну версію Node визначено в [package.json](../../package.json); [обгортка локальних перевірок](../../extensions/lib/apexlang-local-validate.mjs) викликає `python3` безпосередньо.
+
+Для серверних команд [включений до пакета skill Oracle](../../skills/apexlang/README.md#requirements) потребує SQLcl **26.1.2 або новішого**, останньої доступної збірки APEX **26.1**, робочого підключення до бази та прав на цільові workspace і схему. Загальні [вимоги Oracle до APEXlang](https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html) зазначають SQLcl 26.1 як мінімум. ORDS **26.1.1** додав необхідну підтримку APEXlang; див. [опис випуску ORDS 26.1.1](https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html). Для гілки SQLcl 26.1.2 Oracle зазначає Java **17 або 21** в [описі випуску](https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html). Для іншої версії перевіряйте документацію відповідного випуску.
+
+Потрібні **назва збереженого підключення SQLcl** і відповідна **назва APEX workspace**. Розширення приймає назви, а не паролі, облікові дані чи рядки підключення. Локальна робота також потребує наявного застосунку APEXlang або достовірних метаданих схеми, моделі, API чи таблиць.
+
+## Установлення та відкриття проєкту
+
+Установлення для поточного користувача:
+
+```bash
+pi install git:github.com/avhrst/pi-apex
+```
+
+Для встановлення лише в межах проєкту застосунку виконайте команду в його каталозі:
+
+```bash
+pi install git:github.com/avhrst/pi-apex -l
+```
+
+Потім запустіть `pi` в каталозі, що містить застосунок і метадані. Це активний робочий каталог: `app_path` має залишатися в його межах.
+
+Щоб спробувати цей репозиторій локально, запустіть `pi -e .` з його checkout. Тоді робочим каталогом буде checkout; команда не обирає зовнішній проєкт застосунку. Кореневий README також містить форму встановлення через npm для використання після публікації пакета. Цей посібник не стверджує, що конкретну версію вже опубліковано.
+
+Pi завантажує skill, коли він доречний. Почніть запит із `/skill:apexlang`, щоб обрати його явно.
+
+## Перша перевірка наявного застосунку
+
+Наведені назви — приклади; підставте реальний шлях застосунку та збережене підключення.
+
+1. Визначте контекст:
+
+   ```text
+   /skill:apexlang Досліди цей робочий каталог. Визнач можливі застосунки APEX і наявні достовірні метадані. Поясни, яких вхідних даних бракує.
+   ```
+
+2. Перевірте потрібний застосунок локально:
+
+   ```text
+   /skill:apexlang Перевір applications/service-ops локально. Виконай аудит compiler-truth, якщо доступні метадані компілятора. Покажи знайдені проблеми та шляхи звітів. Не імпортуй застосунок.
+   ```
+
+3. Коли середовище налаштовано, замовте серверну перевірку:
+
+   ```text
+   /skill:apexlang Перевір applications/service-ops через збережене підключення apex_dev та APEX workspace SERVICE_OPS_DEV. Спочатку діагностуй середовище, потім виконай серверну перевірку. Не імпортуй застосунок.
+   ```
+
+Якщо після успішної серверної перевірки з'явиться діалог наступного кроку, оберіть **Check APEXlang code**, щоб завершити без імпорту. Кожен інтерактивний діалог обмежено п'ятьма хвилинами; скасування, таймаут або відсутність UI не надають дозволу на імпорт.
+
+Точні назви дій наведено в [довіднику інструмента](tool-reference.md), а окремий шлях імпорту — в [архітектурі](architecture.md#порядок-імпорту).
+
+## Створення локального каркаса
+
+Надайте достовірні метадані й alias застосунку, цільовий шлях або підказку щодо назви. `workspace_probe` має визначити контекст, установити `app_context.status=create_new_allowed` і повернути точний `suggested_app_path`. Для `new_app_materialize` потрібні цей шлях, пара назв підключення/workspace та інтерактивне підтвердження.
+
+```text
+/skill:apexlang Використай перевірені метадані схеми в цьому робочому каталозі для підготовки нового застосунку APEXlang. Спочатку виконай probe і повідом запропонований шлях. Створи каркас через діалог підтвердження, потім перевір його локально. Не імпортуй застосунок.
+```
+
+Матеріалізація створює локальні файли. Створення застосунку на сервері — пізніша операція імпорту з окремим підтвердженням.
+
+## Оновлення повного експорту
+
+У сесії SQLcl із відповідним підключенням замініть заповнювачі перед виконанням:
+
+```text
+apex export -applicationid <id> -exptype APEXLANG -split -dir <absolute-parent-directory> -force
+```
+
+`-dir` — батьківський каталог; SQLcl створює під ним папку з alias застосунку. `-force` видаляє та створює цю папку заново. Перед оновленням збережіть зміни, наявні лише локально. Настанова розширення передбачає один експорт із заміною, щоб уникнути копій із суфіксами на кшталт `p00005_1.apx`; див. [зареєстровану настанову](../../extensions/apexlang/index.ts).

package/docs/uk/maintenance.md

@@ -0,0 +1,83 @@
+# Супровід і діагностика
+
+[Документація](README.md) · [English](../en/maintenance.md)
+
+## Збереження потрібних звітів
+
+Візьміть `outputRoot` із деталей результату інструмента або шлях `APEXlang reports:` із помилки виконання. Розширення передає цей каталог дочірнім процесам як `APEXLANG_OUTPUT_ROOT`; власний тимчасовий корінь створюється всередині розширення, а не задається параметром інструмента.
+
+| Відносний шлях | Вміст |
+| --- | --- |
+| `logs/apexlang-vocab-report.json` | Діагностики словника та непідтримуваної MMD |
+| `logs/apexlang-dsl-report.json` | Діагностики перевірки DSL |
+| `logs/apexlang-validations-report.json` | Діагностики правил валідацій |
+| `logs/validation/` | Артефакти серверної перевірки, якщо їх створило середовище |
+| `logs/runtime-run.json`, `logs/runtime-run.log` | Звіт і транскрипт roundtrip, якщо їх створено |
+| `logs/compat/` | Докази сумісності, якщо використано відповідний шлях |
+| `runtime-apps/` | Тимчасові копії застосунку |
+
+Не кожна дія створює всі файли. Нові запуски очищають відомі застарілі докази, а завершення сесії видаляє весь корінь. Для довготривалого збереження скопіюйте потрібні звіти до каталогу доказів проєкту перед наступним запуском або завершенням сесії. Звіти можуть містити код, назви та діагностики застосунку; перегляньте їхній вміст перед передаванням іншим.
+
+## Діагностика за симптомом
+
+| Симптом | Наступний крок |
+| --- | --- |
+| `Missing Inputs` під час створення каркаса | Надайте достовірні метадані й підказку щодо ідентичності застосунку; повторіть probe та використайте точний `suggested_app_path`. |
+| Відхилено шлях або символічне посилання | Відкрийте pi в корені потрібного проєкту й використайте справжній каталог застосунку всередині нього. |
+| Виправлення словника відхиляє файл із кількома жорсткими посиланнями | Перед переписуванням зробіть потрібний файл застосунку незалежним. |
+| Відхилено підключення чи workspace | Використайте збережений alias, а не рядок підключення; надайте відповідний workspace. |
+| `deployments/default.json` відсутній або суперечливий | Перегляньте експортовані метадані розгортання та узгодьте потрібний workspace перед повтором. |
+| Не вдається визначити властивості компілятора | Перевірте `mmdVersion` застосунку й доступні метадані компілятора; використайте `compiler_oracle_home` там, де його підтримано. |
+| Багато діагностик у всьому застосунку | Перед масовими правками перевірте сумісність SQLcl/APEX/ORDS і метаданих компілятора. |
+| Серверний процес успішно завершився, але імпорт недоступний | Перевірте поля доказів live-валідатора; самого коду завершення недостатньо. |
+| Застосунок змінився після погодженої перевірки | Повторно перевірте поточний знімок застосунку. |
+| Діалог після перевірки скасовано або сплив таймаут | Застосунок не імпортовано; замовте нову перевірку, якщо імпорт досі потрібний. |
+| Таймаут процесу чи перевищення обсягу виводу | Перегляньте збережений вивід, діагностуйте через `runtime_doctor` і усуньте причину перед повтором. |
+
+## Рекомендації щодо версій
+
+[Машиночитана таблиця](../../extensions/apexlang/ords-sqlcl-compatibility.json) містить `policy=advisory-only` і дату перевірки **2026-07-19**. Збірка SQLcl **26.1.2.132.1334** у ній — діагностична базова версія для описаних сценаріїв APEX 26.1, а не універсально обов'язкова версія. SQLcl 26.2 не блокується категорично.
+
+[Механізм рекомендацій](../../extensions/apexlang/compatibility.ts) спрацьовує за щонайменше **50 структурованих діагностик**. Для локальних JSON-звітів і текстового виводу compiler-truth додатково потрібні щонайменше **5 різних `.apx`-файлів**; дублікати діагностик прибираються. Явний `UNSUPPORTED_MMD_VERSION` у локальному звіті словника також викликає рекомендації.
+
+Перевірте `sql -version`, `.apex/apexlang.json` → `mmdVersion`, а також версії APEX/ORDS на сервері разом із його адміністратором. Таблиця додає поради, не змінюючи статусу перевірки й не надаючи права імпорту. Зафіксовані мінімуми Oracle та діагностичні рекомендації проєкту мають різні значення `basis`; для інших гілок версій звертайтеся до пов'язаної документації випусків.
+
+## Розробка та перевірки
+
+З кореня репозиторію:
+
+```bash
+npm install --ignore-scripts
+npm run check
+```
+
+`npm run check` послідовно виконує такі етапи:
+
+| Етап | Що перевіряє |
+| --- | --- |
+| `typecheck` | Суворі перевірки TypeScript без створення вихідних файлів |
+| `verify:vendor` | Хеш і походження зафіксованої копії Oracle |
+| `test` | Контракти розширення/адаптера та відповідність результатів валідаторів |
+| `smoke` | Probe порожнього тимчасового каталогу й локальну перевірку вбудованого каркаса |
+| `verify:package` | Склад npm-пакета в dry-run і виключення файлів розробки/кешу |
+
+Це локальні автоматизовані перевірки, а не доказ успішної серверної перевірки чи імпорту на реальному сервері. Workflow публікації запускається вручну й виконує `npm run check` перед публікацією; див. [publish-npm.yml](../../.github/workflows/publish-npm.yml).
+
+## Оновлення копії Oracle
+
+Підставте перевірений коміт/ref замість `<reviewed-ref>`:
+
+```bash
+npm run sync:oracle -- --ref <reviewed-ref>
+npm run check
+```
+
+[Скрипт синхронізації](../../scripts/sync-oracle-apexlang.mjs) отримує репозиторій Oracle, замінює `skills/apexlang`, оновлює `LICENSE`, коміт/хеш у `UPSTREAM.json` і зафіксовані посилання в кореневому README та повідомленнях про сторонні компоненти. Під час заміни він використовує резервну копію. Перегляньте підсумковий diff перед комітом.
+
+Власну поведінку реалізуйте в `extensions/`; локальні зміни в копії Oracle порушують перевірку її походження. Після зміни поведінки разом оновлюйте обидва мовні посібники й обидві інфографіки SVG/PNG. Дата/коміт посібників — знімок документації, який скрипт синхронізації Oracle не переписує автоматично.
+
+## Матеріали документації
+
+Інфографіки — редаговані SVG у [docs/assets](../assets) з PNG-копіями для поширення. Обидві мають однакові компонування та процес. SVG є джерелом кожного зображення; після зміни підписів або схеми оновіть PNG. Перелік npm `files` включає `docs`, щоб посилання на документацію з установленого README залишалися придатними.
+
+Посилання на код/тести в цих посібниках стосуються Git checkout. `scripts/` і `test/` — ресурси розробки, які навмисно не входять до npm-пакета; для них відкрийте [репозиторій коду](https://github.com/avhrst/pi-apex). Ліцензія та атрибуція постачальника наведені в [LICENSE](../../LICENSE), [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md) і [UPSTREAM.json](../../UPSTREAM.json).

package/docs/uk/tool-reference.md

@@ -0,0 +1,85 @@
+# Довідник інструмента
+
+[Документація](README.md) · [English](../en/tool-reference.md)
+
+Зареєстрований інструмент має назву **`apexlang`**. Його API для моделі містить рівно вісім наведених нижче дій. Схема визначена в [index.ts](../../extensions/apexlang/index.ts), а вимоги окремих дій і формування команд — в [apexlang-cli.mjs](../../extensions/lib/apexlang-cli.mjs).
+
+## Дії
+
+| Дія | Обов'язкові дані, крім `action` | Результат |
+| --- | --- | --- |
+| `workspace_probe` | Немає; якщо вказано підключення чи workspace, потрібні обидва | Шукає локальний контекст і можливі застосунки в установлених межах. |
+| `new_app_materialize` | `app_path`, `db_connection_name`, `workspace_name`; достовірний результат probe | Створює базовий каркас після інтерактивного підтвердження лише за точним запропонованим шляхом. |
+| `local_validate` | `app_path` | Перевіряє словник, DSL і правила валідацій. `fix_vocab=true` переписує словник після підтвердження. |
+| `compiler_truth_audit` | `app_path` | Виконує аудит за метаданими компілятора з обов'язково ввімкненою перевіркою атрибутів компонентів. |
+| `query_valid_props` | Щонайменше одне з `component`, `component_type_id`, `template_component` або `list=true` | Запитує властивості компілятора чи перелік відповідних типів компонентів; запитує вивід JSON. |
+| `runtime_preflight` | `db_connection_name`, `workspace_name` | Визначає та перевіряє налаштування середовища; приймає необов'язковий `app_path`. |
+| `runtime_doctor` | `db_connection_name`, `workspace_name` | Діагностує налаштування середовища; приймає необов'язковий `app_path`. |
+| `runtime_validate` | `app_path`, `db_connection_name`, `workspace_name` | Перевіряє на сервері; після підтвердженого успіху пропонує окремий інтерактивний шлях імпорту. |
+
+Дві операції безпосередньо змінюють проєкт: створення каркаса та переписування словника. Інші дії також можуть записувати звіти й тимчасові копії середовища. Імпорт на сервер — окрема підтверджена гілка `runtime_validate`.
+
+## Параметри
+
+| Параметр | Тип / значення | Де використовується |
+| --- | --- | --- |
+| `action` | Одна з восьми назв вище | Усі виклики |
+| `app_path` | Каталог у межах активного робочого каталогу | Каркас, локальна/компіляторна/серверна перевірка; необов'язковий для preflight/doctor |
+| `db_connection_name` | Збережений alias SQLcl, 1–128 символів; латинські літери, цифри, `_`, `.`, `-`; перший символ — літера, цифра або `_` | Probe, каркас, дії середовища |
+| `workspace_name` | 1–128 символів; латинські літери, цифри, `_`, `$`, `#`, `.`, `-`; перший символ — літера або цифра | Разом зі збереженим підключенням |
+| `execution_mode` | `auto`, `build-root`, `path` | Дії середовища; передається механізму визначення середовища Oracle |
+| `apex_root` | Шлях кореня середовища | Дії середовища |
+| `compiler_oracle_home` | Каталог метаданих компілятора або Oracle home | Компіляторний аудит, запити властивостей, початкова серверна перевірка |
+| `component` | Семантичний ідентифікатор компонента | Запит властивостей |
+| `component_type_id` | Числовий ID у вигляді рядка | Запит властивостей |
+| `template_component` | Ідентифікатор шаблонного компонента Universal Theme | Запит властивостей |
+| `parent`, `group` | Фільтри компонента/групи властивостей | Запит властивостей |
+| `when` | Масив до 20 рядків припущень | Запит властивостей |
+| `list` | Boolean | Запит властивостей |
+| `supporting_objects` | Boolean | Preflight/doctor, перевірка середовища й подальший імпорт |
+| `fix_vocab` | Boolean | Локальна перевірка |
+
+Керувальні символи в текстових даних відхиляються. У шляхах також заборонені подвійні лапки й амперсанди. Схема містить спільні необов'язкові поля; побудовник команд визначає, які з них використовує конкретна дія. Зокрема, побудовник roundtrip-імпорту не передає `compiler_oracle_home` як параметр CLI.
+
+## Приклади вхідних даних
+
+Це об'єкти аргументів інструмента, а не shell-команди. Замініть умовні значення перевіреним контекстом проєкту.
+
+```json
+{"action":"workspace_probe"}
+```
+
+```json
+{"action":"local_validate","app_path":"applications/service-ops"}
+```
+
+```json
+{"action":"query_valid_props","list":true}
+```
+
+```json
+{"action":"runtime_preflight","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
+```
+
+```json
+{"action":"runtime_validate","app_path":"applications/service-ops","db_connection_name":"apex_dev","workspace_name":"SERVICE_OPS_DEV"}
+```
+
+## Результати та критерії успіху
+
+Успішні відповіді інструмента містять текст і `details`, зокрема `action`, `exitCode` та `outputRoot`. Серверна перевірка також повертає `liveValidationPassed` та `imported`, а за потреби — деталі вибору й цілі. Скасовані зміни проєкту повертають `cancelled=true`. Невдалі запуски породжують помилку з доступним виводом процесу та шляхом звітів; помилки вхідних даних до запуску можуть ще не мати звітів.
+
+| Операція | Докази, які перевіряє розширення |
+| --- | --- |
+| Локальні перевірки | Обгортка успішно завершується й виводить `APEXLANG_LOCAL_CHECK_OK`; окремі звіти містять діагностики. |
+| Серверна перевірка | Успішний результат процесу; `live_check_status=pass` **або** `validation_status=pass`; також `validation_sources.live_validator.status=pass`. |
+| Доказ відсутності нової цілі | Навмисно заблокований результат: `target_resolution_mode=create-new`, `target_resolution_status=not_found_in_workspace`, `create_new_confirmation_required=true`, `import_status=blocked`, `failure_class=create_new_confirmation_required` і `ok=false`. |
+| Імпорт | Успішний результат процесу та `validate_status=pass`, `import_status=pass`, `runtime_gate_status=pass`. |
+
+Самого коду завершення нуль недостатньо для успіху серверної перевірки чи імпорту. Перевірка відсутності нової цілі очікувано зупиняється на межі підтвердження; це ще не імпортований застосунок.
+
+## Сумісність із попередженнями
+
+Адаптер містить окремий шлях сумісності для результатів SQLcl, що містять лише попередження компіляції. Перш ніж нормалізувати результат чи продовжити погоджений імпорт, він перевіряє поточні артефакти, докази в транскрипті та, де потрібно, ідентичність цілі. Відсутні, застарілі, суперечливі докази або докази жорстких помилок залишаються блокувальними. Гілка create-new не використовує резервний шлях сумісності імпорту наявного застосунку.
+
+Цей механізм відокремлений від **рекомендаційної таблиці** ORDS/SQLcl, яка лише додає поради з діагностики. Див. [супровід](maintenance.md) і функції `normalizeWarningOnlyValidation` та `runWarningCompatibleImport` в [адаптері](../../extensions/lib/apexlang-cli.mjs).

package/extensions/apexlang/index.ts

@@ -28,6 +28,7 @@ import {
 
 const MAX_TOOL_OUTPUT = 80_000;
 const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
+const RPC_DIALOG_TIMEOUT_MS = 5 * 60 * 1000;
 const CHECK_ONLY_CHOICE = "Check APEXlang code (recommended) — stop after the successful live check";
 const IMPORT_CHOICE = "Check and import APEXlang code — revalidate and import in one SQLcl session";
 const UPDATE_EXISTING_CHOICE = "Update an existing app — require one proven remote target";
@@ -192,7 +193,11 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
       if (!ctx.hasUI) {
         throw new Error("This APEXlang action changes project files and requires interactive confirmation.");
       }
-      const confirmed = await ctx.ui.confirm("Confirm APEXlang project change", confirmationMessage(input));
+      const confirmed = await ctx.ui.confirm(
+        "Confirm APEXlang project change",
+        confirmationMessage(input),
+        { ...(signal ? { signal } : {}), timeout: RPC_DIALOG_TIMEOUT_MS }
+      );
       if (!confirmed) {
         return {
           content: [{ type: "text", text: "APEXlang project change cancelled." }],
@@ -264,10 +269,11 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
         };
       }
 
-      const choice = await ctx.ui.select("APEXlang live check passed. Choose the next step:", [
-        CHECK_ONLY_CHOICE,
-        IMPORT_CHOICE
-      ]);
+      const choice = await ctx.ui.select(
+        "APEXlang live check passed. Choose the next step:",
+        [CHECK_ONLY_CHOICE, IMPORT_CHOICE],
+        { ...(signal ? { signal } : {}), timeout: RPC_DIALOG_TIMEOUT_MS }
+      );
       if (choice !== CHECK_ONLY_CHOICE && choice !== IMPORT_CHOICE) {
         return {
           content: [
@@ -293,10 +299,11 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
             "APEXlang live check did not produce a valid application snapshot digest; import is blocked until it is revalidated."
           );
         }
-        const targetChoice = await ctx.ui.select("Choose the explicitly intended import target:", [
-          UPDATE_EXISTING_CHOICE,
-          CREATE_NEW_CHOICE
-        ]);
+        const targetChoice = await ctx.ui.select(
+          "Choose the explicitly intended import target:",
+          [UPDATE_EXISTING_CHOICE, CREATE_NEW_CHOICE],
+          { ...(signal ? { signal } : {}), timeout: RPC_DIALOG_TIMEOUT_MS }
+        );
         if (targetChoice !== UPDATE_EXISTING_CHOICE && targetChoice !== CREATE_NEW_CHOICE) {
           return {
             content: [
@@ -349,7 +356,8 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
           );
           createNewConfirmed = await ctx.ui.confirm(
             "Confirm new APEX application",
-            `Oracle proved that ${provenAlias} is absent from ${provenWorkspace}. Create it by rerunning validation and import together?`
+            `Oracle proved that ${provenAlias} is absent from ${provenWorkspace}. Create it by rerunning validation and import together?`,
+            { ...(signal ? { signal } : {}), timeout: RPC_DIALOG_TIMEOUT_MS }
           );
           if (!createNewConfirmed) {
             return {
@@ -472,6 +480,7 @@ export {
   ORDS_SQLCL_COMPATIBILITY,
   ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
   ORDS_SQLCL_COMPATIBILITY_TABLE,
+  RPC_DIALOG_TIMEOUT_MS,
   UPDATE_EXISTING_CHOICE,
   actionWritesProject,
   buildValidationCompatibilityAdvisory,

package/extensions/lib/apexlang-cli.d.mts

@@ -136,8 +136,7 @@ export function validateMaterializationPaths(options: {
 export function prepareRuntimeApp(
   input: ApexlangInput,
   cwd: string,
-  outputRoot: string,
-  options?: { forceStage?: boolean }
+  outputRoot: string
 ): Promise<{
   appPath?: string;
   staged: boolean;