@wix/agent-skills 1.0.0

package/skills/wix-design-system/scripts/wds.cjs

@@ -0,0 +1,531 @@
+#!/usr/bin/env node
+
+/**
+ * WDS Documentation Helper
+ *
+ * Auto-discovers @wix/design-system in node_modules and provides
+ * fast, focused lookups for components, props, examples, and icons.
+ *
+ * Usage:
+ *   node <path-to>/wds.cjs search <keyword>
+ *   node <path-to>/wds.cjs component <Name>
+ *   node <path-to>/wds.cjs components <Name1> <Name2>...
+ *   node <path-to>/wds.cjs example <Name> <ExampleName>
+ *   node <path-to>/wds.cjs testkit <Name> [method]
+ *   node <path-to>/wds.cjs icons <query>
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// Path discovery
+// ---------------------------------------------------------------------------
+
+function tryEnablePnp() {
+  // Yarn Berry PnP projects have no node_modules. Walk up from cwd looking for
+  // .pnp.cjs and activate it so require.resolve can see PnP-managed packages.
+  let dir = process.cwd();
+  while (true) {
+    const pnp = path.join(dir, ".pnp.cjs");
+    if (fs.existsSync(pnp)) {
+      try {
+        require(pnp).setup();
+      } catch {
+        // ignore — fall through to other discovery paths
+      }
+      return;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+
+function findDocsDir() {
+  tryEnablePnp();
+
+  // Primary: use Node's module resolver (handles symlinks, pnpm, yarn PnP, etc.)
+  try {
+    const pkgPath = require.resolve("@wix/design-system/package.json", {
+      paths: [process.cwd()],
+    });
+    const docsDir = path.join(path.dirname(pkgPath), "dist", "docs");
+    if (fs.existsSync(docsDir)) return docsDir;
+  } catch {
+    // resolve failed — fall through to filesystem scan
+  }
+
+  // Fallback: walk up from cwd looking for node_modules
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path.join(
+      dir,
+      "node_modules",
+      "@wix",
+      "design-system",
+      "dist",
+      "docs"
+    );
+    if (fs.existsSync(candidate)) return candidate;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+function readFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function buildTermsPattern(args) {
+  // Tolerate both `search foo bar` (separate args) and `search "foo bar"`
+  // (single quoted arg). Without the split, a single quoted string becomes a
+  // literal-phrase match instead of OR-of-words and silently returns nothing.
+  return args
+    .flatMap((a) => a.split(/\s+/))
+    .filter(Boolean)
+    .map(escapeRegex)
+    .join("|");
+}
+
+function validateComponentName(name) {
+  if (!/^[A-Za-z0-9]+$/.test(name)) {
+    console.error(
+      `Invalid component name "${name}". Names may only contain letters and digits.`
+    );
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function cmdSearch(docsDir, terms) {
+  if (terms.length === 0) {
+    console.error("Usage: wds.cjs search <keyword> [keyword...]");
+    console.error('Example: wds.cjs search form input validation');
+    process.exit(1);
+  }
+
+  const content = readFile(path.join(docsDir, "components.md"));
+  if (!content) {
+    console.error("Error: components.md not found");
+    process.exit(1);
+  }
+
+  const regex = new RegExp(buildTermsPattern(terms), "i");
+  const sections = content.split(/^\s*### /m).slice(1);
+  const matches = [];
+
+  for (const section of sections) {
+    if (regex.test(section)) {
+      const lines = section.split("\n");
+      const name = lines[0].trim();
+      const descLine = lines.find((l) => l.trimStart().startsWith("- description:"));
+      const desc = descLine ? descLine.replace(/.*- description:/, "").trim() : "";
+      const doLine = lines.find((l) => l.trimStart().startsWith("- do:"));
+      const doText = doLine ? doLine.replace(/.*- do:/, "").trim() : "";
+      const dontLine = lines.find((l) => l.trimStart().startsWith("- donts:"));
+      const dontText = dontLine ? dontLine.replace(/.*- donts:/, "").trim() : "";
+      matches.push({ name, description: desc, do: doText, donts: dontText });
+    }
+  }
+
+  if (matches.length === 0) {
+    console.log(`No components found matching "${terms.join(" ")}".`);
+    return;
+  }
+
+  console.log(`Found ${matches.length} component(s):\n`);
+  for (const r of matches) {
+    console.log(`### ${r.name}`);
+    if (r.description) console.log(`  ${r.description}`);
+    if (r.do) console.log(`  Do: ${r.do}`);
+    if (r.donts) console.log(`  Don't: ${r.donts}`);
+    console.log();
+  }
+}
+
+// Renders one component's props + examples list. Returns true on success,
+// false if the component wasn't found (so batch callers can keep going).
+function printComponent(docsDir, componentName) {
+  validateComponentName(componentName);
+
+  const componentsDir = path.join(docsDir, "components");
+
+  // --- Props ---
+  const propsPath = path.join(componentsDir, `${componentName}Props.md`);
+  const propsContent = readFile(propsPath);
+
+  if (!propsContent) {
+    console.error(
+      `Component "${componentName}" not found. Run: wds.cjs search <keyword>`
+    );
+    return false;
+  }
+
+  const propsLines = propsContent.split("\n");
+  const propsLineCount = propsLines.length;
+
+  console.log(`## ${componentName} Props (${propsLineCount} lines)\n`);
+
+  if (propsLineCount <= 200) {
+    // Small file — include full props
+    console.log(propsContent);
+  } else {
+    // Large file — summarize prop names and types only
+    console.log(
+      `(Large props file — showing summary. Use grep for specific prop details.)\n`
+    );
+    for (const line of propsLines) {
+      if (line.startsWith("### ")) {
+        const propName = line.replace("### ", "").trim();
+        // Find the type line (next line starting with "- type:")
+        const idx = propsLines.indexOf(line);
+        const typeLine = propsLines[idx + 1];
+        const type =
+          typeLine && typeLine.startsWith("- type:")
+            ? typeLine.replace("- type:", "").trim()
+            : "";
+        console.log(`  ${propName}: ${type}`);
+      }
+    }
+  }
+
+  // --- Examples list ---
+  const examplesPath = path.join(componentsDir, `${componentName}Examples.md`);
+  const examplesContent = readFile(examplesPath);
+
+  if (examplesContent) {
+    const exLines = examplesContent.split("\n");
+    const examples = [];
+    for (let i = 0; i < exLines.length; i++) {
+      if (exLines[i].startsWith("### ")) {
+        examples.push(exLines[i].replace("### ", "").trim());
+      }
+    }
+
+    if (examples.length > 0) {
+      console.log(`\n## Available Examples (${examples.length})\n`);
+      for (const ex of examples) {
+        console.log(`  - ${ex}`);
+      }
+      console.log(
+        `\nGet an example: wds.cjs example ${componentName} "<ExampleName>"`
+      );
+    }
+  }
+
+  return true;
+}
+
+function cmdComponent(docsDir, componentName) {
+  if (!componentName) {
+    console.error("Usage: wds.cjs component <ComponentName>");
+    console.error("Example: wds.cjs component Button");
+    process.exit(1);
+  }
+  if (!printComponent(docsDir, componentName)) {
+    process.exit(1);
+  }
+}
+
+// Cheap pre-check so cmdComponents can decide whether to emit a `---`
+// separator before invoking the actual renderer. Avoids stale separators
+// when a middle component is missing.
+function componentExists(docsDir, componentName) {
+  if (!/^[A-Za-z0-9]+$/.test(componentName)) return false;
+  return fs.existsSync(
+    path.join(docsDir, "components", `${componentName}Props.md`)
+  );
+}
+
+function cmdComponents(docsDir, args) {
+  // Accept either `components Button Card` or `components "Button Card"`.
+  const names = args.flatMap((a) => a.split(/\s+/)).filter(Boolean);
+
+  if (names.length === 0) {
+    console.error("Usage: wds.cjs components <Name1> [Name2] [Name3]...");
+    console.error("Example: wds.cjs components Button Card Table");
+    process.exit(1);
+  }
+
+  let printedAny = false;
+  let anyFailed = false;
+  for (const name of names) {
+    // Match the single-component flow: invalid names get a distinct error
+    // instead of being lumped under "not found".
+    if (!/^[A-Za-z0-9]+$/.test(name)) {
+      console.error(
+        `Invalid component name "${name}". Names may only contain letters and digits.`
+      );
+      anyFailed = true;
+      continue;
+    }
+    if (!componentExists(docsDir, name)) {
+      console.error(
+        `Component "${name}" not found. Run: wds.cjs search <keyword>`
+      );
+      anyFailed = true;
+      continue;
+    }
+    if (printedAny) console.log("\n---\n");
+    printComponent(docsDir, name);
+    printedAny = true;
+  }
+
+  // Exit non-zero only if every requested component failed.
+  if (anyFailed && !printedAny) process.exit(1);
+}
+
+function cmdExample(docsDir, componentName, exampleName) {
+  if (!componentName || !exampleName) {
+    console.error('Usage: wds.cjs example <ComponentName> "<ExampleName>"');
+    console.error('Example: wds.cjs example Button "Loading state"');
+    process.exit(1);
+  }
+  validateComponentName(componentName);
+
+  const filePath = path.join(
+    docsDir,
+    "components",
+    `${componentName}Examples.md`
+  );
+  const content = readFile(filePath);
+
+  if (!content) {
+    console.error(`No examples file for "${componentName}".`);
+    process.exit(1);
+  }
+
+  const lines = content.split("\n");
+  let startLine = -1;
+  let endLine = lines.length;
+  const searchName = exampleName.toLowerCase();
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("### ")) {
+      const name = lines[i].replace("### ", "").trim().toLowerCase();
+      if (startLine >= 0) {
+        // Found the next section — stop here
+        endLine = i;
+        break;
+      }
+      if (name === searchName || name.includes(searchName)) {
+        startLine = i;
+      }
+    }
+  }
+
+  if (startLine < 0) {
+    console.error(
+      `Example "${exampleName}" not found for ${componentName}.\n`
+    );
+    // List available examples
+    const available = [];
+    for (const line of lines) {
+      if (line.startsWith("### ")) {
+        available.push(line.replace("### ", "").trim());
+      }
+    }
+    if (available.length > 0) {
+      console.log("Available examples:");
+      for (const ex of available) {
+        console.log(`  - ${ex}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  console.log(lines.slice(startLine, endLine).join("\n"));
+}
+
+function cmdTestkit(docsDir, componentName, methodName) {
+  if (!componentName) {
+    console.error("Usage: wds.cjs testkit <ComponentName> [methodName]");
+    console.error("Example: wds.cjs testkit Button");
+    console.error('Example: wds.cjs testkit Button click');
+    process.exit(1);
+  }
+  validateComponentName(componentName);
+
+  const filePath = path.join(
+    docsDir,
+    "components",
+    `${componentName}Testkit.md`,
+  );
+  const content = readFile(filePath);
+
+  if (!content) {
+    console.error(
+      `Testkit docs for "${componentName}" not found. Run: wds.cjs search <keyword>`,
+    );
+    process.exit(1);
+  }
+
+  if (!methodName) {
+    console.log(content);
+    return;
+  }
+
+  const lines = content.split("\n");
+  const searchName = methodName.toLowerCase();
+  let startLine = -1;
+  let endLine = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("### ") && !lines[i].startsWith("### API")) {
+      const name = lines[i].replace("### ", "").trim().toLowerCase();
+      if (startLine >= 0) {
+        endLine = i;
+        break;
+      }
+      if (name === searchName || name.includes(searchName)) {
+        startLine = i;
+      }
+    }
+  }
+
+  if (startLine < 0) {
+    console.error(
+      `Method "${methodName}" not found on ${componentName} testkit.\n`,
+    );
+    const available = [];
+    let inApiSection = false;
+    for (const line of lines) {
+      if (line.startsWith("### API")) {
+        inApiSection = true;
+        continue;
+      }
+      if (inApiSection && line.startsWith("### ")) {
+        available.push(line.replace("### ", "").trim());
+      }
+    }
+    if (available.length > 0) {
+      console.log("Available methods:");
+      for (const m of available) {
+        console.log(`  - ${m}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  console.log(lines.slice(startLine, endLine).join("\n"));
+}
+
+function cmdIcons(docsDir, terms) {
+  if (terms.length === 0) {
+    console.error("Usage: wds.cjs icons <query> [query...]");
+    console.error("Example: wds.cjs icons Add Edit Delete");
+    process.exit(1);
+  }
+
+  const content = readFile(path.join(docsDir, "icons.md"));
+  if (!content) {
+    console.error("Error: icons.md not found");
+    process.exit(1);
+  }
+
+  const regex = new RegExp(buildTermsPattern(terms), "i");
+  const matches = [];
+
+  for (const line of content.split("\n")) {
+    if (line.trim() && regex.test(line)) {
+      matches.push(line.trim());
+    }
+  }
+
+  if (matches.length === 0) {
+    console.log(`No icons found matching "${terms.join(" ")}".`);
+    return;
+  }
+
+  console.log(`Found ${matches.length} icon(s):\n`);
+  for (const m of matches) {
+    console.log(`  ${m}`);
+  }
+  console.log(
+    "\nIcons are from @wix/wix-ui-icons-common. Each icon has a Small variant (e.g., Add + AddSmall)."
+  );
+}
+
+function cmdHelp(docsDir) {
+  const scriptPath = path.resolve(__dirname, "wds.cjs");
+  console.log(`WDS Documentation Helper
+
+Usage:
+  node ${scriptPath} search <keyword>              Search components by keyword
+  node ${scriptPath} component <Name>              Get props + example list
+  node ${scriptPath} components <Name1> <Name2>... Get props + example list for multiple components in one call
+  node ${scriptPath} example <Name> "<ExampleName>" Get a specific example
+  node ${scriptPath} testkit <Name> [method]       Get testkit imports + API (or one method)
+  node ${scriptPath} icons <query>                 Search for icons
+
+Examples:
+  node ${scriptPath} search table list
+  node ${scriptPath} search form input validation
+  node ${scriptPath} component Button
+  node ${scriptPath} components Button Card Table Input
+  node ${scriptPath} example Button "Loading state"
+  node ${scriptPath} testkit Button
+  node ${scriptPath} testkit Button click
+  node ${scriptPath} icons Add Edit Delete
+
+Docs found at: ${docsDir}`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const docsDir = findDocsDir();
+if (!docsDir) {
+  console.error(
+    "Error: @wix/design-system not found in node_modules.\n" +
+      "Install it first: npm i @wix/design-system"
+  );
+  process.exit(1);
+}
+
+const [command, ...args] = process.argv.slice(2);
+
+switch (command) {
+  case "search":
+    cmdSearch(docsDir, args);
+    break;
+  case "component":
+    cmdComponent(docsDir, args[0]);
+    break;
+  case "components":
+    cmdComponents(docsDir, args);
+    break;
+  case "example":
+    cmdExample(docsDir, args[0], args.slice(1).join(" "));
+    break;
+  case "testkit":
+    cmdTestkit(docsDir, args[0], args[1]);
+    break;
+  case "icons":
+    cmdIcons(docsDir, args);
+    break;
+  default:
+    cmdHelp(docsDir);
+    break;
+}