docsui-cli 0.0.59

package/dist/utils/detect-structure.d.ts

@@ -0,0 +1,16 @@
+type Framework = "nextjs" | "astro" | "react" | "unknown";
+type MdxPipeline = "contentlayer" | "next-mdx-remote" | "next-mdx" | "astro-mdx" | "mdx-rollup" | "unknown";
+interface ProjectStructure {
+    hasSrc: boolean;
+    componentsDir: string;
+    libDir: string;
+    framework: Framework;
+    mdxPipeline: MdxPipeline;
+    hasTypeScript: boolean;
+    hasTailwind: boolean;
+}
+declare function detectProjectStructure(cwd?: string): Promise<ProjectStructure>;
+declare function detectMdxPipeline(cwd: string): Promise<MdxPipeline>;
+declare function detectFramework(cwd: string): Promise<Framework>;
+
+export { type Framework, type MdxPipeline, type ProjectStructure, detectFramework, detectMdxPipeline, detectProjectStructure };

package/dist/utils/detect-structure.js

@@ -0,0 +1,58 @@
+import fs from "fs-extra";
+import path from "path";
+async function detectProjectStructure(cwd = process.cwd()) {
+  const srcExists = await fs.pathExists(path.join(cwd, "src"));
+  const framework = await detectFramework(cwd);
+  const mdxPipeline = await detectMdxPipeline(cwd);
+  const hasTypeScript = await fs.pathExists(path.join(cwd, "tsconfig.json"));
+  const hasTailwind = await fs.pathExists(path.join(cwd, "tailwind.config.js")) || await fs.pathExists(path.join(cwd, "tailwind.config.ts")) || await fs.pathExists(path.join(cwd, "tailwind.config.mjs"));
+  if (framework === "astro" || srcExists) {
+    return {
+      hasSrc: true,
+      componentsDir: "src/components/docsui",
+      libDir: "src/lib",
+      framework,
+      mdxPipeline,
+      hasTypeScript,
+      hasTailwind
+    };
+  }
+  return {
+    hasSrc: false,
+    componentsDir: "components/docsui",
+    libDir: "lib",
+    framework,
+    mdxPipeline,
+    hasTypeScript,
+    hasTailwind
+  };
+}
+async function detectMdxPipeline(cwd) {
+  try {
+    const pkg = await fs.readJSON(path.join(cwd, "package.json"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if ("contentlayer" in deps || "next-contentlayer" in deps || "contentlayer2" in deps || "next-contentlayer2" in deps)
+      return "contentlayer";
+    if ("next-mdx-remote" in deps) return "next-mdx-remote";
+    if ("@next/mdx" in deps) return "next-mdx";
+    if ("@astrojs/mdx" in deps) return "astro-mdx";
+    if ("@mdx-js/rollup" in deps) return "mdx-rollup";
+  } catch {
+  }
+  return "unknown";
+}
+async function detectFramework(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!await fs.pathExists(pkgPath)) return "unknown";
+  const pkg = await fs.readJSON(pkgPath);
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if ("next" in deps) return "nextjs";
+  if ("astro" in deps) return "astro";
+  if ("react" in deps || "react-dom" in deps) return "react";
+  return "unknown";
+}
+export {
+  detectFramework,
+  detectMdxPipeline,
+  detectProjectStructure
+};

package/dist/utils/fetch-component.d.ts

@@ -0,0 +1,13 @@
+interface ComponentData {
+    name: string;
+    files: Array<{
+        path: string;
+        content: string;
+        integrity?: string;
+    }>;
+    dependencies?: string[];
+    registryDependencies?: string[];
+}
+declare function fetchComponent(name: string): Promise<ComponentData>;
+
+export { type ComponentData, fetchComponent };

package/dist/utils/fetch-component.js

@@ -0,0 +1,81 @@
+import axios from "axios";
+import fs from "fs-extra";
+import path from "path";
+import { readFileSync } from "fs";
+import { createHash } from "crypto";
+import { fileURLToPath } from "url";
+const REGISTRY_BASE = "https://raw.githubusercontent.com/suryaravikumar-space/mdx-ui";
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+function getCliVersion() {
+  try {
+    const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(path.join(__dirname2, "../../package.json"), "utf-8")
+    );
+    const v = pkg.version;
+    return typeof v === "string" && SEMVER_RE.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+const CLI_VERSION = getCliVersion();
+function verifyIntegrity(data) {
+  for (const file of data.files) {
+    if (!file.integrity) continue;
+    const [algo, expected] = file.integrity.split("-");
+    if (algo !== "sha256") continue;
+    const actual = createHash("sha256").update(file.content).digest("base64");
+    if (actual !== expected) {
+      throw new Error(
+        `Integrity check failed for "${file.path}" in component "${data.name}". The registry may be compromised. Aborting.`
+      );
+    }
+  }
+}
+async function fetchComponent(name) {
+  try {
+    const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
+    const possiblePaths = [
+      path.join(__dirname2, "../../../../registry/mdx", `${name}.json`),
+      path.join(__dirname2, "../../../registry/mdx", `${name}.json`),
+      path.join(__dirname2, "../../registry/mdx", `${name}.json`)
+    ];
+    for (const registryPath of possiblePaths) {
+      if (await fs.pathExists(registryPath)) {
+        return await fs.readJSON(registryPath);
+      }
+    }
+  } catch {
+  }
+  const candidates = [];
+  if (CLI_VERSION) {
+    candidates.push(
+      `${REGISTRY_BASE}/v${CLI_VERSION}/registry/mdx/${name}.json`
+    );
+  }
+  candidates.push(`${REGISTRY_BASE}/main/registry/mdx/${name}.json`);
+  for (let i = 0; i < candidates.length; i++) {
+    const url = candidates[i];
+    const isLast = i === candidates.length - 1;
+    try {
+      const response = await axios.get(url);
+      const data = response.data;
+      verifyIntegrity(data);
+      return data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404) {
+        if (!isLast) continue;
+        throw new Error(
+          `Component "${name}" not found. Run: npx docsui-cli@latest list`
+        );
+      }
+      throw new Error(
+        `Could not fetch "${name}" \u2014 check your internet connection`
+      );
+    }
+  }
+  throw new Error(`Could not fetch "${name}" \u2014 check your internet connection`);
+}
+export {
+  fetchComponent
+};

package/dist/utils/get-config.d.ts

@@ -0,0 +1,14 @@
+import { Framework, MdxPipeline } from './detect-structure.js';
+
+interface Config {
+    componentsDir: string;
+    typescript: boolean;
+    tailwind: boolean;
+    framework?: Framework;
+    mdxPipeline?: MdxPipeline;
+    cssFile?: string;
+    tailwindConfig?: string;
+}
+declare function getConfig(): Promise<Config | null>;
+
+export { type Config, getConfig };

package/dist/utils/get-config.js

@@ -0,0 +1,19 @@
+import fs from "fs-extra";
+import path from "path";
+async function getConfig() {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, "docsui.json");
+  try {
+    const exists = await fs.pathExists(configPath);
+    if (!exists) {
+      return null;
+    }
+    const config = await fs.readJSON(configPath);
+    return config;
+  } catch {
+    return null;
+  }
+}
+export {
+  getConfig
+};

