Skip to content

docs(desktop): document the missing-Node.js bootstrap recovery - #9135

Open
LIHUA919 wants to merge 1 commit into
loopx-project:mainfrom
LIHUA919:codex/app-nodejs-missing-9133
Open

LIHUA919 wants to merge 1 commit into
loopx-project:mainfrom
LIHUA919:codex/app-nodejs-missing-9133

Conversation

@LIHUA919

Copy link
Copy Markdown
Contributor

Fixes #9133

Goal / source

Issue #9133 (external report, LoopX 2.3.0 desktop App on a fresh MacBook): first boot stops on the recovery panel with 「安装程序退出(1);App 的启动环境未找到 Node.js…」 and empty report diagnostics.

Characterization (posted on the issue): this is the documented system-prerequisite path, not an M5-specific defect. The bundled-runtime installer runs scripts/install-local.sh, whose validate_release_candidate step executes loopx doctor --deep --installation-only; the required typescript_effect_runtime_ready check fails closed while node is missing (loopx/control_plane/runtime/node_probe.py resolves node via shutil.which), doctor exits 1, the installer exits 1, and the boot page combines runtime_install_exit_1 with environment.node_found=false. The App deliberately does not bundle Node (Node.js 22.22.3+, 24 LTS recommended; docs/guides/installing-loopx.md).

Current gap

The App README's Known Issues documents the fresh-Mac-without-Python analog (runtime_install_exit_2) with self-service steps, but has no entry for the Node analog, and its Prerequisites section lists only the dashboard-build Node floor (20.19+/22.12+), which understates the runtime requirement the installed App enforces.

Observable result

  • apps/desktop/loopx-control-plane/README.md Known Issues gains 「Fresh Mac without a usable Node.js stays on the boot screen」: cause, error code plus diagnostics fields (environment.node_found / node_version), the bounded node search paths, the Finder-versus-nvm/fnm/volta visibility caveat, and install-and-repair self-service steps mirroring the Python entry.
  • The Prerequisites Node bullet now states the actual runtime requirement (22.22.3+, 24 LTS recommended) and keeps the dashboard-build floor as the secondary case.

Docs-only change; no runtime, packaging or UI behavior changes.

Owning boundary

apps/desktop/loopx-control-plane/README.md (desktop App distribution documentation). No protocol/RFC pair touched, so the bilingual RFC gate is unaffected.

Validation

  • uv run --extra test loopx canary premerge --from-git-diff --git-diff-base upstream/main (from the clean worktree on latest main eb552a8bb): all direct checks, catalog canaries, risk-profile smokes and the public-boundary scan passed (exit 0), including loopx check --scan-path apps/desktop/loopx-control-plane/README.md.
  • Typecheck/tests: not applicable; no code paths changed.
  • DCO sign-off on the single commit.

The Known Issues section covers the fresh-Mac-without-Python failure
(runtime_install_exit_2) but not its Node analog: the bundled runtime
installer exits 1 when no usable Node.js is reachable, and the boot page
renders the install-and-repair guidance without a documented recovery
path. Add the parallel entry with the bounded search paths, the
Finder-versus-nvm visibility caveat and self-service steps, and align
the Prerequisites Node bullet with the runtime's actual 22.22.3+ (24 LTS
recommended) requirement instead of the dashboard-build-only floor.

Fixes loopx-project#9133

Signed-off-by: Lihua <[email protected]>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google DeepMind · self_reported

动机 / Motivation

受影响群体为:在未安装 Node.js、仅安装低于 22.22.3 版本,或仅通过 nvm/fnm/volta 安装 Node.js 后从 Finder 启动 LoopX Desktop App 的 macOS 用户与排查启动失败的支持人员。更新前:README 仅说明缺少 Python 的退出码 2 排障,且前置条件仅写明 20.19+ / 22.12+,用户遇到 runtime_install_exit_1 时无从定位 Finder PATH 隔离与 22.22.3+ 要求;更新后:Known Issues 对齐既有 Python 条目结构,明确列出错误码、诊断字段、有界搜索路径、nvm/fnm/volta 不可见原因及安装后点击 Repair this version 的自救步骤,Prerequisites 也同步区分运行时与构建门槛。apps/desktop/loopx-control-plane/README.md 精准补充了与实际 Rust/Shell/Python 实现逐项吻合的 Node.js 缺失排障指引和前置条件说明,且不改变任何可执行代码。本 PR 不改变桌面端是否捆绑 Node.js 的产品策略,不修改 runtime_search_path、boot.js 错误提示文案、30 秒环境缓存 TTL 或任何打包构建流程。

改动思路 / Approach

本 PR 响应 Issue #9133 对全新 Mac 启动停在恢复页问题的定性与后续承诺,选择在现有 apps/desktop/loopx-control-plane/README.md 的 Known Issues(紧邻 Python 缺失条目 runtime_install_exit_2)与 Prerequisites 两处原位增补说明,而不改动桌面端不捆绑 Node.js 的既定架构或引导代码。文档改动精准落在桌面分发说明归属文件 apps/desktop/loopx-control-plane/README.md 内,复用既有 Known Issues 版块与 CLI 安装基准,零侵入生产控制面与桌面原生代码。当前 PR 边界为:仅更新 apps/desktop/loopx-control-plane/README.md 中的 Known Issues 与 Prerequisites 说明,不引入任何打包策略、Tauri 缓存清除或运行时行为调整。从长期维护看,新增条目在结构与术语上与既有 Python 排障段落及 docs/guides/installing-loopx.md 完全一致。

具体改动 / Changes

本次改动(exact head ffc582292548e1692f32287d039370875f114b62)仅编辑 apps/desktop/loopx-control-plane/README.md(+33/-1 行),严格对照需求来源 https://github.com/loopx-project/loopx/issues/9133(版本 issue-9133-comment-2026-11-20T10:07:30Z)完成了两项要求:ISSUE-9133-KNOWN-ISSUE(在 Known Issues 新增「Fresh Mac without a usable Node.js stays on the boot screen」)与 ISSUE-9133-PREREQ(在 Prerequisites 中区分运行受管 TypeScript 运行时所需的 22.22.3+ / 推荐 24 LTS 与仅覆盖 dashboard 构建的 20.19+ / 22.12+)。

关键代码讲解

虽本 PR 为纯文档变更,审查已逐行交叉核验其引用的桌面启动与 Node 探测核心符号:

  1. apps/desktop/loopx-control-plane/src-tauri/src/services.rs#L1091-L1124(runtime_search_path):确认在 macOS 下精确按 ~/.local/bin、/opt/homebrew/bin、/usr/local/bin、/opt/homebrew/opt/node@24/bin、/usr/local/opt/node@24/bin、/opt/homebrew/opt/node@22/bin、/usr/local/opt/node@22/bin 及继承进程 PATH 的顺序拼接,且 bundled_runtime.rs#L199 与所有受管服务均复用同一函数 configure_runtime_environment。
  2. apps/desktop/loopx-control-plane/src-tauri/src/bundled_runtime.rs#L171-L285(install_snapshot):确认内置运行时通过 scripts/install-local.sh(第 672、883-885 行)运行 loopx --format json doctor --deep --installation-only,非零退出映射为 runtime_install_exit_{code}。
  3. loopx/control_plane/runtime/node_probe.py#L15,L106-L137(probe_node):确认 MINIMUM_NODE_VERSION = (22, 22, 3),经 shutil.which("node") 找不到或版本不足时在 loopx/release_candidate.py#L325-L349 使必选检查 typescript_effect_runtime_ready 失败,进而由 loopx/cli_commands/doctor.py#L92 返回退出码 1(fail-closed)。
  4. apps/desktop/loopx-control-plane/src-tauri/src/maintenance.rs#L799-L876(reinstall_bundled_runtime)与 static/boot.js#L191-L255:确认 Recovery & updates -> Diagnostics 准确暴露 error_code 与 environment.node_found / node_version,且点击 Repair this version 后重置 runtime_retry 并由 lib.rs#L230-L312 实时监督线程重连同一窗口而无需第二次重启 App;同时 scripts/dashboard.sh#L12 证实 20.19+ or 22.12+ 确实仅用于 dashboard 构建。

对主干的风险 / Risks

未发现阻塞性缺陷(No blocking findings)。变更不涉及可执行逻辑、公共 API、默认配置或双语 RFC 成对文件,因此无功能回归风险。唯一可指出的非阻塞细节观察是:maintenance.rs#L580,L632-L639 对 desktop_update_status 返回的 environment 诊断块设置了 30 秒缓存(ENVIRONMENT_TTL),而 reinstall_bundled_runtime 本身并不清空该缓存;因此在点击 Repair this version 时安装程序会立即使用最新的 runtime_search_path 重试并重连工作区,但若在 30 秒内紧接着再次失败,Diagnostics 文本中的 environment.node_found / node_version 需等待 TTL 过期或重开 App 才会刷新。该细节不影响自救步骤的正确性,无需阻塞本 PR。

本地独立验证结果(均在 ffc582292548e1692f32287d039370875f114b62 隔离 worktree 完成):

  • 相对链接核验(apps/desktop/loopx-control-plane/README.md 内 7 处图片链接):PASS(全部 exists=True)。
  • 底层安装校验与 Node 探测单测(tests/test_release_candidate.py、tests/control_plane/test_effect_runtime_node_probe.py、tests/test_doctor_installation_scope.py):PASS(6 passed + 50 passed)。
  • loopx check --scan-path apps/desktop/loopx-control-plane/README.md、双语 RFC 门禁与 loopx canary premerge --tier quick(3/3 catalog canaries + 1/1 public boundary):PASS。

我的整体评价 / Verdict

仅修改 apps/desktop/loopx-control-plane/README.md Markdown 文档,未触及前端 HTML/CSS/JS 或任何渲染界面。无(未在全新裸机 macOS 上执行实机 .app 安装点击,已通过源码逐行交叉核验及单元测试替代)。本 PR 对主干长程语义无扰动(long_horizon: preserved),对桌面端首次启动遇阻用户的排障体验有清晰正向改善(user_experience: improved),全部文档陈述、路径、版本要求与错误码均已对照 exact-head 源码逐项核实准确,公私边界与门禁检查全部通过,建议合入。

English verdict: APPROVE — exact head ffc582292548e1692f32287d039370875f114b62 accurately documents runtime_install_exit_1, environment.node_found/node_version, the bounded runtime_search_path, Finder-vs-nvm visibility, self-service repair, and the 22.22.3+ runtime vs 20.19+/22.12+ dashboard-build Node floor (56 passed in underlying release-candidate/node-probe tests, boundary scan and quick premerge PASS; no blocking findings).

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI · runtime_reported · xhigh

动机 / Motivation

在 macOS 首次打开 LoopX App 的用户,遇到安装退出 1 后需要知道 App 实际找到了哪个 Node 版本。 当 ~/.local/bin/node 先命中且报 22.22.2 时,保留已安装的 Homebrew Node 24,Core 仍报 node_unavailable。把前置入口指向合格 Node 后,同一个探测才通过。 新版说明把 App 的 Node 22.22.3 下限、诊断入口及修复按钮连到真实失败路径。 本次改动补的是 App README 的恢复步骤,现有安装器、路径策略和诊断字段仍由原代码维护。 缺口在于说明只引导安装另一个版本,少了识别并处理优先命中的旧版本这一步。 问题 #9133

改动思路 / Approach

保留 App 的路径顺序和 Core 的资格校验。README 需要让读者根据 App 的探测结果修复它最先命中的入口。 补齐受支持启动配置的解释和手动恢复,沿用已有诊断与修复入口。 终端里执行 node --version 只能验证交互式 shell。App 诊断报告的版本才对应本次修复所用的路径。单独链接安装指南无法指明这个差别。

具体改动 / Changes

审查提交 ffc5822。README 单文件 +33/-1,新增已知问题和自助步骤,更新运行要求。按基线安装指南核查三点。运行版本下限与 Core 一致。App 路径与诊断列出了正确的候选位置和错误字段。旧版本遮蔽时的恢复仍缺少判断和操作。

关键代码讲解

  • runtime_search_path 先排 ~/.local/bin,再排系统与 Homebrew 通用位置,最后才到 keg 路径和继承的 PATH。路径顺序
  • node_environment 报告第一个命中的文件与可解析版本。probe_node 检查同一个启动环境里实际选中的可执行文件是否合格。App 诊断 Core 探测
  • README 的第 2 步把安装 node@24 列为可直接修复的操作,前序版本会影响这个结果。自助步骤

对主干的风险 / Risks

[P2] 补上旧 Node 排在新安装之前时的修复步骤。 我用准确头的两段 Rust 路径逻辑和 Core 探测复核了先后顺序。缺少 Node 与只找到 22.22.2 均触发 node_unavailable。真正命中 Node 24.21.0 时,原探测通过。 当 ~/.local/bin/node 先命中且报 22.22.2 时,保留已安装的 Homebrew Node 24,Core 仍报 node_unavailable。把前置入口指向合格 Node 后,同一个探测才通过。 仅安装后序的 Homebrew keg 会让已按说明操作的用户再次收到同一个启动错误。补一条分支:node_found 为 true 但 node_version 过旧或缺失时,先用 App 的路径顺序核对并更新优先命中的 Node。装入后序 keg 不会自动替换前序入口,确认 App 报告了受支持版本再修复。

原 Node 探测与安装诊断 50 项通过。Quick premerge 的 4 项直接和 4 项选定检查均通过。

语义与 CI 对齐

沿用 runtime_install_exit_1、node_found、node_version 和 Core 的 node_unavailable。App 找到文件和 Core 认可版本是两次判断。用前序旧 Node 加后序受支持 keg 检查 README 步骤,再只替换前序入口并验证诊断版本变化。

我的整体评价 / Verdict

求改。这份说明能帮助完全缺少 Node 的用户,补上先命中旧版本的分支后也能覆盖诊断发现不可用版本的用户。这个修复只需要改文档。这次只改 README,App 恢复面板的界面和行为没有 diff。 本轮用 macOS 上的 Rust 路径选择函数与真实 Core Node 探测做配对。未安装 App 或执行 Tauri 修复、重启与重连,也未改本机 Node 安装。

English verdict: REQUEST_CHANGES at ffc5822. Document how to replace the earlier unsupported Node that still wins after a supported keg is installed.

1. Check the boot screen error code or Recovery & updates → Diagnostics
(`error_code: runtime_install_exit_1`, `environment.node_found` /
`node_version` confirm the missing runtime).
2. Install Node.js 22.22.3+ — for example `brew install node` (the keg-only

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 说明如何处理优先命中的旧 Node。 在当前 App 路径顺序下,若 ~/.local/bin/node 报 22.22.2,后面已安装的 node@24 不会被选中。实际解析和 Core 探测仍返回 node_unavailable。请在自助步骤里加上 node_found=true 且版本不合格时的操作,先更新 App 实际命中的入口,再用 App 诊断确认版本后重试。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: loopx app runing failed on macbook M5

2 participants