dslinter 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## v0.5.1
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.5.0...v0.5.1)
+
+### 🚀 Enhancements
+
+- **dashboard:** Add embed support and improve dev server configuration ([80526e4](https://github.com/jrmybtlr/DSLinter/commit/80526e4))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.5.0
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.4.0...v0.5.0)
+
+### 🚀 Enhancements
+
+- **dashboard:** Enhance dev banner with network and scanner information ([ef5f1c8](https://github.com/jrmybtlr/DSLinter/commit/ef5f1c8))
+
+### 🩹 Fixes
+
+- **dashboard:** Update inline style handling and improve linting for color values ([70a7d1d](https://github.com/jrmybtlr/DSLinter/commit/70a7d1d))
+
+### 💅 Refactors
+
+- **dashboard:** Update dev banner and button component styles ([3baa3d1](https://github.com/jrmybtlr/DSLinter/commit/3baa3d1))
+
+### 🏡 Chore
+
+- Update package-lock.json and pnpm-lock.yaml, add SECURITY.md, and enhance version checks for native bindings ([9d29b82](https://github.com/jrmybtlr/DSLinter/commit/9d29b82))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.4.0
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.3.0...v0.4.0)

package/README.md

@@ -77,7 +77,7 @@ Previews load your components with your Vite `@/` aliases and Inertia stubs (`us
 
 The embed dev server registers Tailwind `@source` paths for your `.dslinter.json` **`include_dirs`** (for example `resources/js/components`), so component utility classes like `px-3.5` are generated in preview CSS. For 100% parity with your app's full CSS pipeline (theme entry, `@custom-variant`, etc.), use `DSLINTER_USE_CONSUMER_VITE=1` instead.
 
-The prebuilt **`dashboard-dist`** bundle shipped on npm does not run this Vite transform; use embed dev mode (monorepo / git checkout) or consumer Vite for accurate preview styling.
+`npx dslinter` on **npm installs** starts the embed dev server on port **5175** (using `vite/embed-serve.config.ts` and your project's Vite install). Open the **Dashboard** URL from the terminal banner — not the scanner-only port (`7878`). The prebuilt **`dashboard-dist`** fallback serves governance UI only; live previews need the embed dev server.
 
 For apps that already embed the dashboard (like this repo's `demo/`), dev mode uses your app's Vite server when `src/App.tsx` imports `DashboardLayout` from `dslinter`.
 
@@ -108,6 +108,14 @@ Open the **Dashboard** URL from the terminal banner (default port `5175`). The s
 
 No Inertia route, no `buildRegistry.ts`, and no `vite.config` edits are required for dev previews.
 
+**Troubleshooting previews**
+
+- Open the **Dashboard** URL from the `npx dslinter` banner (default `http://127.0.0.1:5175/`), not the scanner API port alone.
+- Run from the **project root** (`npx dslinter .`) so `playgrounds[].rel_path` matches your repo (for example `resources/js/components/app-logo.tsx`).
+- Ensure `.dslinter.json` **`include_dirs`** includes your components folder (for example `resources/js/components`).
+- If you see `@dslinter-scan/…` or glob join errors, upgrade `dslinter` and confirm the embed dev server started (not the prebuilt `dashboard-dist` fallback).
+- Use `<DashboardLayout autoPlayground />` — not `buildRegistry.ts` — unless you run through a Vite dev server that compiles your `import.meta.glob`.
+
 **Optional — embed dashboard in your app:** set `DSLINTER_USE_CONSUMER_VITE=1`, add `plugins: [dslinter()]` from `dslinter/vite`, and render `<DashboardLayout autoPlayground dslinterReport={...} />`.
 
 **Optional — custom playground controls:** `npx dslinter init --laravel` scaffolds `resources/js/playground/buildRegistry.ts`.

package/bin/lib/dev-banner.mjs

@@ -1,5 +1,14 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import {
+  dashboardSharesScannerPort,
+  formatMcpAgentHint,
+  formatMcpDataStatus,
+  getLanIpv4Addresses,
+  hasMcpConfig,
+  httpUrl,
+  scannerApiUrl,
+} from "./network-hosts.mjs";
 
 const BOX = {
   tl: "╭",
@@ -163,6 +172,8 @@ function boxLines(lines, totalWidth) {
  *   dashboardUrl?: string | null;
  *   bundledUrl?: string | null;
  *   pollMs?: number;
+ *   projectRoot?: string;
+ *   mcpConfigured?: boolean;
  * }} opts
  * @returns {string}
  */
@@ -177,6 +188,19 @@ export function formatDevBanner(opts) {
   const scannerWarnPlain = opts.apiAvailable
     ? null
     : `unavailable — port ${opts.apiPort} in use`;
+  const scannerUrl = scannerApiUrl(opts.apiPort);
+  const showScannerApi =
+    opts.apiAvailable &&
+    dashboardUrl != null &&
+    !dashboardSharesScannerPort(dashboardUrl, opts.apiPort);
+  const showMcpData = !showScannerApi;
+  const mcpDataPlain = formatMcpDataStatus(opts.apiPort, opts.apiAvailable);
+  const mcpConfigured =
+    opts.mcpConfigured ??
+    (opts.projectRoot ? hasMcpConfig(opts.projectRoot) : false);
+  const mcpHintPlain = formatMcpAgentHint(mcpConfigured);
+  const lanHost = opts.apiAvailable ? getLanIpv4Addresses()[0] : undefined;
+  const networkUrl = lanHost ? httpUrl(opts.apiPort, lanHost) : null;
 
   /** @type {number[]} */
   const plainWidths = [
@@ -184,12 +208,20 @@ export function formatDevBanner(opts) {
     14 + 2 + scanPlain.length,
   ];
   if (dashboardUrl) plainWidths.push(14 + 2 + dashboardUrl.length);
+  if (showScannerApi) plainWidths.push(14 + 2 + scannerUrl.length);
+  if (networkUrl) plainWidths.push(14 + 2 + networkUrl.length);
+  if (showMcpData) plainWidths.push(14 + 2 + mcpDataPlain.length);
   if (scannerWarnPlain) plainWidths.push(14 + 2 + scannerWarnPlain.length);
   if (opts.pollMs) plainWidths.push(14 + 2 + `polling every ${opts.pollMs} ms`.length);
-  const footerPlain = dashboardUrl
-    ? "  Open the Dashboard in your browser. Ctrl+C to stop."
-    : "  Ctrl+C to stop.";
-  plainWidths.push(visibleLength(footerPlain));
+  const footerLines = [
+    dashboardUrl
+      ? "  Open the Dashboard in your browser. Ctrl+C to stop."
+      : "  Ctrl+C to stop.",
+    `  ${mcpHintPlain}`,
+  ];
+  for (const line of footerLines) {
+    plainWidths.push(visibleLength(line));
+  }
 
   const contentWidth = Math.min(maxBox - 4, Math.max(...plainWidths, 40));
   const totalWidth = contentWidth + 4;
@@ -213,13 +245,30 @@ export function formatDevBanner(opts) {
       ...row(color.label("Dashboard"), dashboardUrl, contentWidth, color.url),
     );
   }
+  if (showScannerApi) {
+    styledRows.push(
+      ...row(color.label("Scanner API"), scannerUrl, contentWidth, color.url),
+    );
+  }
+  if (networkUrl) {
+    styledRows.push(
+      ...row(color.label("Network"), networkUrl, contentWidth, color.url),
+    );
+  }
+  if (showMcpData) {
+    styledRows.push(
+      ...row(color.label("MCP data"), mcpDataPlain, contentWidth, color.value),
+    );
+  }
   if (scannerWarnPlain) {
     styledRows.push(
       ...row(color.label("Scanner"), scannerWarnPlain, contentWidth, color.err),
     );
   }
   styledRows.push("");
-  styledRows.push(color.dim(footerPlain));
+  for (const line of footerLines) {
+    styledRows.push(color.dim(line));
+  }
 
   return boxLines(styledRows, totalWidth).join("\n");
 }

package/bin/lib/dev-banner.test.mjs

@@ -22,7 +22,7 @@ describe("shortenPath", () => {
 });
 
 describe("formatDevBanner", () => {
-  it("includes logo, scan path, dashboard URL, and watch info", () => {
+  it("includes logo, scan path, dashboard URL, scanner API, and agent hint", () => {
     const text = formatDevBanner({
       scanPath: "/tmp/components",
       reportPath: "/tmp/components/public/dslinter-report.json",
@@ -30,6 +30,7 @@ describe("formatDevBanner", () => {
       apiAvailable: true,
       dashboardUrl: "http://localhost:5173/",
       pollMs: 150,
+      mcpConfigured: false,
     });
     expect(text).toContain(LOGO[0]);
     expect(text).toContain(LOGO[1]);
@@ -37,14 +38,18 @@ describe("formatDevBanner", () => {
     expect(text).not.toContain("Report file");
     expect(text).toContain("Dashboard");
     expect(text).toContain("http://localhost:5173/");
-    expect(text).not.toContain("Scanner API");
+    expect(text).toContain("Scanner API");
+    expect(text).toContain("http://127.0.0.1:7878/");
+    expect(text).not.toContain("MCP data");
+    expect(text).not.toContain("npx dslinter mcp");
+    expect(text).toContain("add dslinter to .cursor/mcp.json");
     expect(text).not.toContain("dslinter-report.json");
     expect(text).not.toContain("/events");
     expect(text).toContain("polling every 150 ms");
     expect(text).toContain("Open the Dashboard in your browser");
   });
 
-  it("shows bundled URL as the dashboard when no separate dev server", () => {
+  it("shows MCP data row when dashboard shares scanner port", () => {
     const text = formatDevBanner({
       scanPath: "/tmp/components",
       reportPath: "/tmp/components/public/dslinter-report.json",
@@ -52,11 +57,16 @@ describe("formatDevBanner", () => {
       apiAvailable: true,
       bundledUrl: "http://127.0.0.1:7878/",
       pollMs: 150,
+      mcpConfigured: true,
     });
     expect(text).toContain("Dashboard");
     expect(text).toContain("http://127.0.0.1:7878/");
+    expect(text).toContain("MCP data");
+    expect(text).toContain("live @ http://127.0.0.1:7878");
+    expect(text).toContain("Cursor spawns MCP");
     expect(text).not.toContain("Bundled UI");
     expect(text).not.toContain("Scanner API");
+    expect(text).not.toContain("npx dslinter mcp");
   });
 
   it("marks scanner unavailable when port is busy", () => {
@@ -66,10 +76,12 @@ describe("formatDevBanner", () => {
       apiPort: 7878,
       apiAvailable: false,
       dashboardUrl: "http://localhost:5174/",
+      mcpConfigured: false,
     });
     expect(text).toContain("Scanner");
     expect(text).toContain("unavailable");
-    expect(text).not.toContain("7878/");
+    expect(text).toContain("report file");
+    expect(text).toContain("add dslinter to .cursor/mcp.json");
     expect(text).not.toContain("/events");
   });
 
@@ -82,6 +94,7 @@ describe("formatDevBanner", () => {
       dashboardUrl: "http://localhost:5175/",
       bundledUrl: "http://127.0.0.1:7878/",
       pollMs: 150,
+      mcpConfigured: false,
     });
     const rows = text.split("\n").filter((l) => l.startsWith("│"));
     const widths = rows.map((l) => visibleLength(l));

package/bin/lib/network-hosts.mjs

@@ -0,0 +1,81 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { networkInterfaces } from "node:os";
+
+/** @returns {string[]} Non-loopback IPv4 addresses (LAN). */
+export function getLanIpv4Addresses() {
+  /** @type {string[]} */
+  const addrs = [];
+  const ifaces = networkInterfaces();
+  for (const entries of Object.values(ifaces)) {
+    if (!entries) continue;
+    for (const entry of entries) {
+      const family = entry.family;
+      const isIpv4 =
+        family === "IPv4" || family === 4 || String(family) === "IPv4";
+      if (isIpv4 && !entry.internal) {
+        addrs.push(entry.address);
+      }
+    }
+  }
+  return addrs;
+}
+
+/**
+ * @param {number} port
+ */
+export function scannerApiUrl(port) {
+  return `http://127.0.0.1:${port}/`;
+}
+
+/**
+ * Status line for the MCP data source (not a shell command).
+ * @param {number} port
+ * @param {boolean} apiAvailable
+ */
+export function formatMcpDataStatus(port, apiAvailable) {
+  if (!apiAvailable) {
+    return "offline — agents use report file";
+  }
+  return `live @ http://127.0.0.1:${port}`;
+}
+
+/**
+ * @param {boolean} [mcpConfigured]
+ */
+export function formatMcpAgentHint(mcpConfigured = false) {
+  if (mcpConfigured) {
+    return "AI agents: dslinter in .cursor/mcp.json (Cursor spawns MCP)";
+  }
+  return "AI agents: add dslinter to .cursor/mcp.json";
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function hasMcpConfig(projectRoot) {
+  try {
+    const raw = readFileSync(join(projectRoot, ".cursor", "mcp.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return Boolean(parsed?.mcpServers?.dslinter);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string | null | undefined} dashboardUrl
+ * @param {number} apiPort
+ */
+export function dashboardSharesScannerPort(dashboardUrl, apiPort) {
+  if (!dashboardUrl) return false;
+  return dashboardUrl.includes(`:${apiPort}`);
+}
+
+/**
+ * @param {number} port
+ * @param {string} [host]
+ */
+export function httpUrl(port, host = "127.0.0.1") {
+  return `http://${host}:${port}/`;
+}

package/bin/lib/network-hosts.test.mjs

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  dashboardSharesScannerPort,
+  formatMcpAgentHint,
+  formatMcpDataStatus,
+  getLanIpv4Addresses,
+  httpUrl,
+  scannerApiUrl,
+} from "./network-hosts.mjs";
+
+describe("scannerApiUrl", () => {
+  it("formats loopback scanner URL", () => {
+    expect(scannerApiUrl(7878)).toBe("http://127.0.0.1:7878/");
+  });
+});
+
+describe("formatMcpDataStatus", () => {
+  it("shows live data URL when scanner is up", () => {
+    expect(formatMcpDataStatus(7878, true)).toBe(
+      "live @ http://127.0.0.1:7878",
+    );
+  });
+
+  it("notes offline scanner", () => {
+    expect(formatMcpDataStatus(7878, false)).toContain("report file");
+  });
+});
+
+describe("formatMcpAgentHint", () => {
+  it("prompts setup when not configured", () => {
+    expect(formatMcpAgentHint(false)).toContain("add dslinter");
+    expect(formatMcpAgentHint(false)).toContain(".cursor/mcp.json");
+  });
+
+  it("notes Cursor spawns MCP when configured", () => {
+    expect(formatMcpAgentHint(true)).toContain("Cursor spawns MCP");
+  });
+});
+
+describe("dashboardSharesScannerPort", () => {
+  it("detects bundled dashboard on scanner port", () => {
+    expect(dashboardSharesScannerPort("http://127.0.0.1:7878/", 7878)).toBe(true);
+    expect(dashboardSharesScannerPort("http://localhost:5173/", 7878)).toBe(false);
+  });
+});
+
+describe("getLanIpv4Addresses", () => {
+  it("returns an array", () => {
+    expect(Array.isArray(getLanIpv4Addresses())).toBe(true);
+  });
+});
+
+describe("httpUrl", () => {
+  it("builds URL with custom host", () => {
+    expect(httpUrl(7878, "192.168.1.10")).toBe("http://192.168.1.10:7878/");
+  });
+});

package/bin/lib/project-root.mjs

@@ -32,7 +32,27 @@ function maxMtimeInDir(dir, latest = 0) {
 
 /**
  * @param {string} [root]
- * @returns {boolean} true when embed SPA sources exist (monorepo / git checkout).
+ * @returns {boolean} true when the embed SPA dev server can start (npm or monorepo).
+ */
+export function canRunEmbedVite(root = packageRoot) {
+  return (
+    existsSync(join(root, "index.html")) ||
+    existsSync(join(root, "embed", "main.tsx"))
+  );
+}
+
+/**
+ * @param {string} [root]
+ * @returns {string | null} absolute path to published embed Vite config
+ */
+export function embedServeConfigPath(root = packageRoot) {
+  const configPath = join(root, "vite", "embed-serve.config.ts");
+  return existsSync(configPath) ? configPath : null;
+}
+
+/**
+ * @param {string} [root]
+ * @returns {boolean} true when embed SPA sources exist for building dashboard-dist.
  */
 export function hasEmbedDashboard(root = packageRoot) {
   return existsSync(join(root, "index.html"));
@@ -45,7 +65,10 @@ export function hasEmbedDashboard(root = packageRoot) {
  */
 export function ensureDashboardBuilt(root = packageRoot) {
   const distDir = join(root, "dashboard-dist");
-  if (!hasEmbedDashboard(root)) {
+  const canBuildFromSource =
+    existsSync(join(root, "index.html")) &&
+    existsSync(join(root, "vite.config.ts"));
+  if (!canBuildFromSource) {
     return dashboardDirIfReady(distDir);
   }
 

package/bin/lib/project-root.test.mjs

@@ -5,6 +5,8 @@ import { describe, expect, it } from "vitest";
 import {
   defaultReportPath,
   ensureDashboardBuilt,
+  canRunEmbedVite,
+  embedServeConfigPath,
   hasEmbedDashboard,
 } from "./project-root.mjs";
 
@@ -17,6 +19,28 @@ describe("ensureDashboardBuilt (published install layout)", () => {
     writeFileSync(join(root, "src", "index.ts"), "export {};\n");
 
     expect(hasEmbedDashboard(root)).toBe(false);
+    expect(canRunEmbedVite(root)).toBe(false);
+
+    const dist = ensureDashboardBuilt(root);
+    expect(dist).toBeTruthy();
+    expect(dist).toContain("dashboard-dist");
+  });
+
+  it("canRunEmbedVite when published embed sources exist without root vite.config.ts", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-published-embed-"));
+    mkdirSync(join(root, "dashboard-dist"), { recursive: true });
+    writeFileSync(join(root, "dashboard-dist", "index.html"), "<!doctype html>");
+    mkdirSync(join(root, "embed"), { recursive: true });
+    writeFileSync(join(root, "embed", "main.tsx"), "export {};\n");
+    mkdirSync(join(root, "vite"), { recursive: true });
+    writeFileSync(
+      join(root, "vite", "embed-serve.config.ts"),
+      "export default {};\n",
+    );
+
+    expect(hasEmbedDashboard(root)).toBe(false);
+    expect(canRunEmbedVite(root)).toBe(true);
+    expect(embedServeConfigPath(root)).toBe(join(root, "vite", "embed-serve.config.ts"));
 
     const dist = ensureDashboardBuilt(root);
     expect(dist).toBeTruthy();

package/bin/lib/scan-host.test.mjs

@@ -6,6 +6,7 @@ import {
   scanProjectHostsDashboard,
   shouldUseConsumerViteDev,
 } from "./scan-host.mjs";
+import { canRunEmbedVite, embedServeConfigPath } from "./project-root.mjs";
 
 describe("scanProjectHostsDashboard", () => {
   it("detects DashboardLayout in src/App.tsx", () => {
@@ -38,4 +39,23 @@ describe("shouldUseConsumerViteDev", () => {
     expect(shouldUseConsumerViteDev(root)).toBe(false);
     process.env.DSLINTER_USE_CONSUMER_VITE = prev;
   });
+
+  it("uses embed vite on published npm layout when embed sources ship", () => {
+    const laravelRoot = mkdtempSync(join(tmpdir(), "dslinter-laravel-npm-"));
+    mkdirSync(join(laravelRoot, "resources", "js"), { recursive: true });
+    writeFileSync(join(laravelRoot, "vite.config.js"), "export default {};\n");
+
+    const dslinterPkg = mkdtempSync(join(tmpdir(), "dslinter-pkg-"));
+    mkdirSync(join(dslinterPkg, "embed"), { recursive: true });
+    writeFileSync(join(dslinterPkg, "embed", "main.tsx"), "export {};\n");
+    mkdirSync(join(dslinterPkg, "vite"), { recursive: true });
+    writeFileSync(
+      join(dslinterPkg, "vite", "embed-serve.config.ts"),
+      "export default {};\n",
+    );
+
+    expect(shouldUseConsumerViteDev(laravelRoot)).toBe(false);
+    expect(canRunEmbedVite(dslinterPkg)).toBe(true);
+    expect(embedServeConfigPath(dslinterPkg)).not.toBeNull();
+  });
 });

package/bin/modes/dev.mjs

@@ -5,7 +5,8 @@ import {
   defaultServePort,
   findViteRoot,
   getDashboardPackageRoot,
-  hasEmbedDashboard,
+  canRunEmbedVite,
+  embedServeConfigPath,
   resolveBundledDashboardDir,
   resolveViteBin,
 } from "../lib/project-root.mjs";
@@ -41,6 +42,7 @@ async function resolveUiPort(preferred) {
  *   apiAvailable: boolean;
  *   dashboardUrl?: string | null;
  *   bundledUrl?: string | null;
+ *   projectRoot: string;
  * }} banner
  */
 function printDevBanner(banner) {
@@ -79,13 +81,18 @@ export async function runDevMode({
 
   const consumerViteRoot = findViteRoot(scanAbs);
   const embedRoot = getDashboardPackageRoot();
-  const embedViteBin = hasEmbedDashboard() ? resolveViteBin(embedRoot) : null;
+  const embedConfig = embedServeConfigPath(embedRoot);
+  const embedViteBin = canRunEmbedVite(embedRoot)
+    ? resolveViteBin(embedRoot) ??
+      (consumerViteRoot ? resolveViteBin(consumerViteRoot) : null)
+    : null;
 
   const useConsumerViteDev =
     consumerViteRoot != null && shouldUseConsumerViteDev(scanAbs);
 
   const useEmbedViteDev =
     embedViteBin != null &&
+    embedConfig != null &&
     !useConsumerViteDev &&
     process.env.DSLINTER_NO_EMBED_VITE?.trim() !== "1";
 
@@ -111,6 +118,9 @@ export async function runDevMode({
 
   if (attachBundledStatic) {
     args.push("--dashboard-static", bundledDist);
+    process.stderr.write(
+      "dslinter: warning: using prebuilt dashboard — live component previews are unavailable. Upgrade dslinter or ensure the embed dev server starts (Dashboard URL on port 5175).\n",
+    );
   }
 
   const apiAvailable = !(await warnIfPortBusy(port, { silent: true }));
@@ -164,6 +174,7 @@ export async function runDevMode({
     apiPort: port,
     apiAvailable,
     bundledUrl,
+    projectRoot: projectAbs,
   };
 
   const consumerViteRootForEnv = consumerViteRoot ?? findViteRoot(scanAbs);
@@ -179,7 +190,7 @@ export async function runDevMode({
       [
         embedViteBin,
         "--config",
-        join(embedRoot, "vite.config.ts"),
+        embedConfig,
         "--mode",
         "serve",
         "--port",