package/dist/utils/install-deps.d.ts

@@ -0,0 +1,3 @@
+declare function installDependencies(deps: string[]): Promise<void>;
+
+export { installDependencies };

package/dist/utils/install-deps.js

@@ -0,0 +1,23 @@
+import { execa } from "execa";
+async function installDependencies(deps) {
+  if (deps.length === 0) return;
+  const packageManager = await detectPackageManager();
+  const args = packageManager === "npm" ? ["install", ...deps] : ["add", ...deps];
+  await execa(packageManager, args, {
+    cwd: process.cwd()
+  });
+}
+async function detectPackageManager() {
+  const { stdout } = await execa("which", ["pnpm"], {
+    reject: false
+  });
+  if (stdout) return "pnpm";
+  const { stdout: yarnStdout } = await execa("which", ["yarn"], {
+    reject: false
+  });
+  if (yarnStdout) return "yarn";
+  return "npm";
+}
+export {
+  installDependencies
+};

package/dist/utils/save-mdx-page.d.ts

@@ -0,0 +1,35 @@
+interface SaveMdxPageOptions {
+    /** The MDX string to write */
+    content: string;
+    /** Root output folder — e.g. "content", "docs", "src/content" */
+    outDir: string;
+    /**
+     * Ordered path segments.
+     * Every item except the last becomes a folder.
+     * The last item becomes the filename (`.ai.mdx` is appended automatically).
+     *
+     * @example
+     * path: ["2025", "data-structures", "binary-search-trees", "introduction"]
+     * // writes to: <outDir>/2025/data-structures/binary-search-trees/introduction.ai.mdx
+     *
+     * @example
+     * path: ["lecture-1"]
+     * // writes to: <outDir>/lecture-1.ai.mdx
+     */
+    path: string[];
+}
+interface SaveMdxPageResult {
+    /** Absolute path of the written file */
+    filePath: string;
+    /** Path relative to process.cwd() */
+    relativePath: string;
+}
+/**
+ * Write an MDX string to a fully dynamic folder structure.
+ *
+ * No assumptions about segment names, year, subject, or depth.
+ * The caller owns the structure entirely via the `path` array.
+ */
+declare function saveMdxPage(options: SaveMdxPageOptions): Promise<SaveMdxPageResult>;
+
+export { type SaveMdxPageOptions, type SaveMdxPageResult, saveMdxPage };

