feat: unify smartui-storybook into smartui-cli (built-in storybook command + TUI)

[chaitanyas-maker]

Unify @lambdatest/smartui-storybook into @lambdatest/smartui-cli

Prototype for team review. This folds the standalone Storybook CLI into the main CLI as a built-in storybook command, plus a terminal UI. Opened inside my fork for discussion — not for direct merge to upstream. Validated end-to-end against the live SmartUI cloud.

Why

The two packages both declare bin.smartui, so they collide on PATH — installing @lambdatest/smartui-storybook silently clobbers @lambdatest/smartui-cli (and vice-versa). Users need two installs for one tool. This PR makes one binary own the name and ships Storybook as a first-class command.

Approach — faithful relocation (not a rewrite)

Rather than re-plumb Storybook onto the CLI's createBuild/finalizeBuild lifecycle (which depends on an unverified backend question — see Open Questions), this vendors the proven, shipping @lambdatest/smartui-storybook v1.1.32 engine verbatim into the CLI under src/storybookVendor/, hitting the same /storybook/* endpoints it already uses in production. Behaviour is byte-identical to the standalone tool; only the collision and the double-install are removed.

What changed

• New command smartui storybook <url-or-dir> — URL mode (live server) and DIR mode (static build), identical grammar to the old package.
• New generator smartui config:create-storybook + a storybook block added to the ajv ConfigSchema (and anyOf, since top-level is additionalProperties:false).
• Vendored engine src/storybookVendor/** (12 .cjs modules) — the unique Storybook logic (story discovery, DOM/CSSOM serialize, filtering, zip+render) relocated and bundled by tsup.
• Terminal UI src/lib/tui.cjs — gradient figlet banner, boxed launch summary, and an end-of-run results box (dashboard link + screenshot/approval/change counts). Degrades gracefully with no TTY (CI-safe).
• Deps added: puppeteer, jsdom, archiver, form-data, cli-table3, proxy agents (engine); figlet, gradient-string, boxen, log-symbols, ora (TUI). pnpm-lock.yaml updated.

Notable engineering notes

• Vendored .js → .cjs so esbuild bundles them as CommonJS under the CLI's "type":"module" (otherwise module.exports is silently dropped).
• Fixed 3 sloppy-mode implicit globals (res, filename, githubURL) that only crash once bundled into strict mode.
• The results summary box is emitted on process.beforeExit because the engine doesn't fully await its polling — this guarantees it prints last.

Testing (live)

Built a 5-component / 17-story demo Storybook and ran it against SmartUI:

• Baseline: 51 screenshots, 0 changes.
• After a one-line rebrand (2 theme tokens): 24 changes / 9 unchanged — semantic-colored components correctly matched; brand-colored ones flagged, with per-story mismatch %.
• smartui --help, storybook --help, config:create-storybook, and a clean npm i -g <tarball> global install all verified.

Open questions for eng

1. Backend endpoint ownership — the deeper, "elegant" integration (reuse createBuild/finalizeBuild) needs confirmation that the CLI's visualui/1.0 client can reach the /storybook/* routes. This PR sidesteps it by vendoring; that refactor is the documented follow-up.
2. Versioning / deprecation — proposed 5.0.0 (MAJOR) + a deprecation shim on @lambdatest/smartui-storybook. Not done here.
3. Tests — needs the project's own test suite + a security pass before any real release.

Not included (deliberately)

Live publish, official version bump, deprecation shim, docs updates.

🤖 Generated with Claude Code

[sushobhit-lt]

Automated review of the storybook-unification PR. Scope: the hand-written TS/.cjs glue (vendored engine reviewed for defects but treated as a faithful relocation). Lint/syntax: the repo has no ESLint/Prettier config and no lint script; tsconfig.json is strict with noUncheckedIndexedAccess. No parse-level syntax errors found in the changed source. Main findings are in the URL-mode capture path (sendDoM in src/storybookVendor/commands/utils/dom.cjs and the URL branch of storybook.cjs), which appears untested — the described live test looks like it exercised DIR/static mode only. Details inline.

[sushobhit-lt]

[bug] dom is assigned with no declaration keyword (implicit global) — and so are clone (line 34) and element (line 37, the for…of binding). This is the exact class of defect the PR description says was fixed for res/filename/githubURL ("only crash once bundled into strict mode"), but these three were missed. esbuild bundles the ESM entry (src/index.ts), so this code runs strict → an assignment to an undeclared identifier throws ReferenceError: dom is not defined, breaking the whole URL-mode capture path. Even in sloppy mode it leaks JSDOM instances onto the global object on every story iteration. Declare it:

Suggested change

	dom = new JSDOM(html, {
	const dom = new JSDOM(html, {

[sushobhit-lt]

[bug] Same implicit-global issue — declare clone:

Suggested change

	clone = new JSDOM(html);
	const clone = new JSDOM(html);

[sushobhit-lt]

[bug] Same implicit-global issue — the loop variable element is undeclared:

Suggested change

	for(element of clone.window.document.querySelectorAll('img')) {
	for (const element of clone.window.document.querySelectorAll('img')) {

[sushobhit-lt]

[bug] In URL mode with no -c flag, storybookConfig falls back to defaultSmartUIConfig.storybook, which defines viewports but no resolutions key (see utils/config.cjs). So smartui storybook <url> without a config file throws TypeError: Cannot read properties of undefined (reading 'forEach') right here. (With a config file, validateConfig normalizes viewports→resolutions, which is why DIR-mode testing wouldn't surface it.) Guard with the viewports fallback:

Suggested change

	storybookConfig.resolutions.forEach(element => {
	(storybookConfig.resolutions || storybookConfig.viewports || []).forEach(element => {

[sushobhit-lt]

[nit] // @ts-nocheck disables all type checking for this new file in an otherwise strict project, so future regressions here (e.g. the options/target handling, the regex grab helper) won't be caught by tsup/tsc. Prefer typing the command callback params (commander infers them) and dropping the blanket suppression, or scope suppressions to the few lines that actually need them.

[chaitanyas-maker]

Thanks @sushobhit-lt — sharp review; all three [bug] items are addressed in 850ee15:

• dom.cjs:30/34/37 — declared dom / clone / element with const (as suggested). You're right these were the same implicit-global class as the res/filename/githubURL fixes and were missed by the first scan.
• storybook.cjs:23 — added the (resolutions || viewports || []) fallback guard so smartui storybook <url> with no -c flag doesn't crash on the default config.
• storybook.ts — also fixed a related root cause you'll want to know about: the command's local -c/--config collided with the root global, so --config never reached the engine and validateConfig never ran. Now merged via optsWithGlobals(). (Your storybook.cjs guard covers the no-config path; this covers the with-config path.)

You were exactly right that the live test only exercised DIR/static mode — I've since run URL mode end-to-end. After these fixes it completes the full pipeline (discover → puppeteer render → serialize → POST /storybook/render → build → finalize), but the backend returns Total Screenshots: 0 for both 17-story and 1-story runs. That points at the DOM-upload render path rather than the CLI glue — likely the same "backend endpoint ownership" open question in the PR description. DIR mode is fully green (51 screenshots, 24 diffs).

@ts-nocheck nit: acknowledged. Keeping it for now only because the vendored .cjs import has no type declarations; I'll scope it down / type the callback params as a follow-up rather than blanket-suppress.

[chaitanyas-maker]

Moved upstream: this is now proposed as a draft PR against LambdaTest/smartui-cli → LambdaTest#527 (includes the fixes from @sushobhit-lt's review here). Continuing review there.

[chaitanyas-maker]

Superseded by LambdaTest#527, which now carries the same branch rebased onto current stage. This PR targets prod, so after the rebase its diff also shows every stage-only commit, which makes it misleading to review. Closing in favour of LambdaTest#527.