docs(plugin-manager): record why install failure diagnostics stay in the dialog
The install-log stream now carries every Host subprocess diagnostic the dialog needs, and the failed screen keeps the settled result's log path and stage. Record the decision, the rejected alternatives (client-side synthesis, a separate diagnostic block, a second stage field), and the coverage, and cross-link the guided-installation note it extends.
This commit is contained in:
1 parent
90838b790a
commit
fa4e32a503
6 files changed
+117
-4
No files matched your search
+2
-2
@@ -9,8 +9,8 @@
|
||||
en: edefff7cd986a509
|
||||
zh: a270839fa86976a2
|
||||
/agent-note-guided-plugin-installation/decision:
|
||||
en: 5448b9f8aaa9a569
|
||||
zh: 9024c5328c5da3bd
|
||||
en: ca0224ae08a4b383
|
||||
zh: 780603ca24487949
|
||||
/agent-note-guided-plugin-installation/alternatives-considered:
|
||||
en: be64b541f4d81e7c
|
||||
zh: 8600531c08ab4288
|
||||
|
||||
@@ -14,7 +14,7 @@ The install dialog put a spec straight into `pnpm add` and showed pnpm's termina
|
||||
|
||||
**A failed or cancelled installation restores the profile files.** `installBundle` snapshots `package.json` and `pnpm-lock.yaml` before pnpm runs and puts them back when pnpm fails, when the run is cancelled, or when the package pnpm added declares no bundle patch. This reverses, for installations only, the [manager's decision](2026-09-14-current-profile-plugin-management.md) to retain partial changes: an installation that did not produce a usable bundle must not leave a dependency the page cannot show. Removals keep that decision. Downloaded files can stay under `node_modules` and the pnpm store.
|
||||
|
||||
**A failed run is classified where the facts are.** `classifyInstallFailure` reads how the run ended and what pnpm printed — its `ERR_PNPM_*` codes and Node's errno names — into `packageResult.kind`. A run the manager terminated is classified `timeout` whatever exit status the signal left behind, so installation restores the files and removal reports failure instead of reading it as a success ([run bounds](../../../../packages/boot/plugin-manager/README.md)). The client shows the kind as one line and folds pnpm's output behind the details. Parsing the log is confined to this one function with a fixture-driven test.
|
||||
**A failed run is classified where the facts are.** `classifyInstallFailure` reads how the run ended and what pnpm printed — its `ERR_PNPM_*` codes and Node's errno names — into `packageResult.kind`. A run the manager terminated is classified `timeout` whatever exit status the signal left behind, so installation restores the files and removal reports failure instead of reading it as a success ([run bounds](../../../../packages/boot/plugin-manager/README.md)). The client shows the kind as one line and folds pnpm's output behind the details, which also name the complete log and a failure that stopped before pnpm ran ([details](../bug-fix/2026-10-28-plugin-install-failure-diagnostics.md)). Parsing the log is confined to this one function with a fixture-driven test.
|
||||
|
||||
**GitHub connection failures have a short budget before installation.** The Host runs a read-only `git ls-remote` check with the profile's Git and proxy configuration and a default `githubConnectionTimeoutMs` of 5000 ms. Credential helpers and prompts are disabled for this check, so authentication cannot consume the connection budget. Only network failures and timeouts prevent pnpm from starting; pnpm still owns authentication, HTTPS-to-SSH fallback, ref resolution and the full installation. The budget does not limit downloads or builds. The existing failure kind and `failedAt: 'spec-host'` let the Client show a connection error or timeout and offer a domestic registry for a replacement package spec. Cancellation and manager disposal terminate the check and its descendants before settling.
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ Status: implemented
|
||||
|
||||
**失败或被取消的安装恢复 profile 文件。** `installBundle` 在 pnpm 运行前快照 `package.json` 与 `pnpm-lock.yaml`,在 pnpm 失败、运行被取消、或 pnpm 装入的包没有声明组合包 patch 时把它们放回去。这只针对安装反转了[管理器的决定](2026-09-14-current-profile-plugin-management.zh.md)中"保留部分改动"的部分:没有产出可用组合包的安装,不能留下一个页面无法显示的依赖。删除仍沿用那个决定。已下载文件可能留在 `node_modules` 与 pnpm 缓存中。
|
||||
|
||||
**失败在事实所在处分类。** `classifyInstallFailure` 依据运行的结束方式和 pnpm 的输出——它的 `ERR_PNPM_*` 码和 Node 的 errno 名——给出 `packageResult.kind`。被管理器终止的运行,不论信号留下什么退出状态都归类为 `timeout`,因此安装会还原文件,删除则报告失败而不会读成成功([运行上界](../../../../packages/boot/plugin-manager/README.zh.md))。客户端把 kind 显示成一句话,把 pnpm 输出折叠进详情。对日志的解析只存在于这一个函数,用夹具驱动的测试钉住。
|
||||
**失败在事实所在处分类。** `classifyInstallFailure` 依据运行的结束方式和 pnpm 的输出——它的 `ERR_PNPM_*` 码和 Node 的 errno 名——给出 `packageResult.kind`。被管理器终止的运行,不论信号留下什么退出状态都归类为 `timeout`,因此安装会还原文件,删除则报告失败而不会读成成功([运行上界](../../../../packages/boot/plugin-manager/README.zh.md))。客户端把 kind 显示成一句话,把 pnpm 输出折叠进详情;详情还会指出完整日志,以及尚未运行 pnpm 就停下的一次失败([详情](../bug-fix/2026-10-28-plugin-install-failure-diagnostics.zh.md))。对日志的解析只存在于这一个函数,用夹具驱动的测试钉住。
|
||||
|
||||
**GitHub 连接失败在安装前有单独的短时限。** 宿主通过只读的 `git ls-remote` 检查连接,沿用 profile 的 Git 与代理配置,`githubConnectionTimeoutMs` 默认为 5000 毫秒。这次检查禁用凭据助手和认证提示,避免认证过程占用连接预算。只有网络失败与超时会阻止 pnpm 启动;认证、HTTPS 到 SSH 的回退、ref 解析及完整安装仍由 pnpm 负责。时限不约束下载或构建。已有的失败类型与 `failedAt: 'spec-host'` 让客户端显示连接失败或超时,并提供国内镜像供用户输入另一个包名。取消安装或销毁管理器会先终止检查及其子进程,再结束操作。
|
||||
|
||||
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# Bilingual-pair consistency record for 2026-10-28-plugin-install-failure-diagnostics.md (docs/i18n/README.md): per heading
|
||||
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
|
||||
# After editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.md
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog:
|
||||
en: dc13db49685fee98
|
||||
zh: 65896465ceaba16a
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/problem:
|
||||
en: 34c85dbc0fdaeeaf
|
||||
zh: b11042edb1eb8e3b
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/decision:
|
||||
en: f8237586c53da9f0
|
||||
zh: 739ccc9dab2a8ee0
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/alternatives-considered:
|
||||
en: 5fdda23e82951b8b
|
||||
zh: 6cceaa0037d29bbd
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/consequences:
|
||||
en: ec899115aa11cad7
|
||||
zh: e153f483c0165695
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/related:
|
||||
en: e0709383c16148e9
|
||||
zh: 00765408d0ad25f1
|
||||
/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/testing:
|
||||
en: 8ae5c8609bf85c76
|
||||
zh: a0569346855c0ead
|
||||
@@ -0,0 +1,44 @@
|
||||
# Agent Note: Install failures keep their diagnostics in the dialog
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-10-28-plugin-install-failure-diagnostics.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A failed plugin installation could show the generic sentence "Something went wrong during the install; the details say what" while its expanded details showed only "No output". The dialog rendered the live install-log stream and the failure kind, and the two Host diagnostics that explain such a failure never entered that stream. A pnpm run that printed nothing had its diagnostic (`result.shortMessage`, or `pnpm failed` as the fallback) written to the complete log and the returned result but never streamed, so the dialog's terminal stayed empty. The GitHub connection check that stops an installation before pnpm runs kept its captured output only in `packageResult.output`. The Client also ignored the settled result's `packageResult.logPath` and `stage`, so a failure with recorded diagnostics offered no path to the complete log and could not say that a finished installation failed while the bundle was being activated.
|
||||
|
||||
## Decision
|
||||
|
||||
**The install-log stream carries the Host diagnostic of every run the dialog shows.** A pnpm run that fails without printing anything streams the diagnostic the Host records for it, so the complete log and the dialog show the same text. The GitHub connection check reports the exact `git … ls-remote` command line it ran; when its network failure or timeout stops the installation, `installBundle` emits that command, the captured output, and the failure's exit status as the installation's only install-log run under the caller's request id. A check failure the installation survives streams nothing. A timed-out check has no exit code of its own, so its run settles without one instead of the exit status the timeout coerced.
|
||||
|
||||
**The failed screen keeps what the settled result reports, not only the live stream.** `InstallState` holds the settled `packageResult.logPath` and the details name it as the complete log. `InstallState['failure'].stage` (from the already-reported `ChangeResult.stage`) adds the sentence that the installation finished and enabling the bundle failed. Details without a streamed run say the installation produced no terminal output instead of "No output" under an install-location line that had no run to name. The generic sentence names the failed install command.
|
||||
|
||||
No wire type, public export, or config key is added: `ChangeResult.packageResult.logPath`, `ChangeResult.stage`, and `packageResult.timedOut` already carry these facts to every consumer. The check's command line is a module-local `GithubConnectionFailure` in `github-connection.ts`.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Have the Client synthesize a terminal run from `packageResult.output`.** Rejected: the install-log stream would stay incomplete for every other reader, including the agent tool and the complete Host log, and the dialog would carry two notions of a run — one streamed, one rebuilt from the result.
|
||||
|
||||
**Render `packageResult.output` as a separate Host-diagnostic block.** Rejected: it duplicates the terminal surface with a second styling and copy path, and the failing check's command line would still be missing.
|
||||
|
||||
**Add a failure-stage field to `ChangeResult`.** Rejected: `stage` already names installation and activation, and only activation needed its own sentence; a second stage vocabulary would make every consumer learn two fields for one fact.
|
||||
|
||||
**Keep the generic sentence and rely on the details.** Rejected: the empty details panel this fixes was exactly what the sentence pointed at, so the sentence must not promise diagnostics the dialog does not show.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A failed installation always offers something to act on: a pnpm diagnostic for a silent failure, the failing Git command and its output for a GitHub connection failure, the complete log path, and a sentence naming the failed step when activation failed after a finished installation.
|
||||
- The generic sentence becomes "The install command failed; the details say why" in every dictionary.
|
||||
- A GitHub connection failure reports `timedOut`, and its streamed run settles without an exit code.
|
||||
- No new configuration, wire field, or public package export.
|
||||
|
||||
## Related
|
||||
|
||||
[Guided plugin installation](../architecture/2026-09-15-guided-plugin-installation.md) owns the install dialog's screens, the pre-install spec check, and the failure classification; this note extends its failed screen and install-log stream.
|
||||
|
||||
## Testing
|
||||
|
||||
- `packages/boot/plugin-manager/tests/operations.spec.ts` pins the no-output diagnostic stream; `github-connection.spec.ts` pins the recorded command line and timeout state; `manager.spec.ts` pins the single streamed check run under the request id, its absent exit code on timeout, and that a check failure pnpm may resolve streams nothing.
|
||||
- `packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts` pins the settled log path and stage, including their reset on retry; `components.client.spec.tsx` pins the enabling sentence, the complete-log line, and the no-output sentence.
|
||||
- `apps/web/tests/plugin-install-github.e2e.ts` expands the details of a real GitHub connection failure and finds the Git command, its output, and the log path; `apps/web/tests/plugin-install-silent-failure.e2e.ts` fails a real installation through a package manager that prints nothing and finds the run's command line, its diagnostic, and the complete log in the details.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Agent Note: Install failures keep their diagnostics in the dialog
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-10-28-plugin-install-failure-diagnostics.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
一次插件安装失败时,界面可能显示通用的“安装过程中出错,原因见安装详情”,而展开后的详情只有“无输出”。对话框渲染的是实时的 install-log 流和失败 kind,而解释这类失败的 Host 诊断从未进入该流。打印了空输出的 pnpm 运行,其诊断(`result.shortMessage`,缺省为 `pnpm failed`)只写进完整日志和返回结果,从未被流式发送,因此对话框的终端一直是空的。在 pnpm 运行前就中止安装的 GitHub 连接检查,其捕获的输出只留在 `packageResult.output` 里。客户端同时也忽略了已结束结果中的 `packageResult.logPath` 和 `stage`,所以即使诊断已被记录,失败界面也没有指向完整日志的入口,也无法说明安装其实已经完成、失败发生在启用 bundle 时。
|
||||
|
||||
## Decision
|
||||
|
||||
**install-log 流携带对话框所展示的每一次运行的 Host 诊断。** 没有打印任何内容就失败的 pnpm 运行,会把 Host 为其记录的那条诊断流式发送出来,于是完整日志和对话框显示同样的文本。GitHub 连接检查会报告它实际执行的 `git … ls-remote` 命令行;当它的网络失败或超时中止安装时,`installBundle` 把该命令、捕获的输出和这次失败的退出状态作为该次安装唯一的 install-log 运行、以调用方的 request id 发出。安装仍能继续进行的检查失败不发送任何内容。超时的检查自身没有退出码,因此它的运行不带退出码结束,而不是超时被强制得出的那个状态。
|
||||
|
||||
**失败界面保留已结束结果所报告的内容,而不只是实时流。** `InstallState` 持有已结束的 `packageResult.logPath`,详情把它标为完整日志。`InstallState['failure'].stage`(来自本来就在上报的 `ChangeResult.stage`)补充一句话:安装已完成,启用 bundle 时失败。没有任何流式运行的详情会说明本次安装没有产生终端输出,而不是在一条没有运行可指名的安装位置行下面显示“无输出”。通用提示句会点明失败的是安装命令。
|
||||
|
||||
不新增 wire 类型、公开导出或配置键:`ChangeResult.packageResult.logPath`、`ChangeResult.stage` 和 `packageResult.timedOut` 本来就把这些事实带给每个消费方。检查的命令行是 `github-connection.ts` 内模块级的 `GithubConnectionFailure`。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**让客户端从 `packageResult.output` 合成一次终端运行。** 否决:对其他读取方(agent 工具和完整的 Host 日志)来说 install-log 流仍然不完整,而且对话框会出现两种“运行”的概念——一种来自流,一种从结果重建。
|
||||
|
||||
**把 `packageResult.output` 渲染成单独的 Host 诊断块。** 否决:它会以第二套样式和文案路径重复终端界面,而且失败检查的命令行仍然缺失。
|
||||
|
||||
**给 `ChangeResult` 新增失败阶段字段。** 否决:`stage` 已经区分安装和启用,而且只有启用需要自己的提示句;第二套阶段词汇会让每个消费方为一个事实学两个字段。
|
||||
|
||||
**保留通用提示句、只依赖详情。** 否决:这次要修的正是被该提示句指向的空详情面板,因此提示句不能承诺对话框并不显示的诊断。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 安装失败后总有可行动的信息:静默失败时的 pnpm 诊断、GitHub 连接失败时出错的 Git 命令及其输出、完整日志路径,以及安装完成后启用失败时点名失败步骤的一句话。
|
||||
- 通用提示句在所有词典中变为“安装命令失败,原因见安装详情”。
|
||||
- GitHub 连接失败会报告 `timedOut`,其流式运行不带退出码结束。
|
||||
- 不新增配置、wire 字段或公开包导出。
|
||||
|
||||
## Related
|
||||
|
||||
[Guided plugin installation](../architecture/2026-09-15-guided-plugin-installation.zh.md) 拥有安装对话框的各个界面、安装前的 spec 检查和失败分类;本记录扩展了它的失败界面和 install-log 流。
|
||||
|
||||
## Testing
|
||||
|
||||
- `packages/boot/plugin-manager/tests/operations.spec.ts` 钉住无输出诊断的流式发送;`github-connection.spec.ts` 钉住记录的命令行和超时状态;`manager.spec.ts` 钉住以 request id 发送的唯一检查运行、超时下缺失的退出码,以及 pnpm 可能自行解决的检查失败不发送任何运行。
|
||||
- `packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts` 钉住已结束的日志路径和 stage,包括重试时的重置;`components.client.spec.tsx` 钉住启用阶段的提示句、完整日志行和无输出提示句。
|
||||
- `apps/web/tests/plugin-install-github.e2e.ts` 展开一次真实 GitHub 连接失败的详情,找到 Git 命令、它的输出和日志路径;`apps/web/tests/plugin-install-silent-failure.e2e.ts` 让一次真实安装通过不打印任何内容的包管理器失败,并在详情中找到该运行的命令行、诊断和完整日志。
|
||||
Reference in new issue
Block a user