package/dist/utils/save-mdx-page.js

@@ -0,0 +1,44 @@
+import fs from "fs-extra";
+import path from "path";
+async function saveMdxPage(options) {
+  const { content, outDir, path: segments } = options;
+  if (!content || content.trim() === "") {
+    throw new Error("saveMdxPage: content must not be empty");
+  }
+  if (!outDir || outDir.trim() === "") {
+    throw new Error("saveMdxPage: outDir must not be empty");
+  }
+  if (!segments || segments.length === 0) {
+    throw new Error("saveMdxPage: path must have at least one segment");
+  }
+  for (const segment of segments) {
+    if (!segment || segment.trim() === "") {
+      throw new Error("saveMdxPage: path segments must not be empty strings");
+    }
+    if (path.isAbsolute(segment)) {
+      throw new Error(
+        `saveMdxPage: path segment "${segment}" must not be absolute`
+      );
+    }
+    if (segment.includes("..")) {
+      throw new Error(
+        `saveMdxPage: path segment "${segment}" must not contain ".."`
+      );
+    }
+  }
+  const folders = segments.slice(0, -1);
+  const rawName = segments[segments.length - 1];
+  const baseName = rawName.replace(/\.[^.]+$/, "");
+  const fileName = `${baseName}.ai.mdx`;
+  const cwd = process.cwd();
+  const absoluteOutDir = path.isAbsolute(outDir) ? outDir : path.join(cwd, outDir);
+  const targetDir = path.join(absoluteOutDir, ...folders);
+  const filePath = path.join(targetDir, fileName);
+  await fs.ensureDir(targetDir);
+  await fs.writeFile(filePath, content, "utf-8");
+  const relativePath = path.relative(cwd, filePath);
+  return { filePath, relativePath };
+}
+export {
+  saveMdxPage
+};

package/dist/utils/scan-mdx.d.ts

@@ -0,0 +1,20 @@
+declare function extractComponentNames(content: string): Set<string>;
+declare function extractRegistered(mdxComponentsSource: string): Set<string>;
+interface ScanResult {
+    file: string;
+    missing: Array<{
+        name: string;
+        installAs: string;
+    }>;
+}
+/**
+ * Scan all .mdx files under cwd for unregistered components.
+ * Returns results and prints warnings to the console.
+ */
+declare function scanMdxComponents(cwd: string): Promise<ScanResult[]>;
+/**
+ * Print scan results as warnings with install commands.
+ */
+declare function printScanWarnings(results: ScanResult[], pm?: string): void;
+
+export { type ScanResult, extractComponentNames, extractRegistered, printScanWarnings, scanMdxComponents };

package/dist/utils/scan-mdx.js

