fix(coordinator): storageRoot host-native fallback 修同步下載 502

[monkey1sai]

Summary

Hotfix:bim-review-coordinator/src/config.ts loadConfig 對 storageRoot 的 default 寫死 /workspace/storage(docker container mount point)。Host-native(Windows / Linux)跑時沒設 STORAGE_ROOT env,node 把字串當 host 絕對路徑,Windows 上 fs.mkdir 拋 ENOTDIR: not a directory, mkdir 'C:\workspace',導致 POST /api/external/ifc-ready 的 ifcDownloader.downloadIfcToSharedVolume 全數 502 write_failed,fast-ifc-link-demo-loop (PR #92, archived 2026-05-21) happy path 走不通。

旁邊 storageHostRoot 已有 path.join(cwd, "storage") fallback,只有 storageRoot 漏接。本 PR 把 default 對齊,host-native 直接落在 <cwd>/storage(等同 bim-review-coordinator/storage/)。

重現

2026-05-22 用 Postman collection docs/postman/fast-ifc-link-demo.postman_collection.json 預設值對 host-native coordinator(:8004)送 POST /api/external/ifc-ready,coordinator 回:

HTTP 502
{
  \"detail\": \"IFC download failed\",
  \"ifc_ready_job_id\": \"ifcready_1779417827815_446a7c76\",
  \"error\": \"cannot create /workspace/storage/ifc-cache/ifcready_xxx: ENOTDIR: not a directory, mkdir '/workspace/storage'\",
  \"download_status\": \"failed\"
}

改動(3 files / +25 / -3)

File	變動
bim-review-coordinator/src/config.ts	storageRoot default /workspace/storage → path.join(cwd, \"storage\");欄位註解同步更新
bim-review-coordinator/src/services/ifcDownloader.ts	JSDoc 註解說明 docker compose / host-native 兩種來源
bim-review-coordinator/tests/config.test.ts	加 loadConfig storageRoot fallback describe,2 個 test(default → cwd / 顯式 env 保留)

Spec / Capability impact = NONE

fast-ifc-link-demo-loop (PR #92) implementation drift fix。local-coordinator-ifc-ready-intake-boundary SHALL 行為(同步下載 + 502 on failure)語意完全不變,只修 host-native default 不可用 → 因此不開新 OpenSpec change、不動 openspec/specs/。

Docker compose 行為驗證

compose.runtime-manager.yml:53,94 明確設 STORAGE_ROOT: /workspace/storage(env override 拿到 default 之前),改 default 不影響 container 路徑。

GitNexus impact

mcp__gitnexus__impact({target:\"loadConfig\", direction:\"upstream\"}) = LOW(direct = 0,只在 startup 被 import,不改 signature / 欄位語意,只動 default value)。

Verification

Level	Result
L1 coordinator npm run verify	11 files / 168 tests passed(從 166 → +2 storageRoot fallback tests)
L2 spec validate	skip(沒動 spec)
L3 GitNexus impact (pre-change)	loadConfig LOW
L4 真實 runtime 重跑 Postman happy path	跳過 — 會中斷現有 host-native coordinator(:8004),建議 merge 後手動重啟並重跑同份 Postman collection 確認 502 → 200 + viewer_url
L5 真實 UI	跳過(同 L4)

Test plan

• L1 全綠
• CI green
• Reviewer approve
• merge
• (post-merge)pull main + 重啟 coordinator + 重跑 Postman 確認 happy path 通

🤖 Generated with Claude Code

Summary by CodeRabbit

• Configuration Improvements

  • Storage path configuration is now environment-aware, automatically adapting to support both containerized and host-native deployments without requiring manual adjustments.

• Documentation

  • Clarified storage configuration semantics and default behavior across deployment scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e4a7bb79-a7a2-41d2-9094-f83e67c781bf

📥 Commits

Reviewing files that changed from the base of the PR and between 460d0b5 and f31ca2f.

📒 Files selected for processing (3)

• bim-review-coordinator/src/config.ts
• bim-review-coordinator/src/services/ifcDownloader.ts
• bim-review-coordinator/tests/config.test.ts

---

📝 Walkthrough

Walkthrough

This PR makes storage root configuration path-relative instead of container-absolute by defaulting to path.join(cwd, "storage") instead of the hardcoded "/workspace/storage", while preserving override capability through the STORAGE_ROOT environment variable. Configuration contracts, tests, and related documentation are updated accordingly.

Changes

Storage root configuration and fallback behavior

Layer / File(s)	Summary
Storage root configuration contract and implementation bim-review-coordinator/src/config.ts	CoordinatorConfig.storageRoot field comment clarified for write-path semantics; loadConfig() default changed from hardcoded "/workspace/storage" to dynamic path.join(cwd, "storage") when STORAGE_ROOT is unset.
Test isolation and storage root fallback validation bim-review-coordinator/tests/config.test.ts	Environment variable capture and restoration extended to include STORAGE_ROOT; new test suite validates storageRoot defaults to <cwd>/storage when unset and respects explicit STORAGE_ROOT override.
IFC downloader options documentation bim-review-coordinator/src/services/ifcDownloader.ts	IfcDownloadOptions.storageRoot comment updated to reflect coordinator write destination and new host-relative default.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A storage path so neat and bright,
From container walls to home-like light,
No more hardcoded /workspace/ lines,
Just cwd + storage by design,
Tests ensure the fallback shines! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title mixes English and Chinese, making it unclear. The English portion describes the main fix (storageRoot host-native fallback), but the Chinese segment (修同步下載 502) is cryptic and the overall title is confusing to English-speaking reviewers.	Revise the title to be clear and monolingual, e.g., 'fix(coordinator): storageRoot host-native fallback to resolve 502 error' or add a clarifying comment explaining the Chinese portion.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/hotfix/coordinator-storage-root-host-native-fallback

---

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 and usage tips.}

[Copilot]

Pull request overview

This PR hotfixes the bim-review-coordinator host-native default for storageRoot so synchronous IFC downloads write into a valid local directory when STORAGE_ROOT is not provided, preventing POST /api/external/ifc-ready from failing with 502 due to invalid path creation on Windows/Linux host-native runs.

Changes:

• Change loadConfig() storageRoot default from hard-coded /workspace/storage to path.join(process.cwd(), 'storage') (aligning with the existing storageHostRoot fallback).
• Clarify IfcDownloadOptions.storageRoot JSDoc to document docker-compose vs host-native behavior.
• Add unit tests verifying storageRoot fallback behavior and that explicit STORAGE_ROOT is respected.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
bim-review-coordinator/src/config.ts	Adjusts storageRoot default to <cwd>/storage to work on host-native environments while still allowing docker-compose override via env.
bim-review-coordinator/src/services/ifcDownloader.ts	Updates JSDoc to reflect the intended source of storageRoot under docker-compose vs host-native usage.
bim-review-coordinator/tests/config.test.ts	Adds coverage for the new storageRoot fallback and env override behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.