Make the PO-token provider work right after a fresh install

[MrDix]

Problem

On a fresh machine without Node.js, the first install could finish with the PO-token provider unbuilt:

1. The provider setup installs Node.js automatically, but the same console session only probed %ProgramFiles%\nodejs afterwards. If the executable was not visible there yet (e.g. per-user install scope, or the session PATH not reflecting the registry update), the setup bailed out with "ACTION REQUIRED" and the provider was never cloned/built.
2. The GUI then shows the Queue button stuck on "loading..." forever, with only a console hint telling the user to re-run the install script. Running install\update.bat from a new terminal (fresh PATH, Node.js visible) fixed it - which is exactly the workaround a user had to discover by hand.

Fixes (two independent layers)

Installer robustness (setup_potoken_provider.bat): after installing Node.js, probe both the machine-wide and per-user install locations and, as a fallback, refresh PATH from the registry (machine + user) before re-checking. The provider build now proceeds in the same installer run.

GUI self-heal (potoken_provider.py): when Node.js and git are available but the provider server was never built, the GUI now runs the provider setup script itself on first launch - one-time, inside the existing background worker, never blocking the UI, output captured in .potoken/setup.log. Instead of "re-run the install script", the user sees:

[PO-Token] PO-token provider is not set up yet - downloading and building it now (one-time, this can take a few minutes)...
[PO-Token] Started PO-token provider (Node.js) - full-quality downloads enabled

Supporting changes:

• Both setup scripts (.bat/.sh) honor ULTRASINGER_POTOKEN_SKIP_WARMUP=1 to skip the installer-time warm-up step, since the GUI bootstrap starts (and thereby warms up) the server itself right afterwards.
• _PotokenWorker gains a progress signal so long-running provider steps are visible in the GUI console.
• The bootstrap is guarded: it only runs when the setup script exists, git is available, and Node.js is present; it honors the shutdown cancel event and a generous timeout; failures fall back to the existing setup hint (fail-open, as before).

Testing

• 8 new tests for the bootstrap path (skip conditions, cancel, env flag, success/failure, integration with ensure_provider); full GUI suite passes (164 passed).
• Ran the modified .bat end-to-end with the skip-warm-up flag: builds and exits 0 without the warm-up wait.
• Verified the new PATH-refresh block in an isolated harness with nodejs stripped from the session PATH: node is found again via the install-location probe / registry refresh.

Summary by CodeRabbit

• New Features

  • Added automatic recovery for incomplete local PO-token provider setup when Node.js is available.
  • Added setup progress updates to the application’s queue log.
  • Added an option to skip provider warm-up for faster or unattended startup.

• Bug Fixes

  • Improved Windows Node.js detection after installation by refreshing the current session’s PATH more reliably.
  • Provider setup failures now retain clear status information and guidance instead of interrupting startup.

[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: 16e1e003-8463-4a1d-bc6d-1160df705974

📥 Commits

Reviewing files that changed from the base of the PR and between d38ff29 and 24914bd.

📒 Files selected for processing (5)

• install/helpers/setup_potoken_provider.bat
• install/helpers/setup_potoken_provider.sh
• pytest/gui/test_potoken_provider.py
• src/gui/main_window.py
• src/gui/potoken_provider.py

---

📝 Walkthrough

Walkthrough

The PR adds self-healing Node provider bootstrapping, improves setup-script PATH handling, allows warm-up skipping, reports setup progress in the GUI, and adds tests for success, failure, cancellation, and fallback behavior.

Changes

PO-token provider bootstrap

Layer / File(s)	Summary
Setup script environment and warm-up behavior install/helpers/setup_potoken_provider.bat, install/helpers/setup_potoken_provider.sh	Windows setup now refreshes PATH using installation probes and registry values; both scripts can skip warm-up through ULTRASINGER_POTOKEN_SKIP_WARMUP.
Node provider bootstrap flow src/gui/potoken_provider.py	Missing Node provider entries trigger a cancellable, logged, timeout-bounded setup helper run before provider startup.
GUI progress and bootstrap validation src/gui/main_window.py, pytest/gui/test_potoken_provider.py	Setup progress is emitted to the queue log, with tests covering bootstrap outcomes and ensure_provider self-healing behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MainWindow
  participant _PotokenWorker
  participant ensure_provider
  participant _bootstrap_node_provider
  participant SetupHelper
  MainWindow->>_PotokenWorker: start provider setup
  _PotokenWorker->>ensure_provider: pass progress callback
  ensure_provider->>_bootstrap_node_provider: build missing Node provider
  _bootstrap_node_provider->>SetupHelper: run setup helper
  SetupHelper-->>_bootstrap_node_provider: create provider entry
  _bootstrap_node_provider-->>ensure_provider: return bootstrap result
  ensure_provider-->>_PotokenWorker: provider status and progress
  _PotokenWorker-->>MainWindow: append progress to queue log

Loading

Possibly related PRs

• MrDix/UltraSinger#77: Introduced the Node PO-token provider functionality extended by this PR.
• MrDix/UltraSinger#114: Relocated the provider setup scripts and updated their call sites.
• MrDix/UltraSinger#126: Added update-script calls to the same provider setup helpers.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: making the PO-token provider work on a fresh install.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 fix/potoken-first-install

---

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.}