Comfyui-Nodes-Stats/docs/plans/2026-06-22-trial-install-design.md

Design: Trial-install (7-day) for missing nodes on workflow load

Date: 2026-06-22 Status: Approved

Summary

Extend the existing 7-day rolling trial from disabled packages to missing (not-installed) ones. When a loaded workflow references node types whose owning pack isn't installed, the Workflow tab's Missing section gains:

• Install 7d — really install the pack via ComfyUI Manager, then register a 7-day trial. If it isn't used (executed) within 7 distinct boot-days, it auto-disables (moves to .disabled, reversible) via the existing expiry path.
• Install — really install the pack permanently (no trial).

This makes trying out someone else's workflow non-committal: pull in what it needs, and anything you don't actually use gets parked in .disabled instead of permanently bloating the install (which slows boot — the whole point of this extension).

Decisions (from clarification)

• Expiry action: auto-disable (not uninstall). This is free: the trial table is keyed by package and processExpiredTrials() already disables any expired trial pack and clears its row. No new expiry code.
• Missing-row actions: both Install 7d and Install (permanent), symmetric with the Disabled section's Enable 7d / Enable. Both perform real installs from our UI; the current "open ComfyUI Manager" behavior becomes the failure fallback.

Current state it builds on (v1.6.0, verified)

• tracker.py: trial_packages table + start_trial / tick_boot_days / reset_trials_for / stop_trial / get_trials. Boot tick + usage reset + routes (/nodes-stats/trials[/start|/stop]) wired in __init__.py.
• js/nodes_stats.js:
  • classifyUnresolved() (≈624) → { disabled[], missing[] }; missing entries are { type, pkg: <getmappings packKey> } where packKey is a dir name, registry id, or repo/gist URL.
  • handleInstall(pkg, dialog) (≈1155) currently only opens Manager's Custom Nodes Manager.
  • runManagerEnable(payload) (≈701) = reset → POST /manager/queue/install → start → waitForQueue (install and enable share this endpoint; only the payload differs).
  • processExpiredTrials() (≈1192) disables expired trial packs via Manager, then stopTrial.
  • fetchManagerInfo() (≈483) returns installed/disabled packs only — it skips state==="not-installed", so registry data for missing packs is not in hand and must be fetched separately.

Install resolution (the only real new logic)

Not-installed getlist entries expose enough to install (verified live):

• CNR pack: id = cnr_id, version = semver, files = [git url].
• Git-only pack: no id, version = "unknown", files = [git url].

Plan:

1. resolveInstallTarget(packKey) — fetch /customnode/getlist?mode=local&skip_update=true, index not-installed entries by every identifier (key, id, files, repository) with the same normalize used in classifyUnresolved (lowercase, strip trailing /, .git), and return the matching entry (or null).
2. installPayload(entry) — mirror Manager's installNodes: { id: entry.id || <key>, version: entry.version, files: entry.files, channel:"default", mode:"cache", selected_version: entry.version==="unknown" ? "unknown" : "latest", skip_post_install:false, ui_id:<key> }.
3. Install via the existing runManagerEnable(payload) (same queue endpoint).
4. findInstalledDir(entry) — re-fetch getlist; find the now-installed entry matching entry by id/files/repo; its key is the directory name (needed to key the trial). Fallback: repo basename of files[0] (strip .git).
5. For Install 7d: POST /nodes-stats/trials/start { package: <dir name> }.
6. Show the restart banner: "Installed X — restart to load it" (+ " for a 7-day trial").

Components (all in js/nodes_stats.js)

• resolveInstallTarget(packKey), installPayload(entry), findInstalledDir(entry) — small, mostly-pure helpers.
• handleTrialInstall(pkg, dialog, temporary) — orchestrates resolve → install → dir discovery → (trial start if temporary) → restart banner; on any failure falls back to the existing open-Manager behavior of handleInstall.
• Missing rows render [Install 7d] + [Install]; wire them in wireWorkflowButtons. Reuse setWorkflowButtonsBusy, notify, showRestartBanner, managerIsBusy.

Data flow

Workflow tab (missing row)
  Install 7d -> resolveInstallTarget(packKey) -> installPayload
             -> runManagerEnable (POST install, start, wait)
             -> findInstalledDir -> trials/start{dir}
             -> restart banner "installed for 7-day trial"
  Install    -> same, minus trials/start
later boots  -> tracker.tick_boot_days (distinct days)
use in prompt-> tracker.reset_trials_for (counter -> 0)
expiry       -> processExpiredTrials (UI load) -> Manager disable + stopTrial

Error handling

• ComfyUI Manager absent → Missing actions inert (as today).
• resolveInstallTarget miss, install HTTP error, or git-url install blocked by Manager security level → toast + fall back to handleInstall's open-Manager guidance. No crash.
• findInstalledDir returns nothing (install didn't land) → don't register a trial; toast "installed; couldn't register trial — enable/disable manually".
• managerIsBusy() → ask the user to retry (same guard as enable/disable).

Testing

• Backend unchanged → no new pytest; existing tests/ stays green.
• Pure helpers (resolveInstallTarget matching, installPayload, findInstalledDir matching) written standalone; node --check for syntax.
• Manual: load a workflow needing a not-installed CNR pack → Install 7d installs it, /nodes-stats/trials shows the resulting dir, restart banner appears; Install (permanent) installs without a trial row; a git-url-only/blocked pack falls back to opening Manager; Manager-absent path inert.

Files touched

• js/nodes_stats.js — resolution helpers, handleTrialInstall, Missing-row buttons + wiring.
• README.md, pyproject.toml — docs + version bump (1.6.0 → 1.7.0).

Out of scope (YAGNI)

• Auto-uninstall on expiry (chose disable; reversible + free).
• Bulk "install all missing 7d" (start per-row; revisit if wanted).
• Replicating Manager's full dependency/security UX (fall back to Manager).