docsui-cli 0.0.59

package/README.md

@@ -0,0 +1,279 @@
+# docsui
+
+Copy-paste MDX components for documentation sites. 52+ components including 150+ math primitives, data structures, tables, diagrams, and more — built with React, TypeScript, and Tailwind CSS. CLI, MCP server, and remark plugin included.
+
+Follows the [shadcn/ui](https://ui.shadcn.com) philosophy — components are added directly to your project, not installed as a dependency. You own the code.
+
+## Quick Start
+
+```bash
+# Initialize your project
+npx docsui-cli@latest init
+
+# Add components
+npx docsui-cli@latest add callout tabs code-block
+
+# Or use the interactive menu
+npx docsui-cli@latest
+```
+
+## Commands
+
+### `init`
+
+Sets up mdx-ui in your project:
+
+- Creates `docsui.json` config
+- Injects shadcn-compatible CSS variables into your `globals.css`
+- Patches `tailwind.config` with color tokens (Tailwind v3) or adds `@theme inline` block (Tailwind v4)
+- Injects Shiki dual-theme CSS for syntax highlighting
+- Works with Next.js, Vite React, Astro, and any other framework
+
+```bash
+npx docsui-cli@latest init
+```
+
+### `add`
+
+Adds one or more components to your project:
+
+```bash
+# Add specific components
+npx docsui-cli@latest add callout
+
+# Add multiple at once
+npx docsui-cli@latest add tabs steps accordion
+
+# Interactive picker (no args)
+npx docsui-cli@latest add
+```
+
+Each component is written to your `componentsDir`, its npm dependencies are installed, and your `mdx-components.tsx` is patched with the correct static imports.
+
+### `update`
+
+Re-fetches and overwrites installed components with the latest versions:
+
+```bash
+# Update all installed components
+npx docsui-cli@latest update
+
+# Update specific components
+npx docsui-cli@latest update callout tabs
+```
+
+### `list`
+
+```bash
+# Show all available components
+npx docsui-cli@latest list
+
+# Show only installed components
+npx docsui-cli@latest list --installed
+```
+
+## Available Components (52)
+
+### Content & Layout
+
+| Component         | Description                                                         |
+| ----------------- | ------------------------------------------------------------------- |
+| `alert`           | Semantic `role="alert"` boxes — info, warning, destructive, success |
+| `accordion`       | Collapsible sections — single or multiple open                      |
+| `annotation`      | Inline text annotation — click to reveal explanation popover        |
+| `badge`           | Status labels with 7 variants                                       |
+| `blockquote`      | Styled blockquote                                                   |
+| `callout`         | Alert boxes — info, warning, danger, success                        |
+| `card`            | Card + header/title/description/content/footer + LinkCard           |
+| `changelog`       | Versioned entries with timeline and typed change badges             |
+| `definition`      | Formal term definition in structured format                         |
+| `emphasis`        | Bold (`<strong>`) and italic (`<em>`)                               |
+| `glossary`        | Context-based inline glossary with popovers via `<Term>`            |
+| `heading`         | H1–H6 with auto-generated anchor links                              |
+| `headings`        | Markdown h1–h6 overrides with anchor links                          |
+| `highlight`       | Marker-style inline highlight — yellow, blue, green, pink, purple   |
+| `horizontal-rule` | Divider — default, dashed, dotted, gradient                         |
+| `illustration`    | Single diagram or responsive 1–3 column image grid                  |
+| `image`           | Image with optional caption                                         |
+| `inline-code`     | Inline code snippets                                                |
+| `invariant`       | Formal invariant statement with optional complexity annotation      |
+| `kbd`             | Keyboard shortcut display (`Ctrl+K`, `⌘+S`)                         |
+| `link`            | Styled anchor — auto-detects external URLs, adds open-in-new-tab    |
+| `list`            | Ordered and unordered lists                                         |
+| `paragraph`       | Paragraph with Lead, Intro, Large, Small, Muted variants            |
+| `preview`         | Tabbed component preview — rendered output + source with copy       |
+| `reveal`          | Animated click-to-reveal panel for answers, hints, and spoilers     |
+| `security-note`   | Security callout with severity levels — info, warning, critical     |
+| `spoiler`         | Collapsible `<details>`/`<summary>` disclosure                      |
+| `steps`           | Numbered step-by-step guide                                         |
+| `tabs`            | Tabbed content with keyboard navigation                             |
+
+### Code & Terminal
+
+| Component    | Description                                                     |
+| ------------ | --------------------------------------------------------------- |
+| `code-block` | Syntax-highlighted code blocks via rehype-pretty-code           |
+| `code-group` | Tabbed code blocks — npm/pnpm/yarn or multi-language examples   |
+| `diff-block` | Code diff block — highlights `+` additions and `-` removals     |
+| `terminal`   | macOS-style terminal window with traffic lights and typed lines |
+
+### Math
+
+| Component         | Description                                                                                                 |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- |
+| `math`            | LaTeX math via KaTeX — block and inline                                                                     |
+| `math-primitives` | 150+ JSX math primitives — Frac, Pow, Integral, Sum, Greek, trig, logic and more. No LaTeX engine required. |
+| `math-equation`   | Display equation containers — centered block with optional equation number                                  |
+| `math-solution`   | Step-by-step solution blocks — SolutionStep, SolutionAnswer, SolutionNote                                   |
+
+### Data & Tables
+
+| Component          | Description                                                           |
+| ------------------ | --------------------------------------------------------------------- |
+| `complexity-table` | Time and space complexity table for algorithm operations              |
+| `data-table`       | Dynamic table — accepts columns and data as props                     |
+| `data-type-table`  | AI/ML numeric data type and tensor specification table                |
+| `hardware-spec`    | Hardware interface spec card — type, version, speed, voltage, pins    |
+| `pin-table`        | Hardware pinout table — signal name, direction, voltage, alt function |
+| `privacy-table`    | Personal data documentation — purpose, legal basis, retention         |
+| `register-map`     | Hardware register/OTP fuse map — address, bits, access type, reset    |
+| `table`            | Table with header, body, footer, caption                              |
+
+### Diagrams & Visualization
+
+| Component | Description                                                                        |
+| --------- | ---------------------------------------------------------------------------------- |
+| `ds`      | Data structure visualizations — Array, LinkedList, Stack, Queue, Tree, Graph, etc. |
+| `ds-tree` | SVG tree visualizer — BST, AVL, Heap, N-ary with traversal animations              |
+| `mermaid` | Mermaid diagrams — flowcharts, sequences, etc.                                     |
+
+### SEO & Metadata
+
+| Component | Description                                                |
+| --------- | ---------------------------------------------------------- |
+| `json-ld` | JSON-LD structured data — Article, BreadcrumbList, FAQPage |
+
+### Navigation
+
+| Component   | Description                          |
+| ----------- | ------------------------------------ |
+| `file-tree` | Simple string-based file/folder tree |
+| `tree`      | Interactive file/folder tree         |
+
+### Certification & Compliance
+
+| Component             | Description                                                  |
+| --------------------- | ------------------------------------------------------------ |
+| `certification-badge` | ISO, TISAX, SOC 2 certification chips with status indicators |
+
+### Media
+
+| Component | Description                                                       |
+| --------- | ----------------------------------------------------------------- |
+| `video`   | Video embed — auto-detects YouTube, Vimeo, and HTML5 with caption |
+
+### Utilities
+
+| Component        | Description                            |
+| ---------------- | -------------------------------------- |
+| `mdx-components` | Auto-wired MDX component mapper        |
+| `utils`          | `cn()` utility (clsx + tailwind-merge) |
+
+## Math Primitives
+
+`math-primitives` is the single math system in mdx-ui — 150+ JSX components with no LaTeX engine required:
+
+```bash
+npx docsui-cli@latest add math-primitives
+```
+
+```mdx
+{/* Fraction */}
+
+<Frac num="a" den="b" />
+
+{/* Integral with bounds */}
+
+<Integral from="a" to="b">
+  f(x) dx
+</Integral>
+
+{/* Compose multiple elements */}
+
+<Frac
+  num={
+    <Expr>
+      x <Pow exp="2">dx</Pow>
+    </Expr>
+  }
+  den={<Pow exp="2">dy</Pow>}
+/>
+```
+
+Key components: `Expr` (composition), `Frac`, `Pow`, `Sub`, `Sqrt`, `Integral`, `Sum`, `Prod`, `Lim`, `Deriv`, `PDeriv`, `Brace`, `Paren`, full Greek alphabet, trig functions, logic symbols, and more.
+
+## Syntax Highlighting
+
+`code-block` integrates with `rehype-pretty-code` and Shiki for accurate, dual-theme syntax highlighting.
+
+```bash
+npm install rehype-pretty-code shiki
+```
+
+```ts
+// next.config.ts
+import rehypePrettyCode from "rehype-pretty-code";
+
+const withMDX = createMDX({
+  options: {
+    rehypePlugins: [
+      [
+        rehypePrettyCode,
+        {
+          theme: { light: "github-light-default", dark: "github-dark-default" },
+          defaultColor: false,
+        },
+      ],
+    ],
+  },
+});
+```
+
+Map `pre` to `CodeBlock` in your MDX components:
+
+```tsx
+import { CodeBlock } from "@/components/mdx/code-block";
+const components = { pre: CodeBlock };
+```
+
+The required CSS is automatically injected by `npx docsui-cli@latest init`.
+
+## Framework Support
+
+| Framework              | Status |
+| ---------------------- | ------ |
+| Next.js (App Router)   | ✓      |
+| Next.js (Pages Router) | ✓      |
+| Vite React             | ✓      |
+| Astro                  | ✓      |
+| Tailwind v3            | ✓      |
+| Tailwind v4            | ✓      |
+
+## Example `docsui.json`
+
+```json
+{
+  "componentsDir": "src/components/mdx",
+  "framework": "nextjs"
+}
+```
+
+## Links
+
+- **Documentation**: [GitHub](https://github.com/suryaravikumar-space/mdx-ui)
+- **Issues**: [GitHub Issues](https://github.com/suryaravikumar-space/mdx-ui/issues)
+- **npm**: [docsui](https://www.npmjs.com/package/docsui-cli)
+
+## License
+
+MIT

package/dist/commands/add.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare const add: Command;
+
+export { add };

package/dist/commands/add.js

@@ -0,0 +1,254 @@
+import { Command } from "commander";
+import prompts from "prompts";
+import chalk from "chalk";
+import ora from "ora";
+import fs from "fs-extra";
+import path from "path";
+import { getConfig } from "../utils/get-config.js";
+import {
+  fetchComponent
+} from "../utils/fetch-component.js";
+import { installDependencies } from "../utils/install-deps.js";
+import { COMPONENT_MDX_MAP, REGISTRY } from "../lib/component-registry.js";
+import { scanMdxComponents, printScanWarnings } from "../utils/scan-mdx.js";
+import { ping } from "../utils/telemetry.js";
+async function findMdxComponentsFile(componentsDir, cwd) {
+  const candidates = [
+    path.join(cwd, componentsDir, "mdx-components.tsx"),
+    path.join(cwd, componentsDir, "mdx-components.jsx"),
+    // common fallbacks in case init used a different dir than the actual file
+    path.join(cwd, "src/components/mdx-components.tsx"),
+    path.join(cwd, "src/components/mdx-components.jsx"),
+    path.join(cwd, "components/mdx-components.tsx"),
+    path.join(cwd, "components/mdx-components.jsx"),
+    path.join(cwd, "src/mdx-components.tsx"),
+    path.join(cwd, "src/mdx-components.jsx")
+  ];
+  for (const p of candidates) {
+    if (await fs.pathExists(p)) return p;
+  }
+  return null;
+}
+async function patchMdxComponents(componentName, componentsDir, cwd) {
+  const mapping = COMPONENT_MDX_MAP[componentName];
+  if (!mapping) return { patched: false, mdxPath: "" };
+  if (mapping.imports.length === 0 && Object.keys(mapping.elementMappings).length === 0)
+    return { patched: false, mdxPath: "" };
+  let mdxPath = await findMdxComponentsFile(componentsDir, cwd);
+  if (!mdxPath) {
+    mdxPath = path.join(cwd, componentsDir, "mdx-components.tsx");
+    await fs.ensureDir(path.dirname(mdxPath));
+    await fs.writeFile(mdxPath, `export const mdxComponents = {
+}
+`);
+  }
+  let content = await fs.readFile(mdxPath, "utf-8");
+  if (!content.includes(mapping.importFile)) {
+    const importLine = `import { ${mapping.imports.join(", ")} } from "${mapping.importFile}"
+`;
+    const exportIdx = content.indexOf("export const mdxComponents");
+    if (exportIdx !== -1) {
+      content = content.slice(0, exportIdx) + importLine + content.slice(exportIdx);
+    } else {
+      content = importLine + content;
+    }
+  }
+  const ANCHOR = "export const mdxComponents";
+  const anchorIdx = content.indexOf(ANCHOR);
+  const openBrace = anchorIdx !== -1 ? content.indexOf("{", anchorIdx) : -1;
+  let closeIdx = -1;
+  if (openBrace !== -1) {
+    let depth = 0;
+    for (let i = openBrace; i < content.length; i++) {
+      if (content[i] === "{") depth++;
+      else if (content[i] === "}") {
+        depth--;
+        if (depth === 0) {
+          closeIdx = i;
+          break;
+        }
+      }
+    }
+  }
+  const objectBody = openBrace !== -1 && closeIdx !== -1 ? content.slice(openBrace + 1, closeIdx) : "";
+  const additions = [];
+  for (const [element, component] of Object.entries(mapping.elementMappings)) {
+    if (!objectBody.includes(`${element}:`) && !objectBody.includes(`${element} :`)) {
+      additions.push(`  ${element}: ${component},`);
+    }
+  }
+  for (const exportName of mapping.imports) {
+    const alreadyMapped = Object.values(mapping.elementMappings).includes(
+      exportName
+    );
+    if (!alreadyMapped && !objectBody.includes(`${exportName},`) && !objectBody.includes(`${exportName}:`)) {
+      additions.push(`  ${exportName},`);
+    }
+  }
+  if (additions.length > 0 && closeIdx !== -1) {
+    content = content.slice(0, closeIdx) + additions.join("\n") + "\n" + content.slice(closeIdx);
+  }
+  await fs.writeFile(mdxPath, content);
+  return { patched: true, mdxPath };
+}
+function loadRegistry() {
+  return {
+    components: Object.entries(REGISTRY).filter(([name]) => name !== "utils").map(([name, entry]) => ({
+      name,
+      type: "mdx",
+      description: entry.description,
+      files: entry.files
+    }))
+  };
+}
+const add = new Command().name("add").description("Add components to your project").argument("[components...]", "components to add").option(
+  "-o, --overwrite",
+  "overwrite existing files without prompting",
+  false
+).option("-a, --all", "add all available components", false).action(
+  async (components, opts) => {
+    console.log();
+    const config = await getConfig();
+    if (!config) {
+      console.log(chalk.red("\u2717 No docsui.json found"));
+      console.log(chalk.yellow("Run 'npx docsui-cli@latest init' first"));
+      process.exit(1);
+    }
+    if (opts.all) {
+      const registry = loadRegistry();
+      components = registry.components.filter((c) => c.type === "mdx").map((c) => c.name);
+      console.log(
+        chalk.dim(`Adding all ${components.length} components...
+`)
+      );
+    } else if (components.length === 0) {
+      const registry = loadRegistry();
+      const mdxComponents = registry.components.filter(
+        (c) => c.type === "mdx"
+      );
+      const { selected } = await prompts({
+        type: "multiselect",
+        name: "selected",
+        message: "Which components would you like to add?",
+        choices: mdxComponents.map((c) => ({
+          title: c.name.split("-").map(
+            (word) => word.charAt(0).toUpperCase() + word.slice(1)
+          ).join(" "),
+          value: c.name,
+          description: c.description
+        }))
+      });
+      components = selected;
+    }
+    if (!components || components.length === 0) {
+      console.log(chalk.yellow("No components selected"));
+      process.exit(0);
+    }
+    const spinner = ora("Fetching components...").start();
+    try {
+      const componentsData = [];
+      const processedComponents = /* @__PURE__ */ new Set();
+      async function fetchComponentRecursive(componentName) {
+        if (processedComponents.has(componentName)) return;
+        processedComponents.add(componentName);
+        const data = await fetchComponent(componentName);
+        if (data.registryDependencies && data.registryDependencies.length > 0) {
+          for (const depName of data.registryDependencies) {
+            await fetchComponentRecursive(depName);
+          }
+        }
+        componentsData.push(data);
+      }
+      for (const component of components) {
+        await fetchComponentRecursive(component);
+      }
+      spinner.text = "Installing dependencies...";
+      const allDeps = /* @__PURE__ */ new Set();
+      for (const data of componentsData) {
+        data.dependencies?.forEach((dep) => allDeps.add(dep));
+      }
+      if (allDeps.size > 0) {
+        await installDependencies(Array.from(allDeps));
+      }
+      spinner.stop();
+      const cwd = process.cwd();
+      const framework = config.framework ?? "unknown";
+      const written = [];
+      const skipped = [];
+      for (const data of componentsData) {
+        for (const file of data.files) {
+          const libRoot = config.componentsDir.startsWith("src/") ? path.join(cwd, "src") : cwd;
+          const filePath = file.path.startsWith("lib/") ? path.join(libRoot, file.path) : path.join(cwd, config.componentsDir, file.path);
+          if (!path.resolve(filePath).startsWith(path.resolve(cwd) + path.sep)) {
+            throw new Error(
+              `Refusing to write outside project root: ${file.path}`
+            );
+          }
+          let incoming = file.content;
+          if (framework === "react") {
+            incoming = incoming.replace(/^["']use client["']\n\n?/m, "");
+          }
+          const exists = await fs.pathExists(filePath);
+          if (exists) {
+            const existing = await fs.readFile(filePath, "utf-8");
+            if (existing.trim() === incoming.trim()) {
+              skipped.push(file.path);
+              continue;
+            }
+            if (!opts.overwrite) {
+              const { overwrite } = await prompts({
+                type: "confirm",
+                name: "overwrite",
+                message: `${chalk.yellow(file.path)} already exists and has local changes. Overwrite?`,
+                initial: false
+              });
+              if (!overwrite) {
+                skipped.push(file.path);
+                continue;
+              }
+            }
+          }
+          await fs.ensureDir(path.dirname(filePath));
+          await fs.writeFile(filePath, incoming, "utf-8");
+          written.push(file.path);
+        }
+      }
+      let patchedFile = "";
+      for (const data of componentsData) {
+        const result = await patchMdxComponents(
+          data.name,
+          config.componentsDir,
+          cwd
+        );
+        if (result.patched && !patchedFile) {
+          patchedFile = path.relative(cwd, result.mdxPath);
+        }
+      }
+      console.log();
+      for (const component of components) {
+        console.log(chalk.green(`\u2713 ${component}`));
+      }
+      if (skipped.length > 0) {
+        console.log(chalk.dim(`  skipped: ${skipped.join(", ")}`));
+      }
+      if (patchedFile) {
+        console.log(chalk.dim(`  updated: ${patchedFile}`));
+      }
+      console.log();
+      console.log(chalk.bold("Done! \u{1F389}"));
+      console.log();
+      ping("add", { components });
+      const pm = await fs.pathExists(path.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : await fs.pathExists(path.join(cwd, "yarn.lock")) ? "yarn" : "npm";
+      const scanResults = await scanMdxComponents(cwd);
+      printScanWarnings(scanResults, pm);
+    } catch (error) {
+      spinner.fail("Failed to add components");
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error(chalk.red(msg));
+      process.exit(1);
+    }
+  }
+);
+export {
+  add
+};

package/dist/commands/doctor.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare const doctor: Command;
+
+export { doctor };