Skip to content

fix(cli): validate collects @widget routes passed through a helper (#116) - #127

Merged
manish-wekan merged 3 commits into
nitrocloudofficial:developfrom
ROHIT-JR:fix/116-validate-helper-widgets
Nov 9, 2026
Merged

manish-wekan merged 3 commits into
nitrocloudofficial:developfrom
ROHIT-JR:fix/116-validate-helper-widgets

Conversation

@ROHIT-JR

@ROHIT-JR ROHIT-JR commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

Fixes #116.

Problem

nitrostack-py validate only found @widget routes written as string literals or WidgetOptions(route=...). The pizzaz template uses @widget(pizzaz_widget("pizza-map")), so its 3 widgets were never checked.

Change

_collect_widget_routes also collects:

  • @widget(helper("route")) (a call whose only argument is the route)
  • @widget(helper(route="route", ...))

A helper call with other positional arguments is skipped on purpose. Its first string is not necessarily the route, and a wrong guess would give false warnings. Routes found this way go through the same checks as before (valid segment, widgets/out/<route>.html exists and is not empty).

I used the source-pattern option from the issue. Collecting routes from the registered app at runtime would need the project to import and run, which validate avoids today.

Tests

  • tests/test_validate_widgets.py: helper-wrapped routes (positional, dotted, keyword) are collected, pass when the HTML exists, an unsafe route is reported, other positional arguments are not guessed.
  • Shipped templates: pizzaz reports its 3 routes, starter 1, flight-booking 6.
  • Removing pizza-list.html from a copy of the pizzaz template gives one file is missing warning.
  • tests/test_cli.py: runs the real validate command on a copy of the pizzaz template. Clean output first, then a warning for only the removed widget.

4 of the new tests and the CLI test fail without the fix. Full suite locally: 1330 passed. The failures are the code-mode template and wheel-build tests in tests/test_project_templates.py, which also fail on unmodified develop here because my venv lacks setuptools and the code-mode dependencies.

…itrocloudofficial#116)

@widget(helper("route")) and @widget(helper(route="route", ...)) are now
collected, so the pizzaz template's three widgets are checked. A helper call
with other positional arguments is skipped, since its first string is not
necessarily the route.
@manish-wekan

manish-wekan commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Check:

  1. Build this specific version of SDK, install it in isolated environment, run and create a project using it.
  2. Connect the project to nitrostudio
  3. Deploy to a temporary account on Nitrocloud,
  4. Connect that to claude/cursor/chatgpt and check widgets are rendering or not.
  5. Post Screenshots.

@ROHIT-JR

@manish-wekan

Copy link
Copy Markdown
Collaborator

Reviewed with develop (12e65b1) merged in: 1351 tests pass, the pizzaz template's 3 widgets are now found, and the new tests fail on the old code. Looks good to merge. Minor, can be a follow-up: any @widget(something("x")) with a single string argument is taken as a route, so an unrelated helper could produce a false "missing HTML" warning. Merge-order note: tests/test_cli.py grows to 1605 lines, above its 1589 baseline in #126.

~sent from claude-code

@ROHIT-JR

ROHIT-JR commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator Author

@manish-wekan results of the check you asked for, using the head of this PR (c876158).

  1. Build, isolated install, create project: done. Built the wheel from this branch, installed it in a clean venv, ran nitrostack-py init --template python-pizzaz. validate reports no issues (it now checks the 3 helper-wrapped widget routes). The project vendors this SDK build (vendor/nitrostack, 0.3.2), so the deploy used it.
  2. Connect to Nitrostudio: not done. The scaffold says Nitrostudio cannot folder-connect a Python project, so I connected over Streamable HTTP in step 4 instead.
  3. Deploy to Nitrocloud: done. Uploaded the project as a zip (no .env) to a temporary Nitrocloud account. It built and started. The MCP endpoint answers initialize, tools/list shows show_pizza_map, show_pizza_list and show_pizza_shop, and the 3 ui://widget/*.html resources read back as full HTML.
  4. Connected to ChatGPT as a custom MCP server and called all 3 tools. All three widgets open in the chat. Notes: the first attempt failed because I entered the base URL without /mcp, so use the /mcp URL. The map widget shows the panel and the shop cards but not the base map, with the message "Set MAPBOX_TOKEN in .env to load the map". That token is not part of the zip, so this is a missing config value, not a render failure.
  5. Screenshots:

show_pizza_shop (tonys-pizza)
show_pizza_shop

show_pizza_list (open now)
show_pizza_list

show_pizza_map (shows the MAPBOX_TOKEN message)
show_pizza_map

…tes (nitrocloudofficial#116)

An unrelated @widget(something("x")) call is no longer taken as a route, so it
cannot cause a false 'missing HTML' warning. Helpers are found by parsing the
project for functions that build a WidgetOptions (any file), plus WidgetOptions
itself. The CLI test moves to tests/test_validate_widgets.py and runs the real
command in a subprocess, so tests/test_cli.py stays at its 1589-line baseline.
@ROHIT-JR

ROHIT-JR commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator Author

@manish-wekan thanks, both points from your review are addressed in 7c3c9dd.

False positives from an unrelated helper. A helper call is now taken as a route only if it is WidgetOptions itself or a function in the project that builds a WidgetOptions (found by parsing every project file, so a helper defined in another file works). @widget(something("x")) is no longer collected, whether something is undefined or defined but unrelated. The pizzaz template's 3 widgets are still found. New tests cover the unrelated helper, a helper defined in another file, and WidgetOptions('x'). The unrelated-helper test fails on the previous commit.

test_cli.py size. I moved my CLI test out of tests/test_cli.py, so that file is back to its 1589-line baseline. The test now lives in tests/test_validate_widgets.py and runs the real validate command in a subprocess on a copy of the pizzaz template. I also ran the check script from #126 against this branch and it passes. validators.py is 499 lines, so it is under the 500 limit.

CI is green on 3.10, 3.11 and 3.12. The screenshots from the deployment check are in the comment above.

@jpsiddharth2008 jpsiddharth2008 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Pizzaz fix and file-length changes look good. Two false-positive cases remain:

  1. panel("dashboard") returning WidgetOptions(route="card", description=description) incorrectly checks for dashboard.html.
  2. Helper names are matched globally, so a widget factory named panel in one module can cause an unrelated panel elsewhere to be classified as a factory.
    Please verify that the argument feeds WidgetOptions.route, resolve helpers by their actual scope/import binding, and add regression tests for both case

…rocloudofficial#116)

validate used a project-wide name match, so panel('dashboard') was checked for
dashboard.html even when panel never passed that argument to WidgetOptions.route,
and an unrelated panel in another module could be taken for a widget factory.

Route discovery moves to nitrostack/cli/widget_routes.py and parses each file:

- a function is a factory only if one of its parameters reaches
  WidgetOptions(route=...) (directly, or through another factory) and is not
  reassigned
- the string is read from the argument at that parameter's position or keyword
- a call counts only if its name resolves through the calling module's own
  definitions and imports (local def, from-import, alias, import module,
  relative import, class staticmethod/classmethod) to a real factory
- a file that does not parse still yields its literal routes

validators.py keeps only the file walk, so it drops from 499 to 454 lines.
@ROHIT-JR

ROHIT-JR commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator Author

@jpsiddharth2008 thanks, both cases are fixed in e26a077. A name-based match could not fix them, so route discovery now parses each file and moves to nitrostack/cli/widget_routes.py.

1. The argument must feed route. A function counts as a factory only if one of its parameters reaches WidgetOptions(route=...), directly or through another factory, and the parameter is not reassigned. The string is read from the argument at that parameter's position or keyword. Your example now gives only card (the literal in WidgetOptions(route="card", ...)). dashboard.html is never checked. helper(True, 'x') with def helper(flag, route) takes 'x'.

2. Names resolve through the calling module's own scope. A call counts only if its name resolves to a real factory through that module's definitions and imports: a local def, from x import f, as aliases, import x then x.f(...), relative imports, from pkg import module, and class static or class methods. A local definition wins over an import of the same name. So an unrelated panel in another module, an undefined panel, and a panel imported from another library are all ignored. Bindings are matched per module, not per function, so an import written inside a function body is treated as module-wide.

Tests (8 new, all fail on the previous commit): the panel('dashboard') case, the reassigned and wrong-parameter cases, same helper name in an unrelated module, an undefined name, a third-party import, resolution through plain, aliased, module, relative and package imports, local definition shadowing an import, a factory that forwards to another factory, WidgetOptions aliases and attribute forms, and a file that does not parse. The old test that said extra positional arguments are never guessed is replaced by the position tests, since the route argument is now known exactly.

The pizzaz template still reports its 3 routes. CI is green on 3.10, 3.11 and 3.12. validators.py is down to 454 lines (the new module is 272), and the #126 file-length check passes.

@manish-wekan
manish-wekan merged commit fc85319 into nitrocloudofficial:develop Nov 9, 2026
3 checks passed
manish-wekan pushed a commit that referenced this pull request Nov 12, 2026
…orators in validate

Two regressions in the AST route discovery added in #127:

- A name re-exported through a project module (for example
  shared/__init__.py doing `from nitrostack import WidgetOptions`) was not
  followed, so `from shared import WidgetOptions` skipped the missing-HTML
  check. Name lookup now follows re-exports through project modules, with a
  guard against import cycles.
- Any decorator ending in `.widget` was treated as the SDK decorator, so
  `@pytest.mark.widget("smoke")` warned about a missing smoke.html. A
  `widget` decorator now counts only when it resolves to the SDK's own, by
  direct import, `import nitrostack`, or a project re-export.

Adds regression tests for both, including aliases, multi-hop and cyclic
re-exports, and a non-SDK name that is re-exported.
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.

3 participants