openuispec 0.2.14 → 0.2.15

package/cli/init.ts

@@ -471,6 +471,7 @@ If MCP tools are not available, use these CLI commands with \`--json\` flag:
 
 **Visual verification:**
 - \`openuispec screenshot --route /path\` — screenshot the web app
+- \`openuispec screenshot --route /path --init-script "..."\` — inject auth/role before rendering (web only; app must implement \`__ous_init\` bootstrapper)
 - \`openuispec screenshot-android [--project-dir path]\` — screenshot Android app
 - \`openuispec screenshot-ios [--project-dir path]\` — screenshot iOS app
 

package/docs/cli.md

@@ -175,6 +175,59 @@ Each capture supports:
 - `wait_for`: per-capture wait time in ms
 - `selector`: CSS selector to screenshot a specific element (web only)
 - `full_page`: capture full scrollable page (web only)
+- `init_script`: JavaScript to execute before the page renders (web only — see below)
+
+### `init_script` — app-level initialization
+
+`init_script` lets you inject auth, switch roles, or set up session state before a screenshot is taken — without Puppeteer executing JS directly. The tool base64-encodes the script and appends it as a `?__ous_init=<encoded>` query param. The generated app's bootstrapper reads and runs it before rendering.
+
+**Why app-level instead of `evaluateOnNewDocument`:** the app can `await` login APIs, set framework state, or call any async init — Puppeteer's `evaluateOnNewDocument` is sync-only and has no access to app internals.
+
+**Single capture (MCP):**
+
+```json
+{
+  "route": "/dashboard",
+  "init_script": "window.__auth = { token: 'test-token', role: 'admin' };"
+}
+```
+
+**Batch capture (MCP):**
+
+```json
+{
+  "output_dir": "screenshots",
+  "init_script": "window.__auth = { token: 'test-token', role: 'viewer' };",
+  "captures": [
+    { "screen": "dashboard", "route": "/dashboard" },
+    { "screen": "admin_panel", "route": "/admin",
+      "init_script": "window.__auth = { token: 'test-token', role: 'admin' };" }
+  ]
+}
+```
+
+Per-capture `init_script` overrides the shared one. If neither is set, no param is appended and the app renders normally.
+
+**Bootstrapper contract** — the generated app must include a bootstrapper that:
+
+1. Checks for `__ous_init` in the URL query string on load
+2. Base64-decodes it (`atob`) and `eval`s it (or parses it as structured data)
+3. Runs **before** rendering authenticated content (can be async — app awaits it)
+4. Strips the param from URL/history after processing (`history.replaceState`)
+
+Example bootstrapper (framework-agnostic):
+
+```js
+const param = new URLSearchParams(location.search).get('__ous_init');
+if (param) {
+  try { eval(atob(param)); } catch (e) { console.warn('[ous] init_script error', e); }
+  const url = new URL(location.href);
+  url.searchParams.delete('__ous_init');
+  history.replaceState(null, '', url.toString());
+}
+```
+
+This is a **contract between the tool and generated code** — the tool appends the param; the app consumes it.
 
 ### Preview (experimental)
 

package/mcp-server/index.ts

@@ -813,9 +813,10 @@ server.registerTool(
       full_page: z.boolean().optional().default(false).describe("Capture the full scrollable page instead of just the viewport"),
       selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the full page"),
       output_dir: z.string().optional().describe("Directory to save the screenshot PNG (relative to web app root). E.g. 'screenshots'. If omitted, only returns base64 in response."),
+      init_script: z.string().optional().describe("JavaScript to run before the page renders. Passed to the app via ?__ous_init=<base64> query param. The app's bootstrapper decodes and executes it — use for auth injection, role switching, or session setup."),
     },
   },
-  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir }) => {
+  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir, init_script }) => {
     try {
       return await takeScreenshot(projectCwd, {
         route,
@@ -826,6 +827,7 @@ server.registerTool(
         full_page,
         selector,
         output_dir,
+        init_script,
       });
     } catch (err) {
       return toolError(err);
@@ -894,6 +896,7 @@ const webBatchCaptureSchema = z.object({
   selector: z.string().optional().describe("CSS selector to screenshot a specific element"),
   full_page: z.boolean().optional().describe("Capture full scrollable page"),
   wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+  init_script: z.string().optional().describe("Per-capture init script (overrides shared init_script for this capture)"),
 });
 
 server.registerTool(
@@ -906,11 +909,12 @@ server.registerTool(
       scale: z.number().optional().default(2).describe("Device pixel ratio for all captures (default 2)"),
       theme: z.enum(["light", "dark"]).optional().describe("Force color scheme for all captures"),
       output_dir: z.string().optional().describe("Directory to save all PNGs (relative to web app root)"),
+      init_script: z.string().optional().describe("Shared init script for all captures. Passed via ?__ous_init=<base64>. Per-capture init_script overrides this."),
     },
   },
-  async ({ captures, viewport, scale, theme, output_dir }) => {
+  async ({ captures, viewport, scale, theme, output_dir, init_script }) => {
     try {
-      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir });
+      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir, init_script });
     } catch (err) {
       return toolError(err);
     }

package/mcp-server/screenshot-shared.ts

@@ -48,10 +48,9 @@ export async function closeBrowser(): Promise<void> {
 
 // ── shared result type ──────────────────────────────────────────────
 
-export interface ScreenshotResult {
-  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
-  isError?: true;
-}
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+export type ScreenshotResult = CallToolResult;
 
 // ── manifest loading ────────────────────────────────────────────────
 

package/mcp-server/screenshot.ts

@@ -8,7 +8,7 @@
 import { spawn, type ChildProcess, execSync } from "node:child_process";
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { createServer, type AddressInfo } from "node:net";
+import { createConnection } from "node:net";
 import YAML from "yaml";
 import { findProjectDir } from "../drift/index.js";
 import { getBrowser, closeBrowser, type ScreenshotResult } from "./screenshot-shared.js";
@@ -24,18 +24,186 @@ export interface ScreenshotOptions {
   full_page?: boolean;
   selector?: string;
   output_dir?: string;
+  init_script?: string;
 }
 
-// ── free port finder ────────────────────────────────────────────────
+// ── framework config table ───────────────────────────────────────────
+
+interface FrameworkConfig {
+  /** Typed discriminant for branching logic */
+  kind: "node" | "bun" | "deno" | "python-django" | "python-flask" | "ruby" | "php" | "go" | "rust" | "java";
+  /** Human-readable name */
+  name: string;
+  /** Files whose presence identifies this framework (checked in webDir) */
+  indicators: string[];
+  /** Default dev port when none is configured */
+  defaultPort: number;
+  /** Command + args to start the dev server; PORT placeholder replaced at runtime */
+  devCommand: string[];
+  /** Install command to run when dependencies are missing (null = skip) */
+  installCommand: string[] | null;
+  /** Package manager env var used to set the port (e.g. PORT, APP_PORT) */
+  portEnvVar: string;
+}
 
-function findFreePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const srv = createServer();
-    srv.listen(0, () => {
-      const port = (srv.address() as AddressInfo).port;
-      srv.close(() => resolve(port));
-    });
-    srv.on("error", reject);
+// Ordered by detection priority (most specific first)
+const FRAMEWORKS: FrameworkConfig[] = [
+  {
+    kind: "bun",
+    name: "Bun",
+    indicators: ["bun.lockb", "bun.lock"],
+    defaultPort: 3000,
+    devCommand: ["bun", "run", "dev"],
+    installCommand: ["bun", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "deno",
+    name: "Deno",
+    indicators: ["deno.json", "deno.jsonc"],
+    defaultPort: 8000,
+    devCommand: ["deno", "task", "dev"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "node",
+    name: "Node.js (npm/yarn/pnpm)",
+    indicators: ["package.json"],
+    defaultPort: 3000,
+    devCommand: ["npm", "run", "dev"],
+    installCommand: ["npm", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "python-django",
+    name: "Django",
+    indicators: ["manage.py"],
+    defaultPort: 8000,
+    devCommand: ["python", "manage.py", "runserver", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "python-flask",
+    name: "Flask / FastAPI",
+    indicators: ["requirements.txt", "Pipfile", "pyproject.toml"],
+    defaultPort: 5000,
+    devCommand: ["python", "-m", "flask", "run", "--port", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "ruby",
+    name: "Ruby on Rails",
+    indicators: ["Gemfile", "config/application.rb"],
+    defaultPort: 3000,
+    devCommand: ["bin/rails", "server", "-p", "PORT"],
+    installCommand: ["bundle", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "php",
+    name: "PHP (Laravel)",
+    indicators: ["artisan"],
+    defaultPort: 8000,
+    devCommand: ["php", "artisan", "serve", "--port=PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "go",
+    name: "Go",
+    indicators: ["go.mod"],
+    defaultPort: 8080,
+    devCommand: ["go", "run", "."],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "rust",
+    name: "Rust (Trunk)",
+    indicators: ["Trunk.toml", "Cargo.toml"],
+    defaultPort: 8080,
+    devCommand: ["trunk", "serve", "--port", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "java",
+    name: "Java / Spring Boot",
+    indicators: ["pom.xml", "build.gradle", "build.gradle.kts"],
+    defaultPort: 8080,
+    devCommand: ["./mvnw", "spring-boot:run"],
+    installCommand: null,
+    portEnvVar: "SERVER_PORT",
+  },
+];
+
+// ── framework detection ──────────────────────────────────────────────
+
+function detectFramework(webDir: string): FrameworkConfig {
+  for (const fw of FRAMEWORKS) {
+    if (fw.indicators.some((f) => existsSync(join(webDir, f)))) return fw;
+  }
+  // Fallback: generic Node
+  return FRAMEWORKS.find((f) => f.kind === "node")!;
+}
+
+// ── port resolution ──────────────────────────────────────────────────
+
+/** Parse --port / -p / --port=N from a script string. */
+function parsePortFromScript(script: string): number | null {
+  const m = script.match(/(?:--port|-p)[=\s]+(\d+)/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/** Read PORT (or custom var) from .env.local / .env.development / .env. */
+function readEnvPort(webDir: string, varName = "PORT"): number | null {
+  for (const name of [".env.local", ".env.development", ".env"]) {
+    const envPath = join(webDir, name);
+    if (!existsSync(envPath)) continue;
+    try {
+      const re = new RegExp(`^\\s*${varName}\\s*=\\s*(\\d+)`, "m");
+      const m = readFileSync(envPath, "utf-8").match(re);
+      if (m) return parseInt(m[1], 10);
+    } catch { /* skip */ }
+  }
+  return null;
+}
+
+/** Resolve the port this project's dev server will use. */
+function resolvePort(webDir: string, fw: FrameworkConfig): number {
+  // 1. .env files
+  const envPort = readEnvPort(webDir, fw.portEnvVar);
+  if (envPort) return envPort;
+
+  // 2. package.json dev/start script (Node-like only)
+  if (existsSync(join(webDir, "package.json"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(webDir, "package.json"), "utf-8"));
+      const scripts: Record<string, string> = pkg.scripts ?? {};
+      for (const name of ["dev", "start", "serve", "develop"]) {
+        if (scripts[name]) {
+          const p = parsePortFromScript(scripts[name]);
+          if (p) return p;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // 3. Framework default
+  return fw.defaultPort;
+}
+
+function isPortListening(port: number, host = "127.0.0.1"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host });
+    socket.setTimeout(500);
+    socket.on("connect", () => { socket.destroy(); resolve(true); });
+    socket.on("timeout", () => { socket.destroy(); resolve(false); });
+    socket.on("error", () => resolve(false));
   });
 }
 
@@ -47,18 +215,22 @@ export function findWebAppDir(projectCwd: string): string {
   const manifest = YAML.parse(readFileSync(manifestPath, "utf-8"));
   const projectName = manifest.project?.name ?? "app";
 
+  // Derive indicators from the FRAMEWORKS table so they stay in sync
+  const isWebDir = (d: string) =>
+    FRAMEWORKS.some((fw) => fw.indicators.some((f) => existsSync(join(d, f))));
+
   // Check custom output_dir first
   const customDir = manifest.generation?.output_dir?.web;
   if (customDir) {
     const resolved = resolve(projectDir, customDir);
-    if (existsSync(join(resolved, "package.json"))) return resolved;
+    if (isWebDir(resolved)) return resolved;
   }
 
   // Default: generated/web/<project-name>/
   // Try from the project root (parent of openuispec/)
   const projectRoot = resolve(projectDir, "..");
   const defaultDir = join(projectRoot, "generated", "web", projectName);
-  if (existsSync(join(defaultDir, "package.json"))) return defaultDir;
+  if (isWebDir(defaultDir)) return defaultDir;
 
   throw new Error(
     `Web app not found. Checked:\n` +
@@ -71,78 +243,114 @@ export function findWebAppDir(projectCwd: string): string {
 // ── dev server manager ──────────────────────────────────────────────
 
 interface ServerInstance {
-  process: ChildProcess;
+  process: ChildProcess | null; // null = using an externally running server
   port: number;
   url: string;
 }
 
 const servers = new Map<string, ServerInstance>();
 
-function ensureDepsInstalled(webDir: string): void {
-  if (existsSync(join(webDir, "node_modules"))) return;
+function ensureDepsInstalled(webDir: string, fw: FrameworkConfig): void {
+  if (!fw.installCommand) return;
+  // For Node.js check node_modules; for others always run
+  if (fw.kind === "node" && existsSync(join(webDir, "node_modules"))) return;
   try {
-    execSync("npm install", { cwd: webDir, stdio: "pipe", timeout: 90_000 });
+    execSync(fw.installCommand.join(" "), { cwd: webDir, stdio: "pipe", timeout: 120_000 });
   } catch (err) {
-    throw new Error(`Failed to install web app dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
+    throw new Error(`Failed to install dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
   }
 }
 
+const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+/** Poll until the port accepts connections, or the timeout expires. */
+async function waitForPort(port: number, timeoutMs = 60_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortListening(port)) return true;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
 async function startDevServer(webDir: string): Promise<ServerInstance> {
   const existing = servers.get(webDir);
   if (existing) {
-    // Verify still running
-    if (existing.process.exitCode === null) return existing;
+    const alive = existing.process === null
+      ? await isPortListening(existing.port)   // external server
+      : existing.process.exitCode === null;     // managed process
+    if (alive) return existing;
     servers.delete(webDir);
   }
 
-  ensureDepsInstalled(webDir);
-  const port = await findFreePort();
+  const fw = detectFramework(webDir);
+  const port = resolvePort(webDir, fw);
+
+  // Always prefer an already-running server on the expected port
+  if (await isPortListening(port)) {
+    const instance: ServerInstance = { process: null, port, url: `http://localhost:${port}` };
+    servers.set(webDir, instance);
+    return instance;
+  }
 
-  const child = spawn("npx", ["vite", "--port", String(port), "--strictPort"], {
+  // Start the dev server for this framework
+  ensureDepsInstalled(webDir, fw);
+
+  // Build command: replace "PORT" placeholder with actual port string
+  const [cmd, ...args] = fw.devCommand.map((part) => part === "PORT" ? String(port) : part);
+
+  // For Node.js, use the project's own dev script from package.json if available
+  let spawnCmd = cmd;
+  let spawnArgs = args;
+  if (fw.kind === "node" && existsSync(join(webDir, "package.json"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(webDir, "package.json"), "utf-8"));
+      const scripts: Record<string, string> = pkg.scripts ?? {};
+      const scriptName = ["dev", "start", "serve", "develop"].find((n) => n in scripts);
+      if (scriptName) {
+        spawnCmd = "npm";
+        spawnArgs = ["run", scriptName];
+      }
+    } catch { /* ignore */ }
+  }
+
+  const child = spawn(spawnCmd, spawnArgs, {
     cwd: webDir,
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none" },
+    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none", [fw.portEnvVar]: String(port) },
   });
 
-  // Wait for "Local:" line from Vite
-  const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
-
-  const url = await new Promise<string>((resolveUrl, reject) => {
-    const timeout = setTimeout(() => {
-      child.kill();
-      reject(new Error("Vite dev server failed to start within 30s"));
-    }, 30_000);
-
-    let output = "";
-    const onData = (chunk: Buffer) => {
-      output += chunk.toString();
-      const clean = stripAnsi(output);
-      const match = clean.match(/Local:\s+(https?:\/\/[^\s]+)/);
-      if (match) {
-        clearTimeout(timeout);
-        child.stdout?.off("data", onData);
-        child.stderr?.off("data", onData);
-        resolveUrl(match[1]);
-      }
-    };
-    child.stdout?.on("data", onData);
-    child.stderr?.on("data", onData);
-    child.on("error", (err) => { clearTimeout(timeout); reject(err); });
-    child.on("exit", (code) => {
-      clearTimeout(timeout);
-      if (!output.includes("Local:")) {
-        reject(new Error(`Vite exited with code ${code} before ready. Output:\n${output.slice(-500)}`));
-      }
-    });
-  });
+  // Collect stderr from the start so we have output for error messages
+  let stderr = "";
+  child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+
+  // Wait for the port to open (framework-agnostic — no stdout parsing needed)
+  const ready = await waitForPort(port, 60_000);
+
+  if (!ready) {
+    child.kill();
+    throw new Error(
+      `${fw.name} dev server did not open port ${port} within 60s.\n` +
+      (stderr ? `stderr:\n${stripAnsi(stderr).slice(-500)}` : ""),
+    );
+  }
 
-  const instance: ServerInstance = { process: child, port, url };
+  const instance: ServerInstance = { process: child, port, url: `http://localhost:${port}` };
   servers.set(webDir, instance);
   return instance;
 }
 
 // ── browser manager (imported from screenshot-shared.ts) ────────────
 
+// ── init_script URL injection ────────────────────────────────────────
+
+/** Append ?__ous_init=<base64> to a URL, respecting existing query params. */
+function appendInitParam(targetUrl: string, initScript: string): string {
+  const url = new URL(targetUrl);
+  url.searchParams.set("__ous_init", Buffer.from(initScript).toString("base64"));
+  return url.toString();
+}
+
 // ── screenshot capture ──────────────────────────────────────────────
 
 export async function takeScreenshot(
@@ -158,6 +366,7 @@ export async function takeScreenshot(
     full_page = false,
     selector,
     output_dir,
+    init_script,
   } = options;
 
   // 1. Find and start
@@ -181,7 +390,8 @@ export async function takeScreenshot(
     }
 
     const base = server.url.replace(/\/+$/, "");
-    const targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    let targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    if (init_script) targetUrl = appendInitParam(targetUrl, init_script);
     await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
 
     if (wait_for > 0) {
@@ -230,6 +440,7 @@ export async function takeScreenshot(
             full_page,
             selector: selector ?? null,
             path: savedPath ?? null,
+            init_script: init_script ?? null,
           }, null, 2),
         },
       ],
@@ -247,6 +458,7 @@ export interface WebBatchCapture {
   selector?: string;
   full_page?: boolean;
   wait_for?: number;
+  init_script?: string;
 }
 
 export interface WebScreenshotBatchOptions {
@@ -255,6 +467,7 @@ export interface WebScreenshotBatchOptions {
   scale?: number;
   theme?: "light" | "dark";
   output_dir?: string;
+  init_script?: string;
 }
 
 // ── batch screenshot ─────────────────────────────────────────────────
@@ -263,7 +476,7 @@ export async function takeScreenshotBatch(
   projectCwd: string,
   options: WebScreenshotBatchOptions,
 ): Promise<ScreenshotResult> {
-  const { captures, viewport = { width: 1280, height: 800 }, scale = 2, theme, output_dir } = options;
+  const { captures, viewport = { width: 1280, height: 800 }, scale = 2, theme, output_dir, init_script: sharedInitScript } = options;
 
   if (captures.length === 0) {
     return { content: [{ type: "text", text: "No web captures specified." }], isError: true };
@@ -286,10 +499,12 @@ export async function takeScreenshotBatch(
 
     const base = server.url.replace(/\/+$/, "");
     const themeLabel = theme ?? "default";
-    const snapshots: Array<{ screen: string; path: string; data: string }> = [];
+    const snapshots: Array<{ screen: string; path: string; data: string; init_script?: string }> = [];
 
     for (const capture of captures) {
-      const targetUrl = `${base}${capture.route.startsWith("/") ? "" : "/"}${capture.route}`;
+      const effectiveInitScript = capture.init_script ?? sharedInitScript;
+      let targetUrl = `${base}${capture.route.startsWith("/") ? "" : "/"}${capture.route}`;
+      if (effectiveInitScript) targetUrl = appendInitParam(targetUrl, effectiveInitScript);
       await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
       await new Promise((r) => setTimeout(r, capture.wait_for ?? 1000));
 
@@ -310,7 +525,7 @@ export async function takeScreenshotBatch(
         writeFileSync(savedPath, buffer);
       }
 
-      snapshots.push({ screen: capture.screen, path: savedPath, data: buffer.toString("base64") });
+      snapshots.push({ screen: capture.screen, path: savedPath, data: buffer.toString("base64"), init_script: effectiveInitScript });
     }
 
     const content: ScreenshotResult["content"] = [];
@@ -318,7 +533,7 @@ export async function takeScreenshotBatch(
       content.push({ type: "image" as const, data: s.data, mimeType: "image/png" });
       content.push({
         type: "text" as const,
-        text: JSON.stringify({ screen: s.screen, path: s.path, viewport, scale, theme: themeLabel }, null, 2),
+        text: JSON.stringify({ screen: s.screen, path: s.path, viewport, scale, theme: themeLabel, init_script: s.init_script ?? null }, null, 2),
       });
     }
     return { content };
@@ -329,20 +544,20 @@ export async function takeScreenshotBatch(
 
 // ── cleanup ─────────────────────────────────────────────────────────
 
-export async function shutdownAll() {
+function killAllServers() {
   for (const [, instance] of servers) {
-    try { instance.process.kill(); } catch { /* already dead */ }
+    if (instance.process) {
+      try { instance.process.kill(); } catch { /* already dead */ }
+    }
   }
   servers.clear();
+}
+
+export async function shutdownAll() {
+  killAllServers();
   await closeBrowser();
 }
 
-process.on("exit", () => {
-  // Sync-only fallback for process exit
-  for (const [, instance] of servers) {
-    try { instance.process.kill(); } catch { /* already dead */ }
-  }
-  servers.clear();
-});
+process.on("exit", killAllServers);
 process.on("SIGINT", () => { shutdownAll().then(() => process.exit(0)); });
 process.on("SIGTERM", () => { shutdownAll().then(() => process.exit(0)); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/schema/semantic-lint.ts

@@ -184,7 +184,8 @@ function collectIconRefs(filePath: string): { refs: Set<string>; suffixes: strin
   if (!isRecord(data) || !isRecord(data.icons)) return { refs, suffixes };
 
   const icons = data.icons as UnknownRecord;
-  const variantSuffixes = isRecord(icons.variants?.suffixes) ? icons.variants.suffixes : {};
+  const variants = isRecord(icons.variants) ? icons.variants : {};
+  const variantSuffixes = isRecord(variants.suffixes) ? variants.suffixes : {};
   for (const suffix of Object.keys(variantSuffixes)) {
     if (suffix.trim()) suffixes.push(suffix);
   }
@@ -217,8 +218,9 @@ function collectIconRefs(filePath: string): { refs: Set<string>; suffixes: strin
     }
   }
 
-  if (typeof icons.fallback?.missing_icon === "string") {
-    refs.add(icons.fallback.missing_icon);
+  const fallback = isRecord(icons.fallback) ? icons.fallback : {};
+  if (typeof fallback.missing_icon === "string") {
+    refs.add(fallback.missing_icon);
   }
 
   return { refs, suffixes };