@glasshome/widget-cli 0.8.4 → 0.10.0

package/bin/cli.ts

@@ -27,6 +27,8 @@ Commands:
   build                  Build all widgets (per-widget, self-contained bundles)
   connect <url>          Connect to a running dashboard for live testing
                          --re-auth discards stored credentials and re-runs device approval
+  preview [name...]      Screenshot widgets' examples (light + dark) into preview/
+                         --isolate gives every render its own browser process
   validate [name]        Validate all widgets or a specific one
   publish [hub-url]      Build and publish a widget to Hub
   login [hub-url]        Authenticate with GlassHome Hub
@@ -42,6 +44,8 @@ Examples:
   glasshome-widget add
   glasshome-widget build
   glasshome-widget connect http://localhost:3333
+  glasshome-widget preview
+  glasshome-widget preview clock
   glasshome-widget validate
   glasshome-widget validate clock
   glasshome-widget info
@@ -65,6 +69,7 @@ const { values: flags, positionals } = parseArgs({
     bump: { type: "string" },
     scope: { type: "string" },
     "re-auth": { type: "boolean" },
+    isolate: { type: "boolean" },
     dry: { type: "boolean" },
     help: { type: "boolean", short: "h" },
   },
@@ -134,6 +139,14 @@ switch (effectiveCommand) {
     break;
   }
 
+  case "preview": {
+    const widgetDir = resolveWidgetDir();
+    await notifySdkUpdate(widgetDir);
+    const { runPreview } = await import("../src/commands/preview");
+    await runPreview(widgetDir, args, flags.isolate === true);
+    break;
+  }
+
   case "validate": {
     const widgetName = args[0];
     const widgetDir = resolveWidgetDir();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-cli",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "CLI for creating and managing GlassHome widgets",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "cli": "bun bin/cli.ts",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "files": [
@@ -16,19 +17,37 @@
     "template"
   ],
   "devDependencies": {
+    "@iconify/types": "^2.0.0",
     "@types/bun": "latest",
-    "@types/semver": "^7.0.0"
+    "@types/semver": "^7.0.0",
+    "playwright": "^1.40.0",
+    "typescript": "^5"
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
+    "@fontsource-variable/caveat": "^5.2.8",
+    "@fontsource-variable/geist": "^5.2.9",
+    "@fontsource-variable/geist-mono": "^5.2.8",
+    "@glasshome/sync-layer": "0.4.0",
     "@glasshome/widget-contract": "0.2.0",
-    "@glasshome/widget-sdk": "1.6.1",
+    "@glasshome/widget-sdk": "1.8.1",
+    "@iconify-json/lucide": "^1.2.0",
+    "@iconify-json/mdi": "^1.2.3",
+    "@tailwindcss/vite": "^4.1.13",
     "open": "^11.0.0",
     "picocolors": "^1.1.1",
     "semver": "^7.6.0",
     "ts-morph": "^28.0.0",
     "vite-plugin-solid": "^2.11.0"
   },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/glasshome/widget-cli.git"

package/src/commands/add.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { cancel, isCancel, log, text } from "@clack/prompts";
+import { defaultSdkRange, FALLBACK_SDK_RANGE } from "../utils/sdk-version";
 
 /** Capitalize kebab-case into PascalCase for component names. */
 function capitalize(str: string): string {
@@ -30,20 +31,30 @@ export function scaffoldWidget(
   const displayName = capitalize(widgetName);
   const widgetDescription = description || `A GlassHome dashboard widget: ${widgetName}`;
 
+  // The range the host checks before mounting, derived from the SDK this
+  // project actually builds against. Hardcoding it produced widgets that
+  // declared a 0.2-era range while running on 1.x, which reads as "pre-1.0" to
+  // `requiresCapabilities` and quietly excused them from declaring capabilities.
+  const sdkRange = defaultSdkRange(cwd) ?? FALLBACK_SDK_RANGE;
+
   // Read index.tsx template from the template directory
   const templateDir = resolve(import.meta.dir, "../../template");
   let srcContent = readFileSync(resolve(templateDir, "src/index.tsx.template"), "utf-8");
   srcContent = srcContent.replace(/WIDGET_NAME/g, displayName);
+  srcContent = srcContent.replace(/SDK_RANGE/g, sdkRange);
   writeFileSync(resolve(widgetDir, "index.tsx"), srcContent);
 
-  // Generate manifest.json
+  // Generate manifest.json. `capabilities` is required for any SDK >= 1.0.0
+  // range and an empty array is the honest default: a fresh widget reads
+  // nothing from Home Assistant, and the declaration is what consent shows.
   const manifest = {
     name: displayName,
     description: widgetDescription,
     minSize: { w: 1, h: 1 },
     maxSize: { w: 4, h: 4 },
     defaultSize: { w: 2, h: 2 },
-    sdkVersion: "^0.2.0",
+    sdkVersion: sdkRange,
+    capabilities: [],
     version: "0.1.0",
   };
   writeFileSync(resolve(widgetDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);

package/src/commands/build.ts

@@ -2,8 +2,15 @@ import { log, spinner } from "@clack/prompts";
 import { buildWidgets } from "@glasshome/widget-sdk/vite";
 import { lintAndReport } from "../utils/lint-source";
 import { withQuietStdout } from "../utils/quiet";
+import { typecheckAndReport } from "../utils/typecheck";
 
 export async function runBuild(cwd: string): Promise<void> {
+  const check = spinner();
+  check.start("Checking types...");
+  const typesOk = typecheckAndReport(cwd);
+  check.stop(typesOk ? "Types checked" : "Typecheck failed");
+  if (!typesOk) process.exit(1);
+
   const s = spinner();
   s.start("Building widgets...");
 

package/src/commands/create.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join, resolve } from "node:path";
 import { cancel, confirm, isCancel, log, note, spinner, text } from "@clack/prompts";
 import color from "picocolors";
+import { defaultSdkRange, FALLBACK_SDK_RANGE } from "../utils/sdk-version";
 import { getCliVersion } from "../utils/version";
 import { promptWidgetDetails, scaffoldWidget } from "./add";
 
@@ -125,6 +126,9 @@ export async function runCreate() {
     pkgContent = pkgContent.replace(/PROJECT_NAME/g, projectName as string);
     pkgContent = pkgContent.replace(/PROJECT_DESCRIPTION/g, projectDesc);
     pkgContent = pkgContent.replace(/CLI_VERSION/g, `^${getCliVersion()}`);
+    // Nothing is installed yet, so this comes from the SDK the CLI ships
+    // against. `bun widget upgrade` re-syncs it and every manifest later.
+    pkgContent = pkgContent.replace(/SDK_RANGE/g, defaultSdkRange() ?? FALLBACK_SDK_RANGE);
     writeFileSync(pkgPath, pkgContent);
 
     // Replace project-level placeholders in README.md

package/src/commands/preview.ts

@@ -0,0 +1,100 @@
+import { log } from "@clack/prompts";
+import color from "picocolors";
+import { runPreview as capturePreview } from "../preview/capture";
+import { withQuietStdout } from "../utils/quiet";
+
+/**
+ * Screenshot every widget's authored examples (light + dark) into
+ * `<project>/preview/`, rendered through the same constraints as the hub's
+ * render worker: frozen clock, DNS blackhole, per-render timeout, hash pin.
+ *
+ * Playwright is an OPTIONAL peer — the CLI stays Chromium-free by default — so
+ * detect it first and give an actionable install hint rather than a raw
+ * module-not-found when it is absent.
+ */
+export async function runPreview(cwd: string, names: string[], isolate: boolean): Promise<void> {
+  try {
+    await import("playwright");
+  } catch {
+    log.error("Preview needs Playwright + a Chromium build, which are not installed.");
+    log.info(`Install them with:\n  ${color.bold("bun add -d playwright && bunx playwright install chromium")}`);
+    process.exit(1);
+  }
+
+  // Capture the REAL stdout writer before withQuietStdout no-ops
+  // process.stdout.write. A clack spinner writes through that same override and
+  // would freeze inside the quiet block, so progress goes out this bound
+  // reference (which the override cannot intercept) as plain lines. Build/vite
+  // noise stays silenced; only these phase lines get through.
+  const realWrite = process.stdout.write.bind(process.stdout);
+  const progress = (m: string) => {
+    realWrite(`${color.gray("│")}  ${color.dim(m)}\n`);
+  };
+
+  log.info(names.length ? `Previewing ${names.join(", ")}` : "Previewing all widgets");
+
+  let summary: Awaited<ReturnType<typeof capturePreview>>;
+  try {
+    summary = await withQuietStdout(() =>
+      capturePreview({ projectDir: cwd, only: names, isolate, onProgress: progress }),
+    );
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  const hangs = summary.failures.filter((f) => f.kind === "hang");
+  const integrity = summary.failures.filter((f) => f.kind === "integrity");
+  const networkWidgets = [
+    ...new Set(summary.failures.filter((f) => f.kind === "network").map((f) => f.widget)),
+  ];
+  const attempted = summary.shots + hangs.length;
+
+  // Headline: plain count of what landed in preview/. A miss only matters if a
+  // render could not complete (hangs) or a bundle changed under us (integrity).
+  const out = color.cyan("preview/");
+  if (hangs.length || integrity.length) {
+    log.warn(`Rendered ${summary.shots} of ${attempted} previews into ${out}`);
+  } else {
+    log.success(`Rendered ${summary.shots} previews (light + dark) into ${out}`);
+  }
+
+  if (summary.skipped.length) {
+    log.message(color.dim(`No examples to render: ${summary.skipped.join(", ")}`));
+  }
+
+  // Real miss: a render still too slow after one retry. Its slot is left without
+  // a PNG; everything else rendered.
+  if (hangs.length) {
+    log.warn(
+      `Too slow to render, even after a retry (no image written):\n` +
+        hangs.map((f) => `  · ${f.widget}  ${f.detail}`).join("\n"),
+    );
+  }
+
+  // Should never happen: a bundle's bytes changed mid-run. This is a real
+  // problem, not a slow render.
+  if (integrity.length) {
+    log.error(
+      `A bundle changed while rendering (report this):\n` +
+        integrity.map((f) => `  · ${f.widget}`).join("\n"),
+    );
+  }
+
+  // Informational, not a failure: some widgets have no offline data and reach
+  // for the network. The request is blocked and nothing leaves the machine; the
+  // widget renders a placeholder. Expected for camera; worth a glance if another
+  // widget shows up here.
+  if (networkWidgets.length) {
+    log.message(
+      color.dim(
+        `Used a placeholder (no offline data; network blocked, nothing left the machine): ${networkWidgets.join(", ")}`,
+      ),
+    );
+  }
+
+  // Vite's dev server leaves live handles behind (file watchers, keep-alive
+  // sockets from browsers that crashed mid-render), so the process would sit
+  // idle forever after the verdict instead of exiting. Leave deliberately.
+  process.exit(hangs.length || integrity.length ? 1 : 0);
+}

package/src/commands/publish.ts

@@ -12,6 +12,7 @@ import {
   readManifest,
   writeManifest,
 } from "../utils/manifest";
+import { typecheckAndReport } from "../utils/typecheck";
 import { enforceCliVersion } from "../utils/version";
 import { runLogin } from "./login";
 
@@ -28,13 +29,7 @@ export async function runPublish(
 ): Promise<void> {
   const s = spinner();
 
-  // Step 1: Validate (quiet)
   const { runValidate } = await import("./validate");
-  const valid = await runValidate(cwd, undefined, { quiet: true });
-  if (!valid) {
-    log.error("Fix validation errors before publishing.");
-    process.exit(1);
-  }
 
   // Step 2: Authenticate
   const hubUrl = hubUrlOverride ?? getHubUrl();
@@ -167,7 +162,17 @@ export async function runPublish(
     writeManifest(cwd, widgetName, manifest);
   }
 
-  // Step 6: Build (async so spinner animates)
+  // Step 6: Typecheck, then build (async so spinner animates).
+  //
+  // Checked here rather than left to the project's own build script: a project
+  // scaffolded before the template ran tsc builds with a bare `vite build`, and
+  // publishing is the irreversible step. A project whose build already
+  // typechecks just pays it twice, which is cheap next to a bad publish.
+  s.start("Checking types...");
+  const typesOk = typecheckAndReport(cwd);
+  s.stop(typesOk ? "Types checked" : "Typecheck failed");
+  if (!typesOk) process.exit(1);
+
   s.start("Building widget...");
   const buildProc = Bun.spawn(["bun", "run", "build"], { cwd, stdout: "pipe", stderr: "pipe" });
   const buildExit = await buildProc.exited;
@@ -179,6 +184,15 @@ export async function runPublish(
   }
   s.stop("Build complete");
 
+  // Validate AFTER the build, not before: the build is what produces the
+  // manifest and bundle that get published, so validating beforehand checks a
+  // different document than the one that ships.
+  const valid = await runValidate(cwd, undefined, { quiet: true });
+  if (!valid) {
+    log.error("Fix validation errors before publishing.");
+    process.exit(1);
+  }
+
   // Step 7: Publish
   const distPath = resolve(cwd, "dist", `${widgetName}.js`);
 

package/src/commands/upgrade.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { log, note, spinner } from "@clack/prompts";
 import { discoverWidgets, readManifest, writeManifest } from "../utils/manifest";
+import { getInstalledSdkVersion } from "../utils/sdk-version";
 import { runValidate } from "./validate";
 
 /** Walk up from cwd looking for a package.json with a `workspaces` field. */
@@ -121,16 +122,30 @@ export async function runUpgrade(cwd: string): Promise<void> {
     } else {
       log.warn(`Synced to ${sdkVersion} but validation has warnings/errors. Check above.`);
     }
+    return;
+  }
+
+  // Standalone project. Bumping the dependency is still the author's call, but
+  // syncing the manifests to whatever is installed is not: a manifest range
+  // that excludes the installed SDK fails validation, and this is the command
+  // that error tells people to run.
+  const installed = getInstalledSdkVersion(cwd);
+  if (installed) {
+    syncManifestSdkVersions(cwd, installed);
+    const valid = await runValidate(cwd);
+    if (!valid) log.warn(`Synced manifests to ${installed}, but validation found problems above.`);
   } else {
-    log.info("Not inside the widget workspace. Upgrade @glasshome/widget-sdk manually:");
-    note(
-      [
-        "1. Bump @glasshome/widget-sdk in package.json peerDependencies",
-        "2. bun install",
-        "3. bun widget upgrade   (sync manifest files)",
-        "4. bun widget validate  (check compatibility)",
-      ].join("\n"),
-      "To upgrade",
-    );
+    log.warn("No @glasshome/widget-sdk installed here, so manifests were left alone.");
   }
+
+  log.info("To move to a different SDK version:");
+  note(
+    [
+      "1. Bump @glasshome/widget-sdk in package.json peerDependencies",
+      "2. bun install",
+      "3. bun widget upgrade   (sync manifest files)",
+      "4. bun widget validate  (check compatibility)",
+    ].join("\n"),
+    "To upgrade",
+  );
 }

package/src/commands/validate.ts

@@ -5,6 +5,7 @@ import {
   formatSchemaError,
   publishManifestSchema,
   requiresCapabilities,
+  satisfiesSdk,
 } from "@glasshome/widget-contract";
 import semver from "semver";
 import {
@@ -15,7 +16,7 @@ import {
   readRegistry,
   type WidgetManifest,
 } from "../utils/manifest";
-import { getProjectSdkVersion } from "../utils/version";
+import { getInstalledSdkVersion } from "../utils/sdk-version";
 
 interface ValidationResult {
   passed: boolean;
@@ -23,7 +24,7 @@ interface ValidationResult {
   warnings: string[];
 }
 
-function validateManifest(manifest: WidgetManifest): ValidationResult {
+function validateManifest(manifest: WidgetManifest, installedSdk: string | null): ValidationResult {
   const errors: string[] = [];
   const warnings: string[] = [];
   const hasValidMinSize =
@@ -47,6 +48,23 @@ function validateManifest(manifest: WidgetManifest): ValidationResult {
     }
   }
 
+  // The range must admit the SDK actually resolved in node_modules. Comparing
+  // it against the range declared in package.json only compares a claim with
+  // itself: both said "^0.2.0" while the build ran on 1.7.0, and it passed.
+  // An error, not a warning: a pre-1.0 range also excuses the widget from
+  // declaring capabilities, so a stale one silently leaves the 1.x contract.
+  if (
+    installedSdk &&
+    manifest.sdkVersion &&
+    manifest.sdkVersion !== "*" &&
+    semver.validRange(manifest.sdkVersion) &&
+    !satisfiesSdk(installedSdk, manifest.sdkVersion)
+  ) {
+    errors.push(
+      `sdkVersion "${manifest.sdkVersion}" excludes the installed SDK ${installedSdk}, so it claims a compatibility it was not built for; run \`bun widget upgrade\``,
+    );
+  }
+
   // INS-05: "*" sdkVersion is rejected at publish time, authors must declare
   // a real range (e.g. "^0.3.0"). Installed widgets that already ship "*" are
   // still tolerated by the loader with a warn-and-mount, but new publishes
@@ -157,8 +175,7 @@ export async function runValidate(
 
   const failed: string[] = [];
 
-  // Manifest sdkVersion range must admit the pinned SDK, else it lies about compatibility.
-  const projectSdk = getProjectSdkVersion(cwd);
+  const installedSdk = getInstalledSdkVersion(cwd);
 
   for (const name of toValidate) {
     if (!quiet) log.step(name);
@@ -175,7 +192,7 @@ export async function runValidate(
       continue;
     }
 
-    const result = validateManifest(manifest);
+    const result = validateManifest(manifest, installedSdk);
 
     if (result.errors.length > 0) {
       for (const err of result.errors) {
@@ -189,19 +206,6 @@ export async function runValidate(
       }
     }
 
-    if (
-      !quiet &&
-      projectSdk &&
-      manifest.sdkVersion &&
-      manifest.sdkVersion !== "*" &&
-      semver.validRange(manifest.sdkVersion) &&
-      !semver.satisfies(projectSdk, manifest.sdkVersion)
-    ) {
-      log.warn(
-        `  - manifest sdkVersion "${manifest.sdkVersion}" excludes the installed SDK ${projectSdk}; run \`bun widget upgrade\``,
-      );
-    }
-
     // Check bundle exists
     const bundlePath = resolve(cwd, "dist", `${name}.js`);
     if (!existsSync(bundlePath)) {