Skip to content

fix(pulse): declare runtime deps + show error state when /api/wiki fails#1261

Open
atabisz wants to merge 3 commits into
danielmiessler:mainfrom
atabisz:fix/docs-error-state
Open

fix(pulse): declare runtime deps + show error state when /api/wiki fails#1261
atabisz wants to merge 3 commits into
danielmiessler:mainfrom
atabisz:fix/docs-error-state

Conversation

@atabisz
Copy link
Copy Markdown
Contributor

@atabisz atabisz commented May 14, 2026

Problem

A fresh PAI 5.0.0 install hits two compounding defects when loading the Pulse /docs page:

  1. Undeclared runtime dependencies. Pulse's daemon imports minisearch (in modules/wiki.ts) and smol-toml (in pulse.ts, lib.ts, and others — to parse PULSE.toml), but neither is declared as a dependency anywhere in the release. pulse.log shows ResolveMessage: Cannot find package 'minisearch' and pulse.ts swallows the error, so /api/wiki/* falls through to Pulse's 404 handler. smol-toml would crash startup outright.
  2. Missing error branch in the React UI. docs/page.tsx destructures only data from useQuery. When the fetch errors, data is undefined — indistinguishable from the pending state — so the component falls through to the Loading... branch forever. The user sees an infinite spinner with no error and no console hint.

Either fix alone would mask the other.

Changes

1. Declare Pulse runtime dependencies

  • New Releases/v5.0.0/.claude/PAI/PULSE/package.json declaring minisearch ^7.2.0 and smol-toml ^1.6.1.
  • Co-located with pulse.ts so deps live next to the daemon that uses them.
  • Bun resolves dependencies upward, so bun install in PAI/PULSE/ is sufficient.

Scope note: the daemon also has optional imports for grammy, jose, and @anthropic-ai/claude-agent-sdk (used by the telegram, github-work, and imessage modules respectively, all wrapped in try/catch). These are deliberately not declared in this PR — they need an optionalDependencies vs. plain dependencies design decision and belong in a follow-up. grammy already shows up in pulse.log as a missing-package warning today; this PR doesn't change that.

Installer follow-up needed: the installer (install.sh / PAI-Install/engine/actions.ts) doesn't currently run bun install in PAI/PULSE/. That's a separate PR — declaring the deps is the prerequisite.

2. Surface fetch errors in the React UI

  • New WikiErrorState component — title, message, optional hint, retry button.
  • Both useQuery hooks now propagate isError, error, and refetch to the UI.
  • Error messages include the HTTP status code so the user sees HTTP 404 instead of a generic string.
  • No change to the success path.

Verification

  • Reproduced original bug locally: stopped the wiki module, /api/wiki → 404, /docs stuck on Loading... forever.
  • Applied error-UI patch: /docs now renders "Couldn't load the wiki — Failed to fetch wiki index (HTTP 404)" with a hint pointing to pulse.log and a Retry button.
  • Installed minisearch (mirroring what the new package.json declares), restarted Pulse: wiki module loads, /api/wiki/search returns 200, /docs renders normally.
  • Verified smol-toml is imported by 4 daemon files (pulse.ts, lib.ts, pulse-unified.ts, checks/github-work.ts) — load-bearing for PULSE.toml parsing.

Notes

  • Pre-existing Cannot find module 'react' TypeScript diagnostics in this directory are unrelated — Releases/v5.0.0/ ships without node_modules. Not introduced here.

atabisz added 2 commits May 14, 2026 21:37
…pi/wiki fails

The /docs page rendered "Loading..." forever when the wiki API returned
an error (e.g. when the Pulse wiki module failed to load minisearch and
all /api/wiki/* routes 404'd). The useQuery hooks ignored isError, so a
failed fetch was indistinguishable from a pending fetch.

Surface isError + error from both queries and render a WikiErrorState
component with the HTTP status, a hint, and a Retry button. The doc-detail
query gets the same treatment.

No behavioural change on the success path.
modules/wiki.ts imports minisearch but the dep was never declared
anywhere in the release. Fresh installs of PAI 5.0.0 silently fail to
load the wiki module, which makes /api/wiki return 404 and (combined
with the missing React Query error branch) leaves the /docs page stuck
on Loading... forever.

Add a PULSE-local package.json so 'bun install' in PAI/PULSE/ resolves
the dep alongside the daemon that uses it. Installer wiring (running
bun install during PAI bootstrap) is left to a follow-up PR.
@atabisz atabisz changed the title fix(pulse-docs): show error state instead of infinite Loading when /api/wiki fails fix(pulse): declare minisearch dep + show error state when /api/wiki fails May 14, 2026
pulse.ts, lib.ts, pulse-unified.ts, and checks/github-work.ts all
import smol-toml to parse PULSE.toml. Same defect class as minisearch:
not declared anywhere in the release, so a fresh install would crash
on startup before the wiki module even loads.

Optional module deps (grammy, jose, @anthropic-ai/claude-agent-sdk)
are deliberately deferred to a follow-up PR — they need an
optionalDependencies design discussion, not a blanket addition.
@atabisz atabisz changed the title fix(pulse): declare minisearch dep + show error state when /api/wiki fails fix(pulse): declare runtime deps + show error state when /api/wiki fails May 14, 2026
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.

1 participant