@@ -0,0 +1,106 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+import { glob } from "glob";
+function extractComponentNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  const tagRe = /<([A-Z][a-zA-Z0-9]*)/g;
+  const stripped = content.replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "");
+  let m;
+  while ((m = tagRe.exec(stripped)) !== null) {
+    names.add(m[1]);
+  }
+  return names;
+}
+function extractRegistered(mdxComponentsSource) {
+  const names = /* @__PURE__ */ new Set();
+  const importRe = /import\s*\{([^}]+)\}/g;
+  let m;
+  while ((m = importRe.exec(mdxComponentsSource)) !== null) {
+    m[1].split(",").forEach((s) => {
+      const name = s.trim().split(/\s+as\s+/).pop()?.trim();
+      if (name && /^[A-Z]/.test(name)) names.add(name);
+    });
+  }
+  const mapRe = /:\s*([A-Z][a-zA-Z0-9]*)/g;
+  while ((m = mapRe.exec(mdxComponentsSource)) !== null) {
+    names.add(m[1]);
+  }
+  return names;
+}
+const IGNORE = /* @__PURE__ */ new Set([
+  "Fragment",
+  "React",
+  "StrictMode",
+  "Suspense",
+  "ErrorBoundary"
+]);
+async function scanMdxComponents(cwd) {
+  const candidates = [
+    "src/components/docsui/mdx-components.tsx",
+    "src/components/mdx-components.tsx",
+    "components/docsui/mdx-components.tsx",
+    "components/mdx-components.tsx"
+  ];
+  let mdxComponentsPath = "";
+  for (const c of candidates) {
+    const full = path.join(cwd, c);
+    if (fs.existsSync(full)) {
+      mdxComponentsPath = full;
+      break;
+    }
+  }
+  const registered = mdxComponentsPath ? extractRegistered(fs.readFileSync(mdxComponentsPath, "utf-8")) : /* @__PURE__ */ new Set();
+  const mdxFiles = await glob("**/*.mdx", {
+    cwd,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/.next/**"],
+    absolute: true
+  });
+  if (mdxFiles.length === 0) return [];
+  const results = [];
+  for (const file of mdxFiles) {
+    const content = fs.readFileSync(file, "utf-8");
+    const used = extractComponentNames(content);
+    const missing = [];
+    for (const name of used) {
+      if (IGNORE.has(name)) continue;
+      if (registered.has(name)) continue;
+      const installAs = name.replace(/([A-Z])/g, (m, c, i) => i === 0 ? c : `-${c}`).toLowerCase();
+      missing.push({ name, installAs });
+    }
+    if (missing.length > 0) {
+      results.push({ file: path.relative(cwd, file), missing });
+    }
+  }
+  return results;
+}
+function printScanWarnings(results, pm = "pnpm") {
+  if (results.length === 0) return;
+  const allMissing = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    for (const m of r.missing) allMissing.set(m.name, m.installAs);
+  }
+  console.log("");
+  console.log(chalk.yellow("\u26A0 Unregistered components found in MDX files:\n"));
+  for (const { file, missing } of results) {
+    for (const { name } of missing) {
+      console.log(
+        `  ${chalk.dim(file)} \u2192 ${chalk.cyan(`<${name}>`)} is not installed`
+      );
+    }
+  }
+  console.log("");
+  console.log(chalk.bold("Fix:"));
+  const dlx = pm === "pnpm" ? "pnpm dlx" : pm === "yarn" ? "yarn dlx" : "npx";
+  const installNames = [...allMissing.values()].join(" ");
+  console.log(
+    `  ${chalk.green(`${dlx} docsui add ${installNames}`)}`
+  );
+  console.log("");
+}
+export {
+  extractComponentNames,
+  extractRegistered,
+  printScanWarnings,
+  scanMdxComponents
+};

package/dist/utils/telemetry.d.ts

@@ -0,0 +1,3 @@
+declare function ping(event: string, data?: Record<string, unknown>): void;
+
+export { ping };

package/dist/utils/telemetry.js

@@ -0,0 +1,42 @@
+import { execSync } from "child_process";
+import { createHash } from "crypto";
+import os from "os";
+import axios from "axios";
+const POSTHOG_API_KEY = "phc_zNLMNdcFKJwLJqD6NK8uQwqSwXYYQfm6oAnga7sLQt6b";
+const POSTHOG_ENDPOINT = "https://app.posthog.com/capture/";
+const OWN_REPO = "suryaravikumar-space/mdx-ui";
+function getDistinctId() {
+  const raw = `${os.hostname()}:${os.userInfo().username}`;
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+function isOptedOut() {
+  return process.env.MDX_UI_NO_TELEMETRY === "1" || process.env.DO_NOT_TRACK === "1";
+}
+function isOwnMachine() {
+  try {
+    const remote = execSync("git remote get-url origin 2>/dev/null", {
+      timeout: 1500,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).toString().trim();
+    return remote.includes(OWN_REPO);
+  } catch {
+    return false;
+  }
+}
+function ping(event, data) {
+  if (isOptedOut() || isOwnMachine()) return;
+  axios.post(
+    POSTHOG_ENDPOINT,
+    {
+      api_key: POSTHOG_API_KEY,
+      event,
+      distinct_id: getDistinctId(),
+      properties: { ...data, $lib: "docsui-cli" }
+    },
+    { timeout: 3e3 }
+  ).catch(() => {
+  });
+}
+export {
+  ping
+};

package/dist/utils/write-component.d.ts

@@ -0,0 +1,7 @@
+import { Config } from './get-config.js';
+import { ComponentData } from './fetch-component.js';
+import './detect-structure.js';
+
+declare function writeComponent(component: ComponentData, config: Config): Promise<void>;
+
+export { writeComponent };

package/dist/utils/write-component.js

@@ -0,0 +1,25 @@
+import fs from "fs-extra";
+import path from "path";
+function resolveFilePath(filePath, componentsDir, cwd) {
+  if (filePath.startsWith("lib/")) {
+    const libRoot = componentsDir.startsWith("src/") ? path.join(cwd, "src") : cwd;
+    return path.join(libRoot, filePath);
+  }
+  return path.join(cwd, componentsDir, filePath);
+}
+async function writeComponent(component, config) {
+  const cwd = process.cwd();
+  const framework = config.framework ?? "unknown";
+  for (const file of component.files) {
+    const filePath = resolveFilePath(file.path, config.componentsDir, cwd);
+    await fs.ensureDir(path.dirname(filePath));
+    let content = file.content;
+    if (framework === "react") {
+      content = content.replace(/^["']use client["']\n\n?/m, "");
+    }
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+}
+export {
+  writeComponent
+};