Comfyui-Nodes-Stats/docs/plans/2026-06-21-trial-enable-design.md

# Design: Workflow tab + temporary trial-enable for disabled packages

Date: 2026-06-21
Status: Approved

## Summary

When a loaded workflow references node types that aren't currently resolvable,
Node Stats shows a **Workflow** tab that splits them into:

- **Missing** — the owning package is not installed (or unknown). Handled by
  ComfyUI Manager as usual (install).
- **Disabled** — the owning package is installed but disabled (in
  `custom_nodes/.disabled`). Offers two actions:
  - **Enable temporarily** — re-enable the package under a rolling 7-day trial.
  - **Enable permanently** — normal re-enable, never auto-disabled.

A temporarily-enabled package auto-disables again if it goes **7 distinct
boot-days without being used** in an executed prompt. Any execution use resets
the counter back to 7 (rolling window), so a package stays enabled as long as it
keeps getting used.

## Decisions (from brainstorming)

- **Graduation model:** rolling. Each execution use resets the counter to the
  full budget (7). 7 distinct boot-days unused → auto-disable. No permanent
  "graduation"; a trial package stays trial-managed, kept alive by use.
- **"Used" means:** the package's node appears in an *executed/queued* prompt.
  Reuses the existing usage tracking. Loading a workflow does not count.
- **Granularity:** the tab lists individual node types ("list by node"), but
  every action resolves to and operates on the owning *package* (Manager works
  per package). Trial state is tracked per package.
- **Surfacing:** on workflow load, if any node is disabled/missing, auto-open
  the Node Stats dialog to the Workflow tab.
- **Disabled actions:** both "Enable temporarily" (trial) and "Enable
  permanently".
- **Missing:** defer to ComfyUI Manager (install), as usual.
- **Orchestration (Approach A):** the Python backend only tracks trial state,
  counts boot-days, resets on use, and flags expiry. The frontend performs all
  ComfyUI-Manager enable/disable mutations (server is up, reuses the proven
  disable code, no coupling to Manager internals). Day-counting stays accurate
  across headless restarts; the actual auto-disable executes the next time the
  web UI loads.

## Data model

New SQLite table `trial_packages` in the existing DB:

| column | meaning |
|---|---|
| `package` (PK) | directory name (matches our package keys) |
| `enabled_at` | ISO timestamp the trial started |
| `last_use_day` | `YYYY-MM-DD` of last execution use (init = enable day) |
| `last_boot_day` | `YYYY-MM-DD` of last boot-day counted |
| `unused_boot_days` | counter, 0..budget |
| `budget` | distinct boot-days allowed unused (default 7) |

### Lifecycle

- **Start trial** (after frontend temp-enable): upsert with
  `unused_boot_days=0`, `last_boot_day=today`, `last_use_day=today`,
  `enabled_at=now`. The enable day never counts toward expiry ("not the same
  day").
- **Boot tick** (`tracker.tick_boot_days()`, called once at `__init__` import):
  for each trial row, if `last_boot_day != today`: `unused_boot_days += 1`,
  `last_boot_day = today`.
- **Expiry:** computed, not stored — `expired = unused_boot_days >= budget`.
- **Use reset** (`reset_trials_for(packages)`, called from `_record_prompt`
  after `record_usage`): for each used package on trial, set
  `unused_boot_days = 0`, `last_use_day = today`.
- **Stop trial** (`stop_trial(package)`): delete the row. Called after permanent
  enable, after the frontend disables an expired pack, or if re-disabled.

Disabling an already-disabled package via Manager is a no-op, so a stale trial
row (e.g. package disabled out-of-band) resolves cleanly on next expiry pass.

## Backend (Python)

- `tracker.py`: add table to `SCHEMA`; methods `start_trial`, `stop_trial`,
  `tick_boot_days`, `reset_trials_for(packages)`, `get_trials`.
- `__init__.py`:
  - At import: `tracker.tick_boot_days()` wrapped in try/except (never blocks
    extension load).
  - In `_record_prompt`: after `record_usage`, map used class_types → packages
    and call `tracker.reset_trials_for(packages)`.
  - Routes:
    - `GET /nodes-stats/trials` → `[{package, unused_boot_days, budget,
      days_remaining, expired, enabled_at, last_use_day}, ...]`
    - `POST /nodes-stats/trials/start` `{package}` → upsert trial
    - `POST /nodes-stats/trials/stop` `{package}` → delete trial

The backend never calls ComfyUI Manager.

## Frontend (JS)

- **WF-load hook:** wrap `app.loadGraphData` (and/or graph-changed event);
  collect node types present in the graph but not in
  `LiteGraph.registered_node_types` (unresolved).
- **Classify** unresolved types using:
  - `/customnode/getmappings?mode=local` → class_type → pack key
  - `/customnode/getlist?mode=local&skip_update=true` → pack install state
  - pack state `disabled` → Disabled bucket; `not-installed`/unmappable →
    Missing bucket. (Reconcile the getmappings pack key against getlist entries
    by id/cnr_id/aux_id — verify field names during implementation.)
- **Workflow tab**, auto-opened when ≥1 unresolved node:
  - Disabled rows (by node): `[Enable 7d]` (temp → Manager enable, then
    `trials/start`), `[Enable]` (permanent → Manager enable, then `trials/stop`
    if previously on trial). Show "on trial — N day-boots left" when applicable.
  - Missing rows (by node): `[Install]` → defer to Manager install.
  - Actions resolve to the owning package and dedupe.
- **Expiry execution:** on app load / dialog open, `GET /nodes-stats/trials`;
  for `expired` packs, disable via Manager (reuse existing disable code) →
  `trials/stop` → toast "auto-disabled N unused trial package(s)".
- Enable/disable need a restart to apply in the running session → reuse the
  existing restart banner.

## Error handling

- ComfyUI Manager absent → feature inert (no classification, no actions), same
  as the existing disable feature.
- HTTP/DB failures → toast + log; never corrupt trial state. Failed expiry
  disable keeps the row for a later session (retry).
- Package disabled out-of-band → expiry disable no-ops; row cleaned on stop.

## Testing

- `tests/test_trials.py` (pure logic, mocked dates like existing tests):
  - start_trial initializes counters; enable day not counted
  - tick_boot_days increments only on a new calendar day (same-day reboots = 1)
  - reset_trials_for zeroes the counter
  - expiry triggers at `unused_boot_days >= budget`
  - start/stop/get round-trips
- Frontend verified manually (graph load → tab → enable/disable → expiry).

## Known implementation risk

The **enable** payload (`/manager/queue/install` + `skip_post_install=true`)
needs the correct `id`/`version` for disabled packs — the same class of detail
as the disable-payload bug already fixed. Verify empirically against a live
disabled package during implementation rather than assuming.

## Files touched

- `tracker.py` — trial table + methods
- `__init__.py` — boot tick, usage reset hook, 3 routes
- `js/nodes_stats.js` — WF-load hook, classification, Workflow tab, actions,
  expiry execution
- `tests/test_trials.py` — backend unit tests
- `README.md`, `pyproject.toml` — docs + version bump