@drewpayment/mink 0.1.0

package/src/core/description.ts

@@ -0,0 +1,232 @@
+import { basename, extname } from "path";
+
+const MAX_DESCRIPTION_LENGTH = 100;
+
+const CONFIG_DESCRIPTIONS: Record<string, string> = {
+  "package.json": "Node.js package manifest",
+  "tsconfig.json": "TypeScript configuration",
+  "tsconfig.node.json": "TypeScript configuration (Node)",
+  "tailwind.config.js": "Tailwind CSS configuration",
+  "tailwind.config.ts": "Tailwind CSS configuration",
+  "vite.config.js": "Vite build configuration",
+  "vite.config.ts": "Vite build configuration",
+  "next.config.js": "Next.js configuration",
+  "next.config.ts": "Next.js configuration",
+  "next.config.mjs": "Next.js configuration",
+  "eslint.config.js": "ESLint configuration",
+  "eslint.config.mjs": "ESLint configuration",
+  ".eslintrc": "ESLint configuration",
+  ".eslintrc.js": "ESLint configuration",
+  ".eslintrc.json": "ESLint configuration",
+  ".prettierrc": "Prettier configuration",
+  ".prettierrc.json": "Prettier configuration",
+  "prettier.config.js": "Prettier configuration",
+  "Dockerfile": "Docker container definition",
+  "docker-compose.yml": "Docker Compose services",
+  "docker-compose.yaml": "Docker Compose services",
+  "Makefile": "Make build targets",
+  "CMakeLists.txt": "CMake build configuration",
+  "Cargo.toml": "Rust package manifest",
+  "go.mod": "Go module definition",
+  "pyproject.toml": "Python project configuration",
+  "setup.py": "Python package setup",
+  "Gemfile": "Ruby dependency manifest",
+  "composer.json": "PHP package manifest",
+  "build.gradle": "Gradle build configuration",
+  "pom.xml": "Maven build configuration",
+  "bunfig.toml": "Bun configuration",
+};
+
+function truncate(str: string): string {
+  if (str.length <= MAX_DESCRIPTION_LENGTH) return str;
+  return str.slice(0, MAX_DESCRIPTION_LENGTH - 3) + "...";
+}
+
+function hasBinaryContent(content: string): boolean {
+  return content.includes("\0");
+}
+
+function extractMarkdownHeading(content: string): string | null {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+function extractHtmlTitle(content: string): string | null {
+  const match = content.match(/<title[^>]*>([^<]+)<\/title>/i);
+  return match ? match[1].trim() : null;
+}
+
+function extractDocComment(content: string): string | null {
+  // JSDoc / JavaDoc style: /** ... */
+  const jsdoc = content.match(/^\/\*\*\s*\n?\s*\*?\s*(.+)/m);
+  if (jsdoc) return jsdoc[1].replace(/\*\/\s*$/, "").trim();
+
+  // Python docstring: """...""" or '''...'''
+  const pydoc = content.match(/^(?:def |class ).*\n\s*(?:"""|''')(.+)/m);
+  if (pydoc) return pydoc[1].trim();
+
+  // Shell/Ruby/Python top-of-file comment block
+  const lines = content.split("\n");
+  if (lines[0]?.startsWith("#!")) {
+    // Skip shebang, look at next comment
+    for (let i = 1; i < Math.min(lines.length, 5); i++) {
+      const line = lines[i].trim();
+      if (line.startsWith("# ") && line.length > 2) {
+        return line.slice(2).trim();
+      }
+      if (line && !line.startsWith("#")) break;
+    }
+  } else if (lines[0]?.startsWith("# ") && lines[0].length > 2) {
+    return lines[0].slice(2).trim();
+  }
+
+  return null;
+}
+
+function extractExports(content: string): string | null {
+  const exports: string[] = [];
+  const re = /export\s+(?:function|const|class|interface|type|enum)\s+(\w+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(content)) !== null) {
+    exports.push(match[1]);
+  }
+  if (exports.length === 0) return null;
+  return `exports: ${exports.join(", ")}`;
+}
+
+function extractComponent(content: string, filePath: string): string | null {
+  const ext = extname(filePath).toLowerCase();
+  if (![".tsx", ".jsx", ".vue", ".svelte"].includes(ext)) return null;
+
+  // Look for a PascalCase named export (component convention)
+  const namedMatch = content.match(
+    /(?:export\s+(?:default\s+)?function|export\s+const)\s+([A-Z]\w+)/
+  );
+  const componentName = namedMatch
+    ? namedMatch[1]
+    : basename(filePath, ext);
+
+  const elements: string[] = [];
+  if (/<form[\s>]/i.test(content)) elements.push("form");
+  if (/<table[\s>]/i.test(content)) elements.push("table");
+  if (/modal/i.test(content)) elements.push("modal");
+  if (/<ul[\s>]|<ol[\s>]|<li[\s>]/i.test(content)) elements.push("list");
+  if (/<input[\s>]|<textarea[\s>]|<select[\s>]/i.test(content))
+    elements.push("inputs");
+
+  if (elements.length === 0) return null;
+  return `${componentName} — renders ${elements.join(", ")}`;
+}
+
+function extractCiWorkflow(content: string, filePath: string): string | null {
+  const normalized = filePath.replace(/\\/g, "/");
+  const isCi =
+    normalized.includes(".github/workflows/") ||
+    normalized.includes(".gitlab-ci") ||
+    basename(filePath).toLowerCase() === "jenkinsfile";
+  if (!isCi) return null;
+
+  const nameMatch = content.match(/^name:\s*(.+)$/m);
+  if (nameMatch) return `CI: ${nameMatch[1].trim()}`;
+  return `CI: ${basename(filePath)}`;
+}
+
+function extractMigration(content: string, filePath: string): string | null {
+  const normalized = filePath.toLowerCase();
+  const isMigration =
+    normalized.includes("migration") || normalized.includes("migrate");
+  if (!isMigration) return null;
+
+  const tableMatch = content.match(
+    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)/i
+  );
+  if (tableMatch) return `migration: create ${tableMatch[1]}`;
+  return `migration: ${basename(filePath)}`;
+}
+
+function extractFallback(content: string): string | null {
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith("//") && !trimmed.startsWith("#")) {
+      return trimmed;
+    }
+  }
+  return null;
+}
+
+export function extractDescription(filePath: string, content: string): string {
+  const name = basename(filePath);
+  const ext = extname(filePath).toLowerCase();
+
+  // Edge cases first
+  if (content.length === 0) return `${name} — empty file`;
+  if (hasBinaryContent(content)) return `${name} — binary file`;
+
+  let description: string | null = null;
+  const isLargeFile = content.length > 100 * 1024;
+
+  // Priority 1: Markdown heading
+  if ([".md", ".mdx"].includes(ext)) {
+    description = extractMarkdownHeading(content);
+  }
+
+  // Priority 2: HTML title
+  if (!description && [".html", ".htm"].includes(ext)) {
+    description = extractHtmlTitle(content);
+  }
+
+  // Priority 3: Doc comment
+  if (!description) {
+    description = extractDocComment(content);
+  }
+
+  // Priority 4/5: For component files (tsx/jsx/vue/svelte), try component
+  // detection before generic exports so element-rich components get
+  // meaningful descriptions instead of bare export lists.
+  const componentExt = [".tsx", ".jsx", ".vue", ".svelte"];
+  if (!description && componentExt.includes(extname(filePath).toLowerCase())) {
+    description = extractComponent(content, filePath);
+  }
+
+  // Priority 4: Exports (for non-component files, or component files without elements)
+  if (!description) {
+    description = extractExports(content);
+  }
+
+  // Priority 5 (non-component fallback): already handled above for component files
+
+  // Priority 6: Known config file
+  if (!description) {
+    const configDesc = CONFIG_DESCRIPTIONS[name];
+    if (configDesc) description = configDesc;
+  }
+
+  // Priority 7: CI/CD
+  if (!description) {
+    description = extractCiWorkflow(content, filePath);
+  }
+
+  // Priority 8: Migration
+  if (!description) {
+    description = extractMigration(content, filePath);
+  }
+
+  // Priority 9: Fallback
+  if (!description) {
+    description = extractFallback(content);
+  }
+
+  // Final fallback
+  if (!description) {
+    description = name;
+  }
+
+  if (isLargeFile) {
+    description = truncate(description + " (large file)");
+  } else {
+    description = truncate(description);
+  }
+
+  return description;
+}

package/src/core/design-eval/capture.ts

@@ -0,0 +1,269 @@
+import { mkdirSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import puppeteer from "puppeteer-core";
+import type { Browser, Page } from "puppeteer-core";
+import { minkRoot } from "../paths";
+import type {
+  Viewport,
+  CaptureResult,
+  DesignEvalReport,
+  DesignQcOptions,
+} from "../../types/design-eval";
+
+// ── Browser Detection ─────────────────────────────────────────────────────
+
+const CHROME_PATHS: Record<string, string[]> = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  ],
+  linux: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    `${process.env.LOCALAPPDATA ?? ""}\\Google\\Chrome\\Application\\chrome.exe`,
+  ],
+};
+
+/**
+ * Find a Chrome/Chromium executable on the system.
+ * Checks platform-specific paths, then ~/.mink/browsers/.
+ */
+export function findBrowser(): string {
+  const platform = process.platform;
+
+  // Check system paths
+  const paths = CHROME_PATHS[platform] ?? [];
+  for (const p of paths) {
+    if (existsSync(p)) return p;
+  }
+
+  // Check mink-managed browser installs
+  const minkBrowsers = join(minkRoot(), "browsers");
+  if (existsSync(minkBrowsers)) {
+    // Look for chrome/chromium executables recursively
+    const found = findChromeInDir(minkBrowsers);
+    if (found) return found;
+  }
+
+  throw new Error(
+    [
+      "[mink] No Chrome/Chromium browser found.",
+      "",
+      "Install one of:",
+      "  • Google Chrome: https://www.google.com/chrome/",
+      "  • Or run: npx @puppeteer/browsers install chrome@stable --path ~/.mink/browsers",
+      "",
+      "Then retry: mink designqc",
+    ].join("\n")
+  );
+}
+
+function findChromeInDir(dir: string): string | null {
+  const { readdirSync, statSync } = require("fs") as typeof import("fs");
+  try {
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      const full = join(dir, entry);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+          const found = findChromeInDir(full);
+          if (found) return found;
+        } else if (/^(chrome|chromium|Google Chrome)$/i.test(entry)) {
+          return full;
+        }
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+    // dir not readable
+  }
+  return null;
+}
+
+// ── Route Sanitization ────────────────────────────────────────────────────
+
+/**
+ * Convert a route path to a safe filename prefix.
+ * "/" → "index", "/about" → "about", "/foo/bar" → "foo-bar"
+ */
+export function sanitizeRoute(route: string): string {
+  if (route === "/") return "index";
+  return route
+    .replace(/^\//, "")
+    .replace(/\/+/g, "-")
+    .replace(/[^a-zA-Z0-9-_]/g, "_");
+}
+
+/**
+ * Calculate how many viewport-height sections are needed.
+ */
+export function calculateSections(
+  pageHeight: number,
+  viewportHeight: number,
+  maxSections: number
+): number {
+  if (pageHeight <= 0) return 0;
+  return Math.min(Math.ceil(pageHeight / viewportHeight), maxSections);
+}
+
+// ── Screenshot Capture ────────────────────────────────────────────────────
+
+/**
+ * Capture a single route at a single viewport, producing sectioned screenshots.
+ */
+export async function captureRoute(
+  page: Page,
+  route: string,
+  baseUrl: string,
+  viewport: Viewport,
+  options: { quality: number; maxSections: number; outputDir: string }
+): Promise<CaptureResult[]> {
+  const results: CaptureResult[] = [];
+  const url = `${baseUrl.replace(/\/$/, "")}${route}`;
+  const timestamp = new Date().toISOString();
+
+  // Set viewport
+  await page.setViewport({ width: viewport.width, height: viewport.height });
+
+  // Navigate and wait for stability
+  const response = await page.goto(url, {
+    waitUntil: "networkidle0",
+    timeout: 30000,
+  });
+  const statusCode = response?.status() ?? 0;
+
+  // Get full page height
+  const pageHeight = await page.evaluate(() => {
+    return Math.max(
+      document.body.scrollHeight,
+      document.documentElement.scrollHeight
+    );
+  });
+
+  const totalSections = calculateSections(
+    pageHeight,
+    viewport.height,
+    options.maxSections
+  );
+
+  if (totalSections === 0) return results;
+
+  const prefix = sanitizeRoute(route);
+
+  for (let section = 0; section < totalSections; section++) {
+    const y = section * viewport.height;
+    const clipHeight = Math.min(viewport.height, pageHeight - y);
+
+    const fileName = `${prefix}-${viewport.name}-${section}.jpg`;
+    const filePath = join(options.outputDir, fileName);
+
+    await page.screenshot({
+      path: filePath,
+      type: "jpeg",
+      quality: options.quality,
+      clip: {
+        x: 0,
+        y,
+        width: viewport.width,
+        height: clipHeight,
+      },
+    });
+
+    let fileSize = 0;
+    try {
+      fileSize = statSync(filePath).size;
+    } catch {
+      // stat failed — leave as 0
+    }
+
+    results.push({
+      route,
+      viewport: viewport.name,
+      section,
+      totalSections,
+      filePath,
+      fileName,
+      fileSize,
+      pageHeight,
+      statusCode,
+      timestamp,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Capture all routes across all viewports. Launches the browser once.
+ */
+export async function captureAllRoutes(
+  routes: string[],
+  baseUrl: string,
+  viewports: Viewport[],
+  options: DesignQcOptions,
+  outputDir: string
+): Promise<DesignEvalReport> {
+  mkdirSync(outputDir, { recursive: true });
+
+  const executablePath = findBrowser();
+  const browser: Browser = await puppeteer.launch({
+    executablePath,
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+
+  const report: DesignEvalReport = {
+    capturedAt: new Date().toISOString(),
+    serverUrl: baseUrl,
+    routes,
+    viewports,
+    quality: options.quality,
+    captures: [],
+    errors: [],
+  };
+
+  try {
+    const page = await browser.newPage();
+
+    for (const route of routes) {
+      for (const viewport of viewports) {
+        try {
+          const results = await captureRoute(page, route, baseUrl, viewport, {
+            quality: options.quality,
+            maxSections: options.maxSections,
+            outputDir,
+          });
+          report.captures.push(...results);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          report.errors.push({
+            route,
+            viewport: viewport.name,
+            error: message,
+          });
+          console.error(
+            `[mink] Error capturing ${route} (${viewport.name}): ${message}`
+          );
+        }
+      }
+    }
+
+    await page.close();
+  } finally {
+    await browser.close();
+  }
+
+  return report;
+}

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

@@ -0,0 +1,165 @@
+import { existsSync, readdirSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+
+export type FrameworkType = "nextjs" | "sveltekit" | "nuxt" | "generic";
+
+/**
+ * Detect the frontend framework by checking for config files.
+ */
+export function detectFramework(cwd: string): FrameworkType {
+  const has = (name: string) =>
+    ["js", "mjs", "ts", "cjs"].some((ext) =>
+      existsSync(join(cwd, `${name}.${ext}`))
+    ) || existsSync(join(cwd, name));
+
+  if (has("next.config")) return "nextjs";
+  if (has("svelte.config")) return "sveltekit";
+  if (has("nuxt.config")) return "nuxt";
+  return "generic";
+}
+
+/**
+ * Detect capturable routes based on the project's framework conventions.
+ * Only returns static routes — dynamic segments like [param] are excluded.
+ */
+export function detectRoutes(cwd: string): string[] {
+  const framework = detectFramework(cwd);
+
+  switch (framework) {
+    case "nextjs":
+      return detectNextRoutes(cwd);
+    case "sveltekit":
+      return detectSvelteKitRoutes(cwd);
+    case "nuxt":
+      return detectNuxtRoutes(cwd);
+    case "generic":
+    default:
+      return ["/"];
+  }
+}
+
+// ── Next.js ───────────────────────────────────────────────────────────────
+
+function detectNextRoutes(cwd: string): string[] {
+  const routes: string[] = [];
+
+  // App Router: app/**/page.{tsx,jsx,js,ts}
+  const appDir = join(cwd, "app");
+  if (existsSync(appDir)) {
+    const pageFiles = findFiles(appDir, /^page\.(tsx?|jsx?)$/);
+    for (const file of pageFiles) {
+      const rel = relative(appDir, file);
+      const dir = rel.replace(/([/\\])?page\.(tsx?|jsx?)$/, "");
+      const route = dir === "" ? "/" : `/${dir.split(sep).join("/")}`;
+
+      // Skip dynamic segments, route groups, and parallel routes
+      if (/\[|@|\(/.test(route)) continue;
+      routes.push(route);
+    }
+  }
+
+  // Pages Router: pages/**/*.{tsx,jsx,js,ts}
+  const pagesDir = join(cwd, "pages");
+  if (existsSync(pagesDir)) {
+    const pageFiles = findFiles(pagesDir, /\.(tsx?|jsx?)$/);
+    for (const file of pageFiles) {
+      const rel = relative(pagesDir, file);
+      const name = rel.replace(/\.(tsx?|jsx?)$/, "");
+
+      // Skip special Next.js files and API routes
+      if (/^_(app|document|error)/.test(name)) continue;
+      if (name.startsWith(`api${sep}`) || name === "api") continue;
+      // Skip dynamic segments
+      if (/\[/.test(name)) continue;
+
+      const route =
+        name === "index" ? "/" : `/${name.split(sep).join("/")}`;
+      routes.push(route);
+    }
+  }
+
+  // Deduplicate (app router and pages router may both define /)
+  const unique = [...new Set(routes)];
+  return unique.length > 0 ? unique.sort() : ["/"];
+}
+
+// ── SvelteKit ─────────────────────────────────────────────────────────────
+
+function detectSvelteKitRoutes(cwd: string): string[] {
+  const routesDir = join(cwd, "src", "routes");
+  if (!existsSync(routesDir)) return ["/"];
+
+  const routes: string[] = [];
+  const pageFiles = findFiles(routesDir, /^\+page\.svelte$/);
+
+  for (const file of pageFiles) {
+    const rel = relative(routesDir, file);
+    const dir = rel.replace(/([/\\])?\+page\.svelte$/, "");
+    const route = dir === "" ? "/" : `/${dir.split(sep).join("/")}`;
+
+    // Skip dynamic segments and groups
+    if (/\[|\(/.test(route)) continue;
+    routes.push(route);
+  }
+
+  return routes.length > 0 ? routes.sort() : ["/"];
+}
+
+// ── Nuxt ──────────────────────────────────────────────────────────────────
+
+function detectNuxtRoutes(cwd: string): string[] {
+  const pagesDir = join(cwd, "pages");
+  if (!existsSync(pagesDir)) return ["/"];
+
+  const routes: string[] = [];
+  const vueFiles = findFiles(pagesDir, /\.vue$/);
+
+  for (const file of vueFiles) {
+    const rel = relative(pagesDir, file);
+    const name = rel.replace(/\.vue$/, "");
+
+    // Skip dynamic segments
+    if (/\[/.test(name)) continue;
+
+    const route =
+      name === "index" ? "/" : `/${name.split(sep).join("/")}`;
+    routes.push(route);
+  }
+
+  return routes.length > 0 ? routes.sort() : ["/"];
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function findFiles(dir: string, pattern: RegExp): string[] {
+  const results: string[] = [];
+
+  function walk(current: string): void {
+    let entries: string[];
+    try {
+      entries = readdirSync(current);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      // Skip hidden dirs and node_modules
+      if (entry.startsWith(".") || entry === "node_modules") continue;
+
+      const full = join(current, entry);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+          walk(full);
+        } else if (pattern.test(entry)) {
+          results.push(full);
+        }
+      } catch {
+        // Skip inaccessible entries
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}