@drewpayment/mink 0.1.0

package/src/core/design-eval/server-detect.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import type { Subprocess } from "bun";
+import { DEFAULT_PROBE_PORTS } from "../../types/design-eval";
+
+/**
+ * Check if a port is responding to HTTP requests.
+ */
+export async function probePort(port: number): Promise<boolean> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2000);
+    await fetch(`http://localhost:${port}`, { signal: controller.signal });
+    clearTimeout(timeout);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probe common dev server ports and return the first responding URL.
+ */
+export async function findRunningServer(
+  ports: number[] = DEFAULT_PROBE_PORTS
+): Promise<string | null> {
+  for (const port of ports) {
+    if (await probePort(port)) {
+      return `http://localhost:${port}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read package.json scripts to find a likely dev server command.
+ * Checks for "dev", "start", "serve" in that priority order.
+ */
+export function detectDevCommand(cwd: string): string | null {
+  try {
+    const raw = readFileSync(join(cwd, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    const scripts = pkg.scripts;
+    if (!scripts || typeof scripts !== "object") return null;
+
+    for (const key of ["dev", "start", "serve"]) {
+      if (typeof scripts[key] === "string") {
+        // Return the npm/bun run command, not the raw script value
+        return `npm run ${key}`;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Start a dev server and wait for it to become responsive.
+ * Returns the server URL and the spawned process.
+ */
+export async function startAndWaitForServer(
+  cwd: string,
+  command: string,
+  timeoutMs: number = 30000
+): Promise<{ url: string; proc: Subprocess }> {
+  const parts = command.split(/\s+/);
+  const proc = Bun.spawn(parts, {
+    cwd,
+    stdout: "ignore",
+    stderr: "ignore",
+    stdin: "ignore",
+  });
+
+  const start = Date.now();
+  const ports = DEFAULT_PROBE_PORTS;
+
+  while (Date.now() - start < timeoutMs) {
+    for (const port of ports) {
+      if (await probePort(port)) {
+        return { url: `http://localhost:${port}`, proc };
+      }
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  proc.kill();
+  throw new Error(
+    `[mink] Dev server did not respond within ${Math.round(timeoutMs / 1000)}s. Start it manually and retry.`
+  );
+}

package/src/core/framework-advisor/catalog.ts

@@ -0,0 +1,360 @@
+// ── Framework Catalog (Spec 14) ───────────────────────────────────────────
+
+import type { FrameworkEntry } from "../../types/framework-advisor";
+
+export const FRAMEWORK_CATALOG: FrameworkEntry[] = [
+  {
+    id: "tailwind-headlessui",
+    name: "Tailwind CSS + Headless UI",
+    description:
+      "Utility-first CSS framework paired with unstyled, accessible UI primitives for full design control.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "excellent",
+    bundleSize: "small",
+    learningCurve: "low",
+    typescriptSupport: "native",
+    designTokens: false,
+    ecosystem: "React and Vue with first-party support from the Tailwind Labs team",
+    bestFor: [
+      "Custom designs that need full visual control",
+      "Accessible interactive components without opinionated styling",
+      "Projects already using Tailwind CSS",
+    ],
+    limitations: [
+      "Headless UI has a limited component set compared to full libraries",
+      "Requires building your own design system on top",
+      "No built-in theme or design token system",
+    ],
+    officialUrl: "https://headlessui.com",
+  },
+  {
+    id: "shadcn-ui",
+    name: "shadcn/ui",
+    description:
+      "Copy-paste component collection built on Radix primitives and Tailwind CSS that lives in your codebase.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "excellent",
+    bundleSize: "small",
+    learningCurve: "low",
+    typescriptSupport: "native",
+    designTokens: false,
+    ecosystem: "React with Next.js-optimized CLI and growing community registry",
+    bestFor: [
+      "Rapid prototyping with production-quality components",
+      "Teams that want full ownership of component code",
+      "Next.js applications",
+    ],
+    limitations: [
+      "React-only with no official Vue or Svelte port",
+      "Components must be manually updated since they are copied into the project",
+      "Relies on Radix under the hood so inherits its constraints",
+    ],
+    officialUrl: "https://ui.shadcn.com",
+  },
+  {
+    id: "mui",
+    name: "Material UI (MUI)",
+    description:
+      "The most popular React component library, implementing Google's Material Design with deep customization.",
+    cssApproach: "css-in-js",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "large",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "React with a mature ecosystem including MUI X for advanced data grids, date pickers, and charts",
+    bestFor: [
+      "Enterprise dashboards and admin panels",
+      "Teams that want a comprehensive component set out of the box",
+      "Material Design implementations",
+    ],
+    limitations: [
+      "Large bundle size even with tree-shaking",
+      "Emotion-based styling adds runtime overhead",
+      "Overriding deeply nested styles can be cumbersome",
+    ],
+    officialUrl: "https://mui.com",
+  },
+  {
+    id: "chakra-ui",
+    name: "Chakra UI",
+    description:
+      "Accessible React component library with a simple, composable API and built-in style props.",
+    cssApproach: "css-in-js",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "medium",
+    learningCurve: "low",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "React with companion libraries for icons, transitions, and layout utilities",
+    bestFor: [
+      "Rapid application development with accessible defaults",
+      "Teams prioritizing developer experience and composability",
+      "Projects needing easy dark mode and theming",
+    ],
+    limitations: [
+      "Runtime CSS-in-JS can impact performance in large apps",
+      "Smaller component set than MUI or Ant Design",
+      "React-only with no multi-framework support",
+    ],
+    officialUrl: "https://chakra-ui.com",
+  },
+  {
+    id: "ant-design",
+    name: "Ant Design",
+    description:
+      "Enterprise-grade React component library with 60+ polished components and a complete design system.",
+    cssApproach: "css-in-js",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "large",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "React with Ant Design Pro for admin templates, charts, and data visualization",
+    bestFor: [
+      "Enterprise applications and internal tools",
+      "Data-heavy dashboards with complex table requirements",
+      "Teams familiar with Ant Design's opinionated patterns",
+    ],
+    limitations: [
+      "Very large bundle with aggressive tree-shaking needed",
+      "Opinionated design language can be hard to customize away from",
+      "Documentation has inconsistencies between Chinese and English versions",
+    ],
+    officialUrl: "https://ant.design",
+  },
+  {
+    id: "radix-ui",
+    name: "Radix UI",
+    description:
+      "Unstyled, accessible component primitives designed for building high-quality design systems with Tailwind.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "excellent",
+    bundleSize: "small",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: false,
+    ecosystem: "React with Radix Themes for pre-styled components and broad community adoption",
+    bestFor: [
+      "Building custom design systems with rigorous accessibility",
+      "Headless component architecture with full style control",
+      "Projects that combine Radix primitives with Tailwind CSS",
+    ],
+    limitations: [
+      "Headless primitives require significant styling effort",
+      "React-only with no Vue or Svelte support",
+      "Some components have complex API surfaces",
+    ],
+    officialUrl: "https://www.radix-ui.com",
+  },
+  {
+    id: "mantine",
+    name: "Mantine",
+    description:
+      "Hook-driven React component library with 100+ components, native CSS modules, and excellent DX.",
+    cssApproach: "css-modules",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "medium",
+    learningCurve: "low",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "React with companion packages for hooks, forms, notifications, and rich text editing",
+    bestFor: [
+      "Full-featured applications needing a wide component selection",
+      "Teams that prefer CSS modules over CSS-in-JS runtime",
+      "Projects leveraging React hooks heavily",
+    ],
+    limitations: [
+      "React-only with no multi-framework support",
+      "Upgrading between major versions can require significant migration",
+      "Some advanced components have a large API surface",
+    ],
+    officialUrl: "https://mantine.dev",
+  },
+  {
+    id: "daisyui",
+    name: "DaisyUI",
+    description:
+      "Tailwind CSS plugin that adds semantic class names for common UI components with zero JavaScript.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "basic",
+    bundleSize: "tiny",
+    learningCurve: "low",
+    typescriptSupport: "supported",
+    designTokens: false,
+    ecosystem: "Framework-agnostic as a pure CSS Tailwind plugin, usable with React, Vue, Svelte, or plain HTML",
+    bestFor: [
+      "Quick prototypes and landing pages",
+      "Projects that want styled components without JavaScript overhead",
+      "Tailwind users who prefer semantic class names",
+    ],
+    limitations: [
+      "No built-in interactive behavior — JavaScript must be added separately",
+      "Accessibility support is minimal and left to the developer",
+      "Limited customization depth compared to headless approaches",
+    ],
+    officialUrl: "https://daisyui.com",
+  },
+  {
+    id: "vuetify",
+    name: "Vuetify",
+    description:
+      "Comprehensive Material Design component framework for Vue with a vast component library and theming engine.",
+    cssApproach: "traditional",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "large",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "Vue with built-in SASS variables, icon support, and an active community of plugins",
+    bestFor: [
+      "Vue applications following Material Design guidelines",
+      "Enterprise dashboards with complex data tables",
+      "Teams wanting an all-in-one Vue component solution",
+    ],
+    limitations: [
+      "Large bundle size even with tree-shaking via Vuetify loader",
+      "Tightly coupled to Material Design aesthetic",
+      "Major version upgrades have historically required significant migration",
+    ],
+    officialUrl: "https://vuetifyjs.com",
+  },
+  {
+    id: "primevue",
+    name: "PrimeVue",
+    description:
+      "Feature-rich Vue component suite with 90+ components, multiple themes, and an unstyled mode.",
+    cssApproach: "traditional",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "medium",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "Vue with PrimeIcons, PrimeFlex utility CSS, and shared design across PrimeReact and PrimeNG",
+    bestFor: [
+      "Vue applications needing a large selection of pre-built components",
+      "Enterprise forms and data management interfaces",
+      "Teams that want theme flexibility including unstyled headless mode",
+    ],
+    limitations: [
+      "Documentation can lag behind latest releases",
+      "Some components feel less polished than competitors",
+      "Theming system has a learning curve for deep customization",
+    ],
+    officialUrl: "https://primevue.org",
+  },
+  {
+    id: "skeleton-svelte",
+    name: "Skeleton",
+    description:
+      "Tailwind-powered UI toolkit for Svelte and SvelteKit with adaptive theming and clean defaults.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "small",
+    learningCurve: "low",
+    typescriptSupport: "native",
+    designTokens: false,
+    ecosystem: "Svelte and SvelteKit with Tailwind integration and community theme generator",
+    bestFor: [
+      "SvelteKit applications needing a polished component set",
+      "Tailwind-based projects in the Svelte ecosystem",
+      "Developers who want lightweight, themeable components",
+    ],
+    limitations: [
+      "Svelte-only with no React or Vue support",
+      "Smaller component set compared to mature libraries",
+      "Ecosystem and community are still growing",
+    ],
+    officialUrl: "https://www.skeleton.dev",
+  },
+  {
+    id: "angular-material",
+    name: "Angular Material",
+    description:
+      "Official Material Design component library for Angular with strong accessibility and CDK primitives.",
+    cssApproach: "scoped",
+    darkModeSupport: true,
+    accessibilityRating: "excellent",
+    bundleSize: "medium",
+    learningCurve: "steep",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "Angular with the Component Dev Kit (CDK) for building custom components",
+    bestFor: [
+      "Angular enterprise applications",
+      "Teams requiring WAI-ARIA compliant components",
+      "Projects that align with Material Design standards",
+    ],
+    limitations: [
+      "Angular-only with tight framework coupling",
+      "Steep learning curve tied to Angular's own complexity",
+      "Customizing beyond Material Design's aesthetic requires significant effort",
+    ],
+    officialUrl: "https://material.angular.io",
+  },
+  {
+    id: "flowbite",
+    name: "Flowbite",
+    description:
+      "Tailwind CSS component library with vanilla JS and adapters for React, Vue, Svelte, and Angular.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "basic",
+    bundleSize: "tiny",
+    learningCurve: "low",
+    typescriptSupport: "supported",
+    designTokens: false,
+    ecosystem: "Multi-framework with Flowbite React, Vue, Svelte, and Angular adapters plus a Figma design kit",
+    bestFor: [
+      "Multi-framework teams sharing a consistent design",
+      "Marketing sites and landing pages",
+      "Tailwind users who want ready-made components across stacks",
+    ],
+    limitations: [
+      "Accessibility coverage is basic and needs manual enhancement",
+      "Framework adapters vary in completeness and maturity",
+      "Interactive components depend on Flowbite's own JavaScript",
+    ],
+    officialUrl: "https://flowbite.com",
+  },
+  {
+    id: "park-ui",
+    name: "Park UI",
+    description:
+      "Beautifully designed components built on Ark UI primitives with support for React, Vue, and Solid.",
+    cssApproach: "utility-first",
+    darkModeSupport: true,
+    accessibilityRating: "good",
+    bundleSize: "small",
+    learningCurve: "moderate",
+    typescriptSupport: "native",
+    designTokens: true,
+    ecosystem: "Multi-framework via Ark UI with Panda CSS or Tailwind styling and a growing component set",
+    bestFor: [
+      "Multi-framework projects wanting shared accessible primitives",
+      "Teams adopting Panda CSS or modern styling approaches",
+      "Design-conscious applications requiring polished defaults",
+    ],
+    limitations: [
+      "Relatively new with a smaller community than established libraries",
+      "Component count is still growing",
+      "Ark UI dependency adds an additional abstraction layer",
+    ],
+    officialUrl: "https://park-ui.com",
+  },
+];
+
+export function getFrameworkById(id: string): FrameworkEntry | undefined {
+  return FRAMEWORK_CATALOG.find((f) => f.id === id);
+}