fix(platform): enforce strict path and version resolution

[zeegin]

Migrated from alkoleft/v8-runner-rust pr #37.
Original author: korolevpavel; created: 2026-07-21T23:23:41Z; last upstream update: 2026-07-26T23:48:02Z.
GitHub shows the migration account as the new author; this block preserves actual attribution.
Upstream historical base: master at d612e2d07e0702c6c829f3981d083022611f6373; head: korolevpavel:fix/platform-strict-hint at abc5c79097829d71c34a42ba0e8c3d8e359e1572. Active migrated PRs compare that exact head with the current IngvarConsulting/v8-runner-rust:master.
Upstream merged: 2026-07-26T23:48:02Z; merge commit: 0ae245c75bf8dd4d1f92cded6d243b9d7635bdc2.

---

Closes upstream #28.

What changed

• adds opt-in tools.platform.strict with fail-closed explicit path resolution
• validates exact four-component and prefix platform versions
• pins 1cv8, 1cv8c, and ibcmd to one canonical installation root in strict mode
• exposes typed path/version/source/installation-root metadata in launch JSON and MCP responses
• keeps legacy fallback behavior unchanged when strict mode is disabled
• supports primary strict: true with a machine-local path supplied by the local overlay
• hardens symlink containment, cache revalidation, Windows drive-relative PATH roots, and Windows case-insensitive executable/layout matching
• updates configuration schemas, README, and the repo-local agent skill

Verification

• locator: 38 passed
• utilities: 5 passed
• config/schema: 160 passed
• launch unit: 7 passed
• MCP service: 36 passed
• CLI, MCP stdio, and MCP HTTP launch metadata integration tests passed
• schema artifact freshness passed
• cargo fmt --all -- --check, cargo check --all-targets, and git diff --check passed
• independent whole-branch reviewer, tester, and Rust expert reviews are clean

Platform note

Windows-specific regressions cover cross-drive drive-relative PATH handling and case-insensitive executable/BIN/1CEDT identity. The local Homebrew Rust toolchain has no Windows standard-library target, so those cfg-gated tests require Windows CI/runtime confirmation.

Two pre-existing unrelated warnings remain in tool_extension.rs and process.rs.

Summary by CodeRabbit

• Новые возможности

  • Добавлен параметр tools.platform.strict для fail-closed резолва платформенных утилит без fallback-логики.
  • Команда launch теперь возвращает расширенные платформенные сведения: канонический путь, версия (или null), источник обнаружения и корень установки.

• Исправления

  • Нормализуются и корректно разрешаются относительные пути tools.platform.path.
  • В строгом режиме неподходящие версии/неизвестные версии/недостающие утилиты приводят к ошибке.

• Документация

  • Обновлены конфигурационные материалы, JSON-схемы и описание контракта результата launch.

[zeegin]

Upstream comment by coderabbitai[bot] at 2026-07-21T23:23:57Z: original

Walkthrough

Изменения добавляют tools.platform.strict, fail-closed разрешение платформенных утилит в каноническом installation root и metadata platform_resolution в JSON-результат команды launch. Обновлены модели, locator, схемы, документация и CLI/MCP-тесты.

Changes

Строгое разрешение платформы

Layer / File(s)	Summary
Контракт конфигурации src/config/*, docs/CONFIGURATION.md, docs/schemas/*, docs/superpowers/*, SKILL/references/*, src/use_cases/...	Добавлены tools.platform.strict со значением по умолчанию false, нормализация path, схемы, документация и обновлённые тестовые конфигурации.
Строгий locator и канонический выбор src/platform/locator.rs, src/platform/utilities.rs	Locator переведён на LocatorOptions, поддерживает strict/lenient-политики, канонические границы, проверку версий, sibling consistency, installation root и повторную проверку кэша.
Метаданные launch src/domain/launch.rs, src/use_cases/launch_app.rs, src/mcp/service.rs, tests/*, README.md, docs/CAPABILITIES.md	LaunchResult расширен полем platform_resolution; CLI и MCP-тесты проверяют канонические path, version, source и installation root только для результата launch.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant LaunchExecute
  participant Locator
  Client->>LaunchExecute: launch request
  LaunchExecute->>Locator: locate platform utility
  Locator-->>LaunchExecute: canonical resolution metadata
  LaunchExecute-->>Client: binary and platform_resolution

Loading

Possibly related PRs

• alkoleft/v8-runner-rust#13: затрагивает общий контур LaunchResult и launch_app, включая MCP-ожидание.
• alkoleft/v8-runner-rust#34: также изменяет LaunchResult и интеграцию launch_app.

Suggested reviewers: alkoleft

Poem

Кролик шепчет: strict включён,
Каноничный root сохранён.
Locator версии сверяет в ряд,
А launch метаданные хранит подряд.
Fallback закрыт — JSON сияет!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.70% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Название кратко и точно описывает переход на строгий резолв пути и версии платформы.
Linked Issues check	✅ Passed	Изменения соответствуют #28: strict-mode fail-closed, проверка версии, единый installation root и метаданные резолва добавлены и покрыты тестами.
Out of Scope Changes check	✅ Passed	Посторонних изменений не видно: docs, схемы, тесты и метаданные напрямую поддерживают strict platform resolution.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @​coderabbitai help to get the list of available commands.}

[zeegin]

Upstream comment by korolevpavel at 2026-07-22T05:28:41Z: original

@​coderabbitai review

[zeegin]

Upstream comment by coderabbitai[bot] at 2026-07-22T05:28:46Z: original

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[zeegin]

Upstream review by coderabbitai[bot]; state: COMMENTED; submitted: 2026-07-21T23:29:17Z; commit: 294a53ade8802164acddf3840d2da9da6d03b26b. Original review

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@​docs/superpowers/plans/2026-07-22-strict-platform-resolution.md`:
- Line 11: Change the “Task 1: Configuration and path normalization” heading
from level 3 to level 2 by using ## so the document’s heading hierarchy
satisfies markdownlint MD001.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 54f4ae7b-dbf4-47ab-baa5-969f5ae3b671

📥 Commits

Reviewing files that changed from the base of the PR and between be558db and 294a53a.

📒 Files selected for processing (27)

• README.md
• SKILL/references/config-and-backends.md
• docs/CAPABILITIES.md
• docs/CONFIGURATION.md
• docs/schemas/v8project.local.schema.json
• docs/schemas/v8project.schema.json
• docs/superpowers/plans/2026-07-22-strict-platform-resolution.md
• docs/superpowers/specs/2026-07-22-strict-platform-resolution-design.md
• src/config/loader.rs
• src/config/model.rs
• src/config/schema.rs
• src/config/validate.rs
• src/domain/launch.rs
• src/mcp/service.rs
• src/platform/locator.rs
• src/platform/utilities.rs
• src/use_cases/artifacts.rs
• src/use_cases/build_project.rs
• src/use_cases/check_syntax.rs
• src/use_cases/configure_extensions.rs
• src/use_cases/dump_config.rs
• src/use_cases/external_artifacts.rs
• src/use_cases/launch_app.rs
• src/use_cases/load_artifact.rs
• tests/cli_launch.rs
• tests/mcp_http.rs
• tests/mcp_stdio.rs

[zeegin]

Upstream review by coderabbitai[bot]; state: COMMENTED; submitted: 2026-07-26T23:46:29Z; commit: abc5c79097829d71c34a42ba0e8c3d8e359e1572. Original review

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/cli_launch.rs (1)

243-252: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Не допускайте тихого no-op при изменении тестовой конфигурации.

Если tools.client_mcp и tools.platform отсутствуют или изменились отступы, replace вернёт исходную строку, а helper молча запишет её обратно. В результате тест может проверять значения по умолчанию вместо настроенного сценария. Добавьте assert_ne!(updated, config, "configuration marker not found") или возвращайте ошибку из helper.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@​tests/cli_launch.rs` around lines 243 - 252, Ensure the configuration update
flow around the updated value detects when neither replacement marker is found:
assert that updated differs from config with the message "configuration marker
not found", or propagate an equivalent helper error before writing the
configuration. Preserve the existing replacement behavior when either
tools.client_mcp or tools.platform is present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@​tests/cli_launch.rs`:
- Around line 243-252: Ensure the configuration update flow around the updated
value detects when neither replacement marker is found: assert that updated
differs from config with the message "configuration marker not found", or
propagate an equivalent helper error before writing the configuration. Preserve
the existing replacement behavior when either tools.client_mcp or tools.platform
is present.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d3c80f73-ce7c-4579-b491-7da3db121dff

📥 Commits

Reviewing files that changed from the base of the PR and between 294a53a and abc5c79.

📒 Files selected for processing (18)

• SKILL/references/config-and-backends.md
• docs/CAPABILITIES.md
• docs/CONFIGURATION.md
• docs/schemas/v8project.local.schema.json
• docs/schemas/v8project.schema.json
• docs/superpowers/plans/2026-07-22-strict-platform-resolution.md
• docs/superpowers/specs/2026-07-22-strict-platform-resolution-design.md
• src/config/loader.rs
• src/config/model.rs
• src/config/schema.rs
• src/config/validate.rs
• src/domain/launch.rs
• src/mcp/service.rs
• src/platform/locator.rs
• src/platform/utilities.rs
• src/use_cases/dump_config.rs
• src/use_cases/launch_app.rs
• tests/cli_launch.rs

💤 Files with no reviewable changes (1)

• src/config/validate.rs

🚧 Files skipped from review as they are similar to previous changes (13)

• SKILL/references/config-and-backends.md
• docs/superpowers/plans/2026-07-22-strict-platform-resolution.md
• docs/CAPABILITIES.md
• docs/schemas/v8project.schema.json
• src/config/model.rs
• docs/schemas/v8project.local.schema.json
• src/use_cases/dump_config.rs
• src/domain/launch.rs
• docs/superpowers/specs/2026-07-22-strict-platform-resolution-design.md
• src/use_cases/launch_app.rs
• src/mcp/service.rs
• src/config/schema.rs
• src/platform/locator.rs

[zeegin]

Upstream inline review comment by coderabbitai[bot] at 2026-07-21T23:29:16Z; path: docs/superpowers/plans/2026-07-22-strict-platform-resolution.md, original line: 11. Original comment

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Исправьте уровень заголовка.

После # заголовок должен быть ##, иначе markdownlint выдаёт MD001.

Предлагаемое исправление

-### Task 1: Configuration and path normalization
+## Task 1: Configuration and path normalization

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

## Task 1: Configuration and path normalization

🧰 Tools

🪛 markdownlint-cli2 (0.23.0)

[warning] 11-11: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@​docs/superpowers/plans/2026-07-22-strict-platform-resolution.md` at line 11,
Change the “Task 1: Configuration and path normalization” heading from level 3
to level 2 by using ## so the document’s heading hierarchy satisfies
markdownlint MD001.

Source: Linters/SAST tools

✅ Addressed in commit 7286a7d