Skip to content

fix(hub-ui-onboard): stop an install that never finishes - #488

Merged
antfu merged 5 commits into
mainfrom
fix/onboard-install-timeout
Nov 10, 2026
Merged

antfu merged 5 commits into
mainfrom
fix/onboard-install-timeout

Conversation

@antfubot

@antfubot antfubot commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

When the package manager hangs after a click on Install, the panel waits forever. runInstall had no time limit on exec, so no error showed and no hint told the user to run the command in a terminal.

Now createOnboarding() takes an installTimeout option in milliseconds. The default is 5 minutes. When the install runs longer, runInstall kills the process and throws a new DF9009 diagnostic. The diagnostic names the command and tells the user to run it in a terminal. The panel shows it like other install errors, with a Retry button.

The limit uses its own timer and Promise.race, not tinyexec's timeout option. tinyexec still waits for the output pipes to close after the kill, and a grandchild process can keep them open. The new test covers that case.

On Windows, a kill does not reach child processes, and tinyexec runs a package manager's .cmd shim through cmd.exe. So the timeout runs taskkill /T /F to end the whole tree, the same way killProcessTree in @devframes/hub does. The kill can end the install with an exit code before the timer fires its error, so runInstall checks for the timeout first and always reports DF9009.

User prompts

Claude Opus 5.5 in Claude Code (inside Paseo). The user asked to fix #464 and open a PR.

Verification

  • packages/hub-ui-onboard/test/install.test.ts: a fake package manager that never exits and starts a grandchild that inherits stdio. With timeout: 300, runInstall rejects with DF9009 in under 5 s.
  • pnpm -C packages/hub-ui-onboard vitest run: 4 files, 24 tests pass.
  • pnpm lint, pnpm knip, pnpm typecheck, pnpm build: pass.
  • pnpm test: all pass except 2 devframe tests that need [::1] (dev.test.ts, initiate.test.ts). This sandbox has no IPv6 loopback, and this PR does not touch devframe.
  • Updated the @devframes/hub-ui-onboard d.ts snapshot for the new option.
  • CI: all jobs pass, including Windows on Node 22, 24, 26 and latest. One Ubuntu Node 26 run failed once on an unrelated @devframes/plugin-assets d.ts snapshot (union member order) and passed on re-run.
  • Not verified: a real hung pnpm 10 install through the panel.

Written with Claude Code. The user gave the task and has not reviewed the diff yet.

Add an `installTimeout` option (default 10 minutes). When the package
manager runs longer, the onboarding kills it and reports DF9009 with the
command to run in a terminal.

Closes #464
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
devframe Ready Ready Preview Nov 10, 2026 7:15am UTC

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/488?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-11-10 07:14 UTC
🔗 head 0b2da86
🤖 automated by pulls.review

{
  "headSha": "0b2da86c58136cb3feea20413df1298ffe1797a0",
  "result": {
    "overallSummary": "Fixes an onboarding install that could hang forever when the package manager never exits: adds an `installTimeout` option (default 5 minutes), a new `DF9009` diagnostic, and the process-killing logic behind it, plus tests and docs for the new behavior.",
    "groups": [
      {
        "key": "install-timeout",
        "label": "Install timeout",
        "summary": "Adds an `installTimeout` option (default 5 minutes) to `createOnboarding()`. `runInstall` now races the package-manager process against a timer, kills it (using `taskkill /T /F` on Windows to catch the whole process tree) when it exceeds the limit, and throws a new `DF9009` diagnostic so the panel can show a Retry error instead of hanging forever.",
        "category": "core",
        "filePaths": [
          "packages/hub-ui-onboard/src/install.ts",
          "packages/hub-ui-onboard/src/index.ts",
          "packages/hub-ui-onboard/src/types.ts",
          "packages/hub-ui-onboard/src/diagnostics.ts"
        ],
        "critical": true,
        "fileNotes": [
          {
            "path": "packages/hub-ui-onboard/src/install.ts",
            "text": "The timeout uses its own timer plus `Promise.race` rather than tinyexec's `timeout` option, because tinyexec still waits for output pipes to close after a kill; a grandchild inheriting stdio can keep them open."
          }
        ]
      },
      {
        "key": "tests",
        "label": "Install timeout tests",
        "summary": "New test simulates a hung package manager with a grandchild process that inherits stdio, verifying `runInstall` still rejects with `DF9009` within the expected time. The public-API type snapshot is updated for the new `installTimeout` option.",
        "category": "tests",
        "filePaths": [
          "packages/hub-ui-onboard/test/install.test.ts",
          "tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/hub-ui-onboard/test/install.test.ts",
            "text": "Spawns a grandchild process that keeps stdio open for 3s to reproduce the pipe-closing issue described in the install.ts change."
          }
        ]
      },
      {
        "key": "docs",
        "label": "Docs for DF9009",
        "summary": "Documents the new `installTimeout` option and adds the `DF9009` error reference page explaining cause and fix.",
        "category": "docs",
        "filePaths": [
          "docs/content/1.guide/23.hub-ui-onboard.md",
          "docs/content/6.errors/DF9009.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-10T07:14:09.921Z",
    "model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
    "locale": "en"
  }
}

@antfu
antfu merged commit fa998cc into main Nov 10, 2026
27 of 28 checks passed
@antfu
antfu deleted the fix/onboard-install-timeout branch November 10, 2026 07:24

This branch was successfully deployed

1 active deployment
Preview — 0b2da86c Deployed Nov 10, 2026 by vercel[bot]
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.

hub-ui-onboard: the install never settles when the package manager hangs

2 participants