@glasshome/widget-cli 0.5.4 → 0.7.0

package/bin/cli.ts

@@ -31,6 +31,8 @@ Commands:
   login [hub-url]        Authenticate with GlassHome Hub
   info [name]            Show widget metadata and bundle info
   upgrade                Upgrade @glasshome/widget-sdk to latest version
+  migrate config         Rewrite widgets' raw-zod config to defineConfig + field.*
+                         --name <widget> targets one; --dry previews without writing
   help                   Show this help message
 
 Examples:
@@ -62,6 +64,7 @@ const { values: flags, positionals } = parseArgs({
     bump: { type: "string" },
     scope: { type: "string" },
     "re-auth": { type: "boolean" },
+    dry: { type: "boolean" },
     help: { type: "boolean", short: "h" },
   },
   allowPositionals: true,
@@ -163,7 +166,7 @@ switch (effectiveCommand) {
     const widgetName = args[0];
     const { runInfo } = await import("../src/commands/info");
     await runInfo(resolveWidgetDir(), widgetName);
-    outro("");
+    outro();
     break;
   }
 
@@ -174,6 +177,22 @@ switch (effectiveCommand) {
     break;
   }
 
+  case "migrate": {
+    const target = args[0];
+    if (!target) {
+      log.error("Missing target. Usage: glasshome-widget migrate config [--name <widget>] [--dry]");
+      process.exit(1);
+    }
+    const { runMigrate } = await import("../src/commands/migrate");
+    const ok = await runMigrate(resolveWidgetDir(), target, {
+      dry: flags.dry === true,
+      name: str(flags.name),
+    });
+    outro(ok ? "Done" : "Migration failed");
+    process.exit(ok ? 0 : 1);
+    break;
+  }
+
   default: {
     log.error(`Unknown command: ${command}`);
     console.log(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-cli",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "description": "CLI for creating and managing GlassHome widgets",
   "type": "module",
   "bin": {
@@ -22,9 +22,11 @@
   "dependencies": {
     "@clack/prompts": "^1.6.0",
     "@glasshome/widget-contract": "0.1.1",
-    "@glasshome/widget-sdk": "1.3.0",
+    "@glasshome/widget-sdk": "1.4.0",
     "open": "^11.0.0",
+    "picocolors": "^1.1.1",
     "semver": "^7.6.0",
+    "ts-morph": "^28.0.0",
     "vite-plugin-solid": "^2.11.0"
   },
   "repository": {

package/src/commands/build.ts

@@ -1,5 +1,7 @@
 import { log, spinner } from "@clack/prompts";
 import { buildWidgets } from "@glasshome/widget-sdk/vite";
+import { lintAndReport } from "../utils/lint-source";
+import { withQuietStdout } from "../utils/quiet";
 
 export async function runBuild(cwd: string): Promise<void> {
   const s = spinner();
@@ -8,12 +10,15 @@ export async function runBuild(cwd: string): Promise<void> {
   try {
     const solid = (await import("vite-plugin-solid")).default;
     process.chdir(cwd);
-    await buildWidgets({
-      srcDir: "src",
-      outDir: "dist",
-      plugins: [solid()],
-    });
+    await withQuietStdout(() =>
+      buildWidgets({
+        srcDir: "src",
+        outDir: "dist",
+        plugins: [solid()],
+      }),
+    );
     s.stop("Build complete");
+    lintAndReport(cwd);
   } catch (err) {
     s.stop("Build failed");
     log.error(err instanceof Error ? err.message : String(err));

package/src/commands/connect.ts

@@ -1,9 +1,12 @@
 import { existsSync, readdirSync, readFileSync, statSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { log, spinner } from "@clack/prompts";
+import { log, note, spinner } from "@clack/prompts";
+import color from "picocolors";
 import { buildWidgets } from "@glasshome/widget-sdk/vite";
 import { trpcMutate, trpcQuery } from "../utils/api";
 import { clearHostToken, extractHost, getHostToken, storeHostToken } from "../utils/auth";
+import { lintAndReport } from "../utils/lint-source";
+import { withQuietStdout } from "../utils/quiet";
 
 interface RegistryWidget {
   name: string;
@@ -33,7 +36,7 @@ async function uploadAndRegister(
 
   const bundlePath = resolve(distDir, `${slug}.js`);
   if (!existsSync(bundlePath)) {
-    log.warn(`Bundle not found: ${bundlePath} — skipping ${slug}`);
+    log.warn(`Bundle not found: ${bundlePath}, skipping ${slug}`);
     return;
   }
 
@@ -115,7 +118,7 @@ export async function runConnect(
 ): Promise<void> {
   const distDir = resolve(cwd, "dist");
   const solid = (await import("vite-plugin-solid")).default;
-  // delegateEvents: false — widgets run in closed shadow roots where Solid's
+  // delegateEvents: false, widgets run in closed shadow roots where Solid's
   // document-level event delegation cannot see the target.
   const buildOpts = {
     srcDir: "src",
@@ -129,7 +132,7 @@ export async function runConnect(
   try {
     const origCwd = process.cwd();
     process.chdir(cwd);
-    await buildWidgets(buildOpts);
+    await withQuietStdout(() => buildWidgets(buildOpts));
     process.chdir(origCwd);
   } catch (err) {
     s.stop("Build failed");
@@ -137,6 +140,7 @@ export async function runConnect(
     process.exit(1);
   }
   s.stop("Build complete");
+  lintAndReport(cwd);
 
   // Step 2: Check registry was generated
   const registryPath = resolve(distDir, "registry.json");
@@ -152,7 +156,7 @@ export async function runConnect(
 
   if (opts.reAuth) {
     clearHostToken(host);
-    log.info("Discarded stored credentials (--re-auth).");
+    log.info("Discarded stored credentials (--re-auth)");
   }
 
   // Validate stored token before using it
@@ -166,17 +170,17 @@ export async function runConnect(
         const body = (await check.json()) as { session?: unknown } | null;
         if (body?.session) {
           token = existingToken;
-          log.info("Using stored credentials for dashboard.");
+          log.info("Using stored credentials");
         } else {
           clearHostToken(host);
-          log.warn("Stored credentials expired — re-authenticating.");
+          log.warn("Stored credentials expired, re-authenticating");
         }
       } else {
         clearHostToken(host);
-        log.warn("Stored credentials expired — re-authenticating.");
+        log.warn("Stored credentials expired, re-authenticating");
       }
     } catch {
-      log.warn("Could not validate stored credentials — re-authenticating.");
+      log.warn("Could not validate stored credentials, re-authenticating");
     }
   }
 
@@ -218,7 +222,7 @@ export async function runConnect(
       log.warn(
         `Could not reach dashboard at ${api}: ${err instanceof Error ? err.message : String(err)}`,
       );
-      // token stays empty — caught by guard below
+      // token stays empty, caught by guard below
     }
 
     if (deviceCode!) {
@@ -284,7 +288,7 @@ export async function runConnect(
             s.stop("Device code expired");
             break;
           }
-          // Unexpected error — stop polling
+          // Unexpected error, stop polling
           s.stop(`Auth error: ${errData.error ?? res.status}`);
           break;
         } catch (err) {
@@ -303,7 +307,7 @@ export async function runConnect(
   }
 
   if (!token) {
-    log.warn("Authentication failed — widgets won't be connected. Log in at the dashboard first, then restart.");
+    log.warn("Authentication failed, widgets won't be connected. Log in at the dashboard first, then restart.");
     return;
   }
 
@@ -324,7 +328,7 @@ export async function runConnect(
       });
     }
   } catch {
-    // Non-fatal — dev mode may already be enabled
+    // Non-fatal, dev mode may already be enabled
   }
 
   // Step 5: Upload bundles and register widgets
@@ -358,7 +362,7 @@ export async function runConnect(
       const origCwd = process.cwd();
       process.chdir(cwd);
       try {
-        await buildWidgets({ ...buildOpts, only: widgets });
+        await withQuietStdout(() => buildWidgets({ ...buildOpts, only: widgets }));
       } finally {
         process.chdir(origCwd);
       }
@@ -371,7 +375,7 @@ export async function runConnect(
           await uploadAndRegister(apiUrl, distDir, widget, token);
           log.info(`Rebuilt & uploaded ${widgetName}`);
         } else {
-          log.warn(`No registry entry for ${widgetName} — skipping upload`);
+          log.warn(`No registry entry for ${widgetName}, skipping upload`);
         }
       }
     } catch (err) {
@@ -402,14 +406,19 @@ export async function runConnect(
       ).length
     : 0;
 
-  log.success(`Connected! ${widgetCount} widget(s) are live.`);
-  log.info("Bundles uploaded to API. Widgets registered with local paths.");
-  log.info("File changes auto-rebuild and re-upload. Add widgets with `bun widget add`.");
-  log.info("Press Ctrl+C to disconnect.");
-
-  // Step 7: Handle SIGINT — unregister and clean up
+  log.success(color.green(`Connected: ${widgetCount} widget(s) live`));
+  note(
+    [
+      `${color.cyan("watching")}  src/ (edits auto-rebuild & re-upload)`,
+      `${color.cyan("add")}       new widgets with ${color.bold("bun widget add")}`,
+      `${color.cyan("stop")}      press ${color.bold("Ctrl+C")} to disconnect`,
+    ].join("\n"),
+    "Live testing",
+  );
+
+  // Step 7: Handle SIGINT, unregister and clean up
   const cleanup = async () => {
-    log.info("\nDisconnecting...");
+    log.info("Disconnecting...");
     if (debounceTimer) clearTimeout(debounceTimer);
     watcher.close();
 
@@ -422,7 +431,7 @@ export async function runConnect(
           input: { scope: "local", name: slug },
         });
       } catch {
-        // Non-fatal — API may be down
+        // Non-fatal, API may be down
       }
     }
     log.info("Widgets unregistered");

package/src/commands/create.ts

@@ -9,7 +9,8 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { cancel, confirm, isCancel, log, spinner, text } from "@clack/prompts";
+import { cancel, confirm, isCancel, log, note, spinner, text } from "@clack/prompts";
+import color from "picocolors";
 import { getCliVersion } from "../utils/version";
 import { promptWidgetDetails, scaffoldWidget } from "./add";
 
@@ -157,8 +158,8 @@ export async function runCreate() {
       } else {
         installSpinner.stop(
           monorepoRoot
-            ? "Install failed — run `bun install` from the monorepo root"
-            : "Install failed — you can run `bun install` manually",
+            ? "Install failed, run `bun install` from the monorepo root"
+            : "Install failed, you can run `bun install` manually",
         );
       }
     }
@@ -167,7 +168,7 @@ export async function runCreate() {
     const inGitRepo = isInsideGitRepo(process.cwd());
 
     if (inGitRepo) {
-      log.info("Skipping git init — already in a git repository");
+      log.info("Skipping git init, already in a git repository");
     } else {
       const shouldGit = await confirm({
         message: "Initialize git repository?",
@@ -183,30 +184,29 @@ export async function runCreate() {
           Bun.spawnSync(["git", "commit", "-m", "Initial widget scaffold"], { cwd: targetDir });
           gitSpinner.stop("Git repository initialized");
         } else {
-          gitSpinner.stop("Git init failed — you can run `git init` manually");
+          gitSpinner.stop("Git init failed, you can run `git init` manually");
         }
       }
     }
 
     // Next-steps guide
-    log.info("");
-    log.step("Next steps:");
+    const cmd = (c: string, desc: string) => `${color.cyan(c.padEnd(30))} ${color.dim(desc)}`;
+    const steps: string[] = [];
     if (monorepoRoot) {
-      log.info("  bun install                Run from monorepo root to link workspace packages");
-      log.info(`  cd ${projectName}`);
+      steps.push(cmd("bun install", "from monorepo root, links workspace packages"));
+      steps.push(color.cyan(`cd ${projectName}`));
     } else {
-      log.info(`  cd ${projectName}`);
-      if (isCancel(shouldInstall) || !shouldInstall) {
-        log.info("  bun install");
-      }
+      steps.push(color.cyan(`cd ${projectName}`));
+      if (isCancel(shouldInstall) || !shouldInstall) steps.push(color.cyan("bun install"));
     }
-    log.info("  glasshome-widget connect <url>   Connect to a running dashboard for live testing");
-    log.info("  glasshome-widget add             Add another widget to the project");
-    log.info("  glasshome-widget build            Build all widgets");
-    log.info("  glasshome-widget validate        Validate all widgets");
-    log.info("  glasshome-widget publish          Build & publish to GlassHome Hub");
-    log.info("  glasshome-widget info             Show widget metadata");
-    log.info("  glasshome-widget upgrade          Upgrade @glasshome/widget-sdk");
+    steps.push(cmd("bun widget connect <url>", "connect to a dashboard for live testing"));
+    steps.push(cmd("bun widget add", "add another widget"));
+    steps.push(cmd("bun widget build", "build all widgets"));
+    steps.push(cmd("bun widget validate", "validate all widgets"));
+    steps.push(cmd("bun widget publish", "build & publish to GlassHome Hub"));
+    steps.push(cmd("bun widget info", "show widget metadata"));
+    steps.push(cmd("bun widget upgrade", "upgrade @glasshome/widget-sdk"));
+    note(steps.join("\n"), "Next steps");
   } catch (err) {
     s.stop("Failed to scaffold widget project.");
     rmSync(targetDir, { recursive: true, force: true });

package/src/commands/info.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { log } from "@clack/prompts";
+import { log, note } from "@clack/prompts";
+import color from "picocolors";
 import {
   discoverWidgets,
   formatBytes,
@@ -18,8 +19,6 @@ export async function runInfo(cwd: string, widgetName?: string): Promise<void> {
   }
 
   const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  log.info(`Project: ${pkg.name ?? "unknown"}`);
-  log.info(`Version: ${pkg.version ?? "0.0.0"}`);
 
   const widgets = discoverWidgets(cwd);
 
@@ -35,44 +34,40 @@ export async function runInfo(cwd: string, widgetName?: string): Promise<void> {
     process.exit(1);
   }
 
-  log.info(`\nWidgets: ${widgets.length} total`);
+  log.step(
+    `${color.bold(pkg.name ?? "unknown")} ${color.dim(`v${pkg.version ?? "0.0.0"}`)} ${color.dim("·")} ${widgets.length} widget(s)`,
+  );
 
-  for (const name of toShow) {
-    log.info(`\n--- ${name} ---`);
+  // Right-pad labels so values line up inside the note box.
+  const field = (label: string, value: string) => `${color.dim(label.padEnd(9))} ${value}`;
 
+  for (const name of toShow) {
     try {
       const manifest = readManifest(cwd, name);
-      log.info(`  Name:        ${manifest.name}`);
-      log.info(`  Min Size:    ${manifest.minSize.w}×${manifest.minSize.h}`);
-      log.info(`  Max Size:    ${manifest.maxSize.w}×${manifest.maxSize.h}`);
-      if (manifest.defaultSize) {
-        log.info(`  Default:     ${manifest.defaultSize.w}×${manifest.defaultSize.h}`);
-      }
-      log.info(`  SDK Version: ${manifest.sdkVersion}`);
-      if (manifest.version) {
-        log.info(`  Version:     ${manifest.version}`);
-      }
-      if (manifest.description) {
-        log.info(`  Description: ${manifest.description}`);
-      }
+      const lines: string[] = [];
+
+      const size = (s: { w: number; h: number }) => `${s.w}×${s.h}`;
+      lines.push(field("Size", `${size(manifest.minSize)} → ${size(manifest.maxSize)}`));
+      if (manifest.defaultSize) lines.push(field("Default", size(manifest.defaultSize)));
+      lines.push(field("SDK", manifest.sdkVersion));
+      if (manifest.version) lines.push(field("Version", manifest.version));
+      if (manifest.description) lines.push(field("About", color.dim(manifest.description)));
 
-      // Bundle size (if built)
       try {
         const info = getWidgetBundleInfo(cwd, name);
-        log.info(`  Bundle:      ${formatBytes(info.raw)} (${formatBytes(info.gzip)} gzipped)`);
+        lines.push(field("Bundle", `${formatBytes(info.raw)} (${formatBytes(info.gzip)} gzipped)`));
       } catch {
-        log.info("  Bundle:      not built yet");
+        lines.push(field("Bundle", color.dim("not built yet")));
       }
+
+      note(lines.join("\n"), `${manifest.name} ${color.dim(`(${name})`)}`);
     } catch (err) {
-      log.warn(`  Could not read manifest: ${err instanceof Error ? err.message : String(err)}`);
+      log.warn(`${name}: could not read manifest: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
-  // Registry summary
   const registry = readRegistry(cwd);
   if (registry) {
-    log.info(
-      `\nRegistry: ${registry.widgets.length} widget(s) (generated ${registry.generatedAt})`,
-    );
+    log.info(`Registry: ${registry.widgets.length} widget(s) (generated ${registry.generatedAt})`);
   }
 }

package/src/commands/login.ts

@@ -39,7 +39,7 @@ export async function runLogin(hubUrl?: string): Promise<void> {
   }>((resolve, reject) => {
     const timeout = setTimeout(() => {
       server.close();
-      reject(new Error("Login timed out — no response from browser within 120 seconds."));
+      reject(new Error("Login timed out, no response from browser within 120 seconds."));
     }, LOGIN_TIMEOUT_MS);
 
     const server = createServer((req: IncomingMessage, res: ServerResponse) => {
@@ -96,17 +96,16 @@ export async function runLogin(hubUrl?: string): Promise<void> {
     });
   });
 
-  s.stop("Login complete");
+  s.stop("Browser login complete");
 
-  // Verify state
+  // Verify state (spinner already stopped, use log, not s.stop)
   if (receivedState !== state) {
-    s.stop("Login failed");
     log.error("State mismatch. Possible CSRF attack.");
     process.exit(1);
   }
 
   // Exchange code for tokens
-  s.message("Exchanging code for tokens...");
+  s.start("Exchanging code for tokens...");
 
   const tokenRes = await fetch(`${hub}/api/auth/oauth2/token`, {
     method: "POST",

package/src/commands/migrate.ts

@@ -0,0 +1,93 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { log } from "@clack/prompts";
+import { migrateConfigSource } from "../migrate/config-codemod";
+import { discoverWidgets } from "../utils/manifest";
+
+/** All `.ts`/`.tsx` source files under a widget dir. */
+function widgetSourceFiles(cwd: string, widget: string): string[] {
+  const dir = resolve(cwd, "src", widget);
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const entry of readdirSync(d)) {
+      const p = join(d, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if ((entry.endsWith(".ts") || entry.endsWith(".tsx")) && !entry.endsWith(".d.ts"))
+        out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export interface MigrateOptions {
+  dry?: boolean;
+  name?: string;
+}
+
+/**
+ * `bun widget migrate config`, rewrite widgets' raw-zod config to `defineConfig` +
+ * `field.*`. Assistive: unmigratable fields stay raw zod and are reported as manual
+ * TODOs; validation is never dropped. Use `--dry` to preview without writing.
+ */
+export async function runMigrate(
+  cwd: string,
+  target: string,
+  opts: MigrateOptions,
+): Promise<boolean> {
+  if (target !== "config") {
+    log.error(`Unknown migrate target "${target}". Supported: config`);
+    return false;
+  }
+
+  const all = discoverWidgets(cwd);
+  const widgets = opts.name ? all.filter((w) => w === opts.name) : all;
+  if (widgets.length === 0) {
+    log.error(
+      opts.name
+        ? `Widget "${opts.name}" not found. Available: ${all.join(", ")}`
+        : "No widgets found in src/.",
+    );
+    return false;
+  }
+
+  let migrated = 0;
+  let totalTodos = 0;
+  const skipped: string[] = [];
+
+  for (const widget of widgets) {
+    let widgetChanged = false;
+    for (const file of widgetSourceFiles(cwd, widget)) {
+      const original = readFileSync(file, "utf8");
+      const { code, changed, warnings } = migrateConfigSource(original, file);
+      if (!changed) continue;
+
+      widgetChanged = true;
+      migrated++;
+      if (!opts.dry) writeFileSync(file, code);
+
+      const rel = relative(cwd, file);
+      const verb = opts.dry ? "would migrate" : "migrated";
+      if (warnings.length === 0) {
+        log.success(`${widget}: ${verb} ${rel} (fully)`);
+      } else {
+        totalTodos += warnings.length;
+        log.warn(
+          `${widget}: ${verb} ${rel}, ${warnings.length} field(s) left as raw zod (manual TODO):`,
+        );
+        for (const w of warnings) {
+          log.message(`  • ${w.field}: ${w.reason}`);
+        }
+      }
+    }
+    if (!widgetChanged) skipped.push(`${widget} (already migrated or no z.object config)`);
+  }
+
+  if (skipped.length > 0) log.info(`Skipped: ${skipped.join(", ")}`);
+  const prefix = opts.dry ? "Dry run: " : "";
+  log.info(`${prefix}${migrated} widget(s) migrated, ${totalTodos} field(s) need manual review.`);
+  if (!opts.dry && migrated > 0) {
+    log.info("Review the diffs, then rebuild (`bun widget build`) to verify the zod region drops.");
+  }
+  return true;
+}

package/src/commands/publish.ts

@@ -113,7 +113,7 @@ export async function runPublish(
       let sizeInfo = "";
       try {
         const info = getWidgetBundleInfo(cwd, name);
-        sizeInfo = ` — ${formatBytes(info.raw)}`;
+        sizeInfo = `, ${formatBytes(info.raw)}`;
       } catch {}
       return {
         value: name,
@@ -226,7 +226,7 @@ export async function runPublish(
     });
   } catch (err: any) {
     if (err.status === 409) {
-      s.stop(`${manifest.name}@${version} already published — bump version to republish`);
+      s.stop(`${manifest.name}@${version} already published, bump version to republish`);
       process.exit(0);
     }
     s.stop(`Publish failed: ${err.message}`);
@@ -244,7 +244,7 @@ export async function runPublish(
   if (cssBuffer) {
     if (!publishData.cssUploadUrl) {
       s.stop(
-        `dist/${widgetName}.css exists but the Hub did not return a css upload URL — update the Hub or remove the stylesheet`,
+        `dist/${widgetName}.css exists but the Hub did not return a css upload URL, update the Hub or remove the stylesheet`,
       );
       process.exit(1);
     }

package/src/commands/upgrade.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { log, spinner } from "@clack/prompts";
+import { log, note, spinner } from "@clack/prompts";
 import { discoverWidgets, readManifest, writeManifest } from "../utils/manifest";
 import { runValidate } from "./validate";
 
@@ -124,11 +124,14 @@ export async function runUpgrade(cwd: string): Promise<void> {
   } else {
     // Standalone mode: can't fetch from npm (private package), guide user
     log.info("@glasshome/widget-sdk is a workspace package and is not published to npm.");
-    log.info("");
-    log.step("To upgrade:");
-    log.info("  1. Update the @glasshome/widget-sdk version in your package.json peerDependencies");
-    log.info("  2. Run `bun install` to install the new version");
-    log.info("  3. Run `bun widget upgrade` again to sync manifest files");
-    log.info("  4. Run `bun widget validate` to check compatibility");
+    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

@@ -40,18 +40,18 @@ function validateManifest(manifest: WidgetManifest): ValidationResult {
     const capabilities = (manifest as { capabilities?: unknown }).capabilities;
     if (manifest.sdkVersion && requiresCapabilities(manifest.sdkVersion) && capabilities === undefined) {
       errors.push(
-        `sdkVersion "${manifest.sdkVersion}" only admits SDK >= 1.0.0, so manifest.json must declare "capabilities" — use [] if the widget never reads or controls Home Assistant`,
+        `sdkVersion "${manifest.sdkVersion}" only admits SDK >= 1.0.0, so manifest.json must declare "capabilities", use [] if the widget never reads or controls Home Assistant`,
       );
     }
   }
 
-  // INS-05: "*" sdkVersion is rejected at publish time — authors must declare
+  // 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
   // are blocked here.
   if (manifest.sdkVersion === "*") {
     errors.push(
-      `sdkVersion "*" is not allowed — declare a semver range (e.g. "^0.3.0") to opt into host compatibility checks`,
+      `sdkVersion "*" is not allowed, declare a semver range (e.g. "^0.3.0") to opt into host compatibility checks`,
     );
   }
 
@@ -156,7 +156,7 @@ export async function runValidate(
   const failed: string[] = [];
 
   for (const name of toValidate) {
-    if (!quiet) log.info(`\nValidating widget: ${name}`);
+    if (!quiet) log.step(name);
 
     // Read and validate manifest.json
     let manifest: WidgetManifest;
@@ -211,7 +211,7 @@ export async function runValidate(
   // Validate registry.json
   const registry = readRegistry(cwd);
   if (!registry) {
-    if (!quiet) log.error("\ndist/registry.json not found");
+    if (!quiet) log.error("dist/registry.json not found");
     allPassed = false;
   } else {
     const registryTags = new Set(registry.widgets.map((w) => w.bundleUrl));
@@ -221,21 +221,17 @@ export async function runValidate(
         allPassed = false;
       }
     }
-    if (!quiet) log.info(`\nRegistry: ${registry.widgets.length} widget(s)`);
+    if (!quiet) log.info(`Registry: ${registry.widgets.length} widget(s)`);
   }
 
+  // Quiet callers (publish) get a one-line summary; interactive runs let the
+  // caller's outro own the final banner so it isn't printed twice.
   if (quiet) {
     if (allPassed) {
       log.success(`Validated ${toValidate.length} widget(s)`);
     } else {
       log.error(`Validation failed for: ${failed.join(", ")}`);
     }
-  } else {
-    if (allPassed) {
-      log.success("\nAll checks passed");
-    } else {
-      log.error("\nValidation failed");
-    }
   }
 
   return allPassed;

package/src/migrate/config-codemod.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import { migrateConfigSource } from "./config-codemod";
+
+function migrate(body: string) {
+  const code = `import { defineWidget, widgetFields, z } from "@glasshome/widget-sdk";\n\n${body}\n`;
+  return migrateConfigSource(code, "widget.tsx");
+}
+
+describe("migrateConfigSource, field kinds", () => {
+  test("widgetFields.* map to field.*", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  title: widgetFields.title(),\n  area: widgetFields.areaId(),\n  lights: widgetFields.entityIds("light"),\n  th: widgetFields.singleEntity("sensor", { deviceClass: "temperature" }),\n});`,
+    );
+    expect(r.changed).toBe(true);
+    expect(r.warnings).toEqual([]);
+    expect(r.code).toContain("defineConfig({");
+    expect(r.code).toContain("title: field.title(),");
+    expect(r.code).toContain("area: field.area(),");
+    expect(r.code).toContain('lights: field.entities("light"),');
+    expect(r.code).toContain('th: field.entity("sensor", { deviceClass: "temperature" }),');
+  });
+
+  test("raw scalars → field.text/number/toggle/choice", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  name: z.string().optional().meta({ title: "Name" }),\n  size: z.number().min(1).max(10).default(5).meta({ title: "Size" }),\n  on: z.boolean().default(false).meta({ title: "On" }),\n  style: z.enum(["a", "b"]).default("a").meta({ title: "Style" }),\n});`,
+    );
+    expect(r.warnings).toEqual([]);
+    expect(r.code).toContain('name: field.text({ title: "Name" }),');
+    expect(r.code).toContain('size: field.number({ title: "Size", min: 1, max: 10, default: 5 }),');
+    expect(r.code).toContain('on: field.toggle({ title: "On", default: false }),');
+    expect(r.code).toContain('style: field.choice(["a", "b"], { title: "Style", default: "a" }),');
+  });
+
+  test("entity arrays with domain/deviceClass/singleSelect + stringList", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  ids: z.array(z.string()).default([]).meta({ domain: "light", title: "Lights" }),\n  one: z.array(z.string()).default([]).meta({ domain: "sensor", singleSelect: true, deviceClass: "power" }),\n  tags: z.array(z.string()).default([]).meta({ title: "Tags" }),\n});`,
+    );
+    expect(r.warnings).toEqual([]);
+    expect(r.code).toContain('ids: field.entities("light", { title: "Lights" }),');
+    expect(r.code).toContain('one: field.entity("sensor", { deviceClass: "power" }),');
+    expect(r.code).toContain('tags: field.stringList({ title: "Tags" }),');
+  });
+
+  test("nested z.object → field.group (clock analogOptions)", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  analogOptions: z.object({\n    border: z.boolean().default(false).meta({ title: "Show Border" }),\n    ticks: z.enum(["none", "hour"]).default("hour").meta({ title: "Tick Marks" }),\n  }).default({ border: false, ticks: "hour" }).meta({ title: "Analog Options" }),\n});`,
+    );
+    expect(r.warnings).toEqual([]);
+    expect(r.code).toContain("analogOptions: field.group({");
+    expect(r.code).toContain('border: field.toggle({ title: "Show Border", default: false }),');
+    expect(r.code).toContain('ticks: field.choice(["none", "hour"], { title: "Tick Marks", default: "hour" }),');
+    expect(r.code).toContain('}, { title: "Analog Options" }),');
+  });
+
+  test("z.infer → Infer", () => {
+    const r = migrate(
+      `export const configSchema = z.object({ title: widgetFields.title() });\nexport type Config = z.infer<typeof configSchema>;`,
+    );
+    expect(r.code).toContain("export type Config = Infer<typeof configSchema>;");
+  });
+});
+
+describe("migrateConfigSource, imports", () => {
+  test("adds defineConfig/field/Infer, drops widgetFields/z when unused", () => {
+    const r = migrate(
+      `export const configSchema = z.object({ title: widgetFields.title() });\nexport type Config = z.infer<typeof configSchema>;`,
+    );
+    const importLine = r.code.split("\n")[0];
+    expect(importLine).toContain("defineConfig");
+    expect(importLine).toContain("field");
+    expect(importLine).toContain("Infer");
+    // `Infer` is a type, must be type-only for verbatimModuleSyntax widgets.
+    expect(importLine).toContain("type Infer");
+    expect(importLine).not.toContain("widgetFields");
+    expect(importLine).not.toContain(" z,");
+    expect(importLine).not.toContain(" z ");
+    expect(importLine).toContain("defineWidget");
+  });
+
+  test("keeps z when a raw field survives (escape hatch)", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  title: widgetFields.title(),\n  custom: z.string().url().meta({ title: "URL" }),\n});`,
+    );
+    expect(r.code.split("\n")[0]).toContain("z");
+    expect(r.warnings.map((w) => w.field)).toContain("custom");
+  });
+
+  test("reflows a multiline SDK import to one name per line (no inline append)", () => {
+    const code = `import {\n  defineWidget,\n  Widget,\n  widgetFields,\n  z,\n} from "@glasshome/widget-sdk";\n\nexport const configSchema = z.object({ title: widgetFields.title() });\nexport type Config = z.infer<typeof configSchema>;`;
+    const r = migrateConfigSource(code, "widget.tsx");
+    // No line should carry more than one named import (the inline-append smell).
+    expect(r.code).not.toMatch(/\bfield, defineConfig\b/);
+    expect(r.code).toContain("\n  field,\n");
+    expect(r.code).toContain("\n  defineConfig,\n");
+    expect(r.code).toContain("\n  type Infer,\n");
+    expect(r.code).toContain('} from "@glasshome/widget-sdk";');
+  });
+
+  test("rewrites a bare zod import to the SDK import", () => {
+    const code = `import { defineWidget } from "@glasshome/widget-sdk";\nimport { z } from "zod";\n\nexport const configSchema = z.object({\n  custom: z.string().refine((v) => !!v).meta({ title: "X" }),\n});`;
+    const r = migrateConfigSource(code, "widget.tsx");
+    expect(r.code).not.toContain('from "zod"');
+    expect(r.code).toContain('from "@glasshome/widget-sdk"');
+    expect(r.code.split("\n").find((l) => l.includes("widget-sdk"))).toContain("z");
+  });
+});
+
+describe("migrateConfigSource, report and skip (never drop validation)", () => {
+  test("factory-built + identifier fields are left raw and reported", () => {
+    const r = migrate(
+      `const powerEntity = (l: string) => z.array(z.string()).default([]).meta({ domain: "sensor", title: l });\nexport const configSchema = z.object({\n  title: widgetFields.title(),\n  solar: powerEntity("Solar"),\n  strategy: consumptionStrategy,\n});`,
+    );
+    expect(r.changed).toBe(true);
+    expect(r.code).toContain("title: field.title(),");
+    // unmigratable values preserved verbatim
+    expect(r.code).toContain('solar: powerEntity("Solar"),');
+    expect(r.code).toContain("strategy: consumptionStrategy,");
+    const fields = r.warnings.map((w) => w.field).sort();
+    expect(fields).toEqual(["solar", "strategy"]);
+  });
+
+  test("unsupported modifiers (.refine) are reported, value kept", () => {
+    const r = migrate(
+      `export const configSchema = z.object({\n  url: z.string().url().refine((v) => v.length > 0).meta({ title: "URL" }),\n});`,
+    );
+    expect(r.code).toContain("url: z.string().url().refine");
+    expect(r.warnings[0]?.field).toBe("url");
+    expect(r.warnings[0]?.reason).toContain("unsupported modifier");
+  });
+
+  test("no configSchema → unchanged", () => {
+    const r = migrateConfigSource(`export const x = 1;\n`, "widget.tsx");
+    expect(r.changed).toBe(false);
+    expect(r.code).toBe(`export const x = 1;\n`);
+  });
+});

package/src/migrate/config-codemod.ts

@@ -0,0 +1,342 @@
+import { Node, type ObjectLiteralExpression, Project, SyntaxKind } from "ts-morph";
+
+/**
+ * Codemod: rewrite a widget's raw-zod config to the SDK config API
+ * (`defineConfig` + `field.*`). Assistive, never destructive: any field pattern it
+ * does not recognize (custom refinements, unions, factory-built schemas, local
+ * identifiers) is left as raw zod inside `defineConfig` and reported as a manual TODO.
+ * `defineConfig` accepts raw `ZodType` values, so a partially-migrated schema still
+ * compiles and validates identically. Powered by `bun widget migrate config`.
+ */
+
+export interface MigrationWarning {
+  field: string;
+  reason: string;
+}
+
+export interface MigrationResult {
+  code: string;
+  changed: boolean;
+  warnings: MigrationWarning[];
+}
+
+const KNOWN_MODIFIERS = new Set(["optional", "default", "min", "max", "meta"]);
+
+const WIDGET_FIELDS_MAP: Record<string, string> = {
+  title: "field.title",
+  entityIds: "field.entities",
+  singleEntity: "field.entity",
+  areaId: "field.area",
+};
+
+interface ParsedChain {
+  baseObj: string; // "z" | "widgetFields"
+  baseMethod: string; // "object" | "enum" | ... | "title"
+  baseArgs: Node[];
+  optional: boolean;
+  defaultText?: string;
+  minText?: string;
+  maxText?: string;
+  meta?: ObjectLiteralExpression;
+  unknownMod?: string;
+}
+
+/** Walk a zod method chain from outside in; returns null for non-chain expressions. */
+function parseChain(expr: Node): ParsedChain | null {
+  const mods: { name: string; args: Node[] }[] = [];
+  let cur: Node = expr;
+  while (Node.isCallExpression(cur)) {
+    const callee = cur.getExpression();
+    if (!Node.isPropertyAccessExpression(callee)) return null; // e.g. powerEntity(...)
+    const recv = callee.getExpression();
+    const name = callee.getName();
+    if (Node.isIdentifier(recv) && (recv.getText() === "z" || recv.getText() === "widgetFields")) {
+      // Reached the base constructor.
+      const parsed: ParsedChain = {
+        baseObj: recv.getText(),
+        baseMethod: name,
+        baseArgs: cur.getArguments(),
+        optional: false,
+      };
+      for (const m of mods) {
+        if (!KNOWN_MODIFIERS.has(m.name)) parsed.unknownMod = m.name;
+        if (m.name === "optional") parsed.optional = true;
+        else if (m.name === "default") parsed.defaultText = m.args[0]?.getText();
+        else if (m.name === "min") parsed.minText = m.args[0]?.getText();
+        else if (m.name === "max") parsed.maxText = m.args[0]?.getText();
+        else if (m.name === "meta") {
+          const arg = m.args[0];
+          if (arg && Node.isObjectLiteralExpression(arg)) parsed.meta = arg;
+        }
+      }
+      return parsed;
+    }
+    mods.push({ name, args: cur.getArguments() });
+    cur = recv;
+  }
+  return null;
+}
+
+/** Read an object-literal's string/boolean/simple props into name → source text. */
+function readMeta(meta: ObjectLiteralExpression | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!meta) return out;
+  for (const prop of meta.getProperties()) {
+    if (Node.isPropertyAssignment(prop)) {
+      const init = prop.getInitializer();
+      if (init) out[prop.getName()] = init.getText();
+    }
+  }
+  return out;
+}
+
+/** Emit `{ key: value, ... }` for the present entries, preserving source text. */
+function optionsObject(entries: [string, string | undefined][]): string {
+  const parts = entries.filter(([, v]) => v !== undefined).map(([k, v]) => `${k}: ${v}`);
+  return `{ ${parts.join(", ")} }`;
+}
+
+/**
+ * Transform one field expression to its `field.*` form, or return a skip reason.
+ * `indent` is the leading whitespace for a nested `group` shape.
+ */
+function transformField(expr: Node, indent: string): { text: string } | { skip: string } {
+  const c = parseChain(expr);
+  if (!c) return { skip: "not a zod chain (factory/identifier/custom expression)" };
+  if (c.unknownMod) return { skip: `unsupported modifier .${c.unknownMod}()` };
+
+  // widgetFields.* → field.*
+  if (c.baseObj === "widgetFields") {
+    const mapped = WIDGET_FIELDS_MAP[c.baseMethod];
+    if (!mapped) return { skip: `unknown widgetFields.${c.baseMethod}` };
+    const args = c.baseArgs.map((a) => a.getText()).join(", ");
+    return { text: `${mapped}(${args})` };
+  }
+
+  const m = readMeta(c.meta);
+  const title = m.title;
+  const description = m.description;
+
+  switch (c.baseMethod) {
+    case "string": {
+      if (m.formType === '"area-picker"' || m.formType === "'area-picker'") {
+        return {
+          text: `field.area(${title && title !== '"Area"' ? optionsObject([["title", title]]) : ""})`,
+        };
+      }
+      if (!title) return { skip: "z.string() without a title cannot map to field.text" };
+      return {
+        text: `field.text(${optionsObject([
+          ["title", title],
+          ["description", description],
+          ["default", c.defaultText],
+        ])})`,
+      };
+    }
+    case "number": {
+      if (!title) return { skip: "z.number() without a title" };
+      return {
+        text: `field.number(${optionsObject([
+          ["title", title],
+          ["description", description],
+          ["min", c.minText],
+          ["max", c.maxText],
+          ["default", c.defaultText],
+        ])})`,
+      };
+    }
+    case "boolean": {
+      if (!title) return { skip: "z.boolean() without a title" };
+      return {
+        text: `field.toggle(${optionsObject([
+          ["title", title],
+          ["description", description],
+          ["default", c.defaultText],
+        ])})`,
+      };
+    }
+    case "enum": {
+      if (!title) return { skip: "z.enum() without a title" };
+      const values = c.baseArgs[0]?.getText() ?? "[]";
+      return {
+        text: `field.choice(${values}, ${optionsObject([
+          ["title", title],
+          ["description", description],
+          ["default", c.defaultText],
+        ])})`,
+      };
+    }
+    case "array": {
+      const inner = c.baseArgs[0];
+      if (
+        !inner ||
+        !Node.isCallExpression(inner) ||
+        inner.getExpression().getText() !== "z.string"
+      ) {
+        return { skip: "z.array of a non-string element" };
+      }
+      if (m.domain) {
+        const domain = m.domain;
+        const opts = optionsObject([
+          ["title", title],
+          ["description", description],
+          ["deviceClass", m.deviceClass],
+        ]);
+        const optsArg = opts === "{  }" ? "" : `, ${opts}`;
+        const fn = m.singleSelect === "true" ? "field.entity" : "field.entities";
+        return { text: `${fn}(${domain}${optsArg})` };
+      }
+      if (!title) return { skip: "z.array(z.string()) without a domain or title" };
+      return {
+        text: `field.stringList(${optionsObject([
+          ["title", title],
+          ["description", description],
+        ])})`,
+      };
+    }
+    case "object": {
+      if (!title) return { skip: "nested z.object() without a title" };
+      const innerArg = c.baseArgs[0];
+      if (!innerArg || !Node.isObjectLiteralExpression(innerArg))
+        return { skip: "z.object() with a non-literal shape" };
+      const shape = buildShape(innerArg, `${indent}  `);
+      return { text: `field.group(${shape.text}, ${optionsObject([["title", title]])})` };
+    }
+    default:
+      return { skip: `unsupported base z.${c.baseMethod}()` };
+  }
+}
+
+/** Build a `{ key: <field>, ... }` shape literal from an object of zod fields. */
+function buildShape(
+  obj: ObjectLiteralExpression,
+  indent: string,
+): { text: string; warnings: MigrationWarning[] } {
+  const warnings: MigrationWarning[] = [];
+  const lines: string[] = [];
+  for (const prop of obj.getProperties()) {
+    if (!Node.isPropertyAssignment(prop)) {
+      // Spread, shorthand, method, leave the whole thing untouched conservatively.
+      lines.push(`${indent}  ${prop.getText()}`);
+      warnings.push({
+        field: prop.getText().slice(0, 40),
+        reason: "non-standard property (spread/shorthand)",
+      });
+      continue;
+    }
+    const name = prop.getName();
+    const init = prop.getInitializer();
+    if (!init) continue;
+    const result = transformField(init, `${indent}  `);
+    if ("text" in result) {
+      lines.push(`${indent}  ${name}: ${result.text},`);
+    } else {
+      lines.push(`${indent}  ${name}: ${init.getText()},`);
+      warnings.push({ field: name, reason: result.skip });
+    }
+  }
+  return { text: `{\n${lines.join("\n")}\n${indent}}`, warnings };
+}
+
+function rewriteNamedImport(
+  project: Project,
+  filePath: string,
+  moduleName: string,
+  add: { name: string; isTypeOnly?: boolean }[],
+  remove: string[],
+): void {
+  const sf = project.getSourceFileOrThrow(filePath);
+  const decl = sf.getImportDeclaration((d) => d.getModuleSpecifierValue() === moduleName);
+  if (!decl) return;
+  for (const named of decl.getNamedImports()) {
+    if (remove.includes(named.getName())) named.remove();
+  }
+  const existing = new Set(decl.getNamedImports().map((n) => n.getName()));
+  const toAdd = add.filter((n) => !existing.has(n.name));
+  // `Infer` is a type: import it type-only so `verbatimModuleSyntax` widgets compile.
+  if (toAdd.length > 0) decl.addNamedImports(toAdd);
+  // Drop an import that has no remaining named/default/namespace bindings.
+  if (
+    decl.getNamedImports().length === 0 &&
+    !decl.getDefaultImport() &&
+    !decl.getNamespaceImport()
+  ) {
+    decl.remove();
+    return;
+  }
+  // ts-morph appends new names inline onto the last line of a multiline import. Put
+  // each name back on its own line (order preserved, so no churn to existing imports);
+  // leave single-line imports as-is.
+  if (decl.getText().includes("\n")) {
+    const names = decl
+      .getNamedImports()
+      .map((n) => `  ${n.isTypeOnly() ? "type " : ""}${n.getName()},`)
+      .join("\n");
+    decl.replaceWithText(`import {\n${names}\n} from "${decl.getModuleSpecifierValue()}";`);
+  }
+}
+
+export function migrateConfigSource(code: string, filePath = "widget.tsx"): MigrationResult {
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(filePath, code);
+
+  const decl = sf.getVariableDeclaration("configSchema");
+  const initializer = decl?.getInitializer();
+  const warnings: MigrationWarning[] = [];
+  let changed = false;
+
+  if (
+    initializer &&
+    Node.isCallExpression(initializer) &&
+    initializer.getExpression().getText() === "z.object"
+  ) {
+    const shapeArg = initializer.getArguments()[0];
+    if (shapeArg && Node.isObjectLiteralExpression(shapeArg)) {
+      const built = buildShape(shapeArg, "");
+      warnings.push(...built.warnings);
+      initializer.replaceWithText(`defineConfig(${built.text})`);
+      changed = true;
+    }
+  }
+
+  // z.infer<...> → Infer<...>
+  for (const ref of sf.getDescendantsOfKind(SyntaxKind.TypeReference)) {
+    if (ref.getText().startsWith("z.infer")) {
+      ref.getTypeName().replaceWithText("Infer");
+      changed = true;
+    }
+  }
+
+  if (!changed) return { code, changed: false, warnings };
+
+  // Recompute which SDK symbols the migrated body needs (ignore import statements).
+  const body = sf
+    .getStatements()
+    .filter((s) => !Node.isImportDeclaration(s))
+    .map((s) => s.getText())
+    .join("\n");
+  const needField = /\bfield\./.test(body);
+  const needDefineConfig = /\bdefineConfig\(/.test(body);
+  const needInfer = /\bInfer\s*</.test(body);
+  const needZ = /\bz\./.test(body);
+  const usesWidgetFields = /\bwidgetFields\./.test(body);
+
+  const add: { name: string; isTypeOnly?: boolean }[] = [];
+  if (needField) add.push({ name: "field" });
+  if (needDefineConfig) add.push({ name: "defineConfig" });
+  if (needInfer) add.push({ name: "Infer", isTypeOnly: true });
+  const remove: string[] = [];
+  if (!usesWidgetFields) remove.push("widgetFields");
+  if (!needZ) remove.push("z");
+
+  // Move any surviving `z` need onto the SDK import; drop the bare "zod" import.
+  const zodDecl = sf.getImportDeclaration((d) => d.getModuleSpecifierValue() === "zod");
+  if (zodDecl) {
+    zodDecl.remove();
+    if (needZ) add.push({ name: "z" });
+  }
+
+  rewriteNamedImport(project, filePath, "@glasshome/widget-sdk", add, remove);
+
+  return { code: sf.getFullText(), changed, warnings };
+}

package/src/utils/lint-source.ts

@@ -0,0 +1,84 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { log } from "@clack/prompts";
+import { deprecations, formatDeprecation } from "@glasshome/widget-sdk/deprecations";
+import { discoverWidgets } from "./manifest";
+
+/**
+ * Source-level deprecation lint. Scans widget `.ts`/`.tsx` for deprecated API usage
+ * (driven by the SDK deprecation registry) and direct `zod` imports, printing the
+ * removal timeline. Warnings only: never blocks a build until the deprecated path is
+ * actually removed (v2). Runs on `bun widget build` and `connect`.
+ */
+
+export interface SourceLintFinding {
+  widget: string;
+  file: string;
+  line: number;
+  message: string;
+}
+
+const SOURCE_EXTS = [".ts", ".tsx"];
+const ZOD_IMPORT = /\bfrom\s+["']zod["']/;
+const ZOD_IMPORT_MESSAGE =
+  'importing from "zod" directly couples your widget to the SDK\'s zod version. Prefer field.*/defineConfig; for advanced schemas import { z } from "@glasshome/widget-sdk".';
+
+function widgetSourceFiles(cwd: string, widget: string): string[] {
+  const dir = resolve(cwd, "src", widget);
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const entry of readdirSync(d)) {
+      const p = join(d, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (SOURCE_EXTS.some((e) => entry.endsWith(e))) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+const registryMatchers = deprecations
+  .filter((d) => d.sourcePattern)
+  .map((d) => ({ entry: d, re: new RegExp(d.sourcePattern as string) }));
+
+/** Scan one widget's source and return deprecation findings. */
+export function lintWidgetSource(cwd: string, widget: string): SourceLintFinding[] {
+  const findings: SourceLintFinding[] = [];
+  for (const file of widgetSourceFiles(cwd, widget)) {
+    const rel = relative(cwd, file);
+    const lines = readFileSync(file, "utf8").split("\n");
+    lines.forEach((text, i) => {
+      const line = i + 1;
+      for (const { entry, re } of registryMatchers) {
+        if (re.test(text)) {
+          findings.push({ widget, file: rel, line, message: formatDeprecation(entry) });
+        }
+      }
+      if (ZOD_IMPORT.test(text)) {
+        findings.push({
+          widget,
+          file: rel,
+          line,
+          message: `[@glasshome/widget-sdk] ${ZOD_IMPORT_MESSAGE}`,
+        });
+      }
+    });
+  }
+  return findings;
+}
+
+/**
+ * Lint the given widgets (or all discovered widgets) and print findings as warnings.
+ * Returns the findings so callers can act on them; never throws or blocks the build.
+ */
+export function lintAndReport(cwd: string, widgets?: string[]): SourceLintFinding[] {
+  const targets = widgets ?? discoverWidgets(cwd);
+  const findings = targets.flatMap((w) => lintWidgetSource(cwd, w));
+  if (findings.length === 0) return findings;
+
+  log.warn(`${findings.length} deprecated config usage(s) found (non-blocking until SDK 2.0):`);
+  for (const f of findings) {
+    log.message(`  ${f.file}:${f.line}  ${f.message}`);
+  }
+  return findings;
+}

package/src/utils/quiet.ts

@@ -0,0 +1,20 @@
+/**
+ * Run `fn` with stdout writes swallowed. `buildWidgets()` (SDK) console.logs a
+ * "[registry] Generated..." line mid-build; when the caller drives a clack
+ * spinner that raw write lands on the spinner's line and garbles it. Stderr is
+ * left alone so real warnings/errors still surface.
+ */
+export async function withQuietStdout<T>(fn: () => Promise<T>): Promise<T> {
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  const originalLog = console.log;
+  // Bun's console.log writes to fd 1 natively and bypasses a process.stdout.write
+  // override, so both paths are silenced.
+  process.stdout.write = (() => true) as typeof process.stdout.write;
+  console.log = () => {};
+  try {
+    return await fn();
+  } finally {
+    process.stdout.write = originalWrite;
+    console.log = originalLog;
+  }
+}