docsui-cli 0.0.59

package/dist/commands/new.d.ts

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

package/dist/commands/new.js

@@ -0,0 +1,113 @@
+import { Command } from "commander";
+import prompts from "prompts";
+import chalk from "chalk";
+import fs from "fs-extra";
+import path from "path";
+function slugify(title) {
+  return title.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function todayIso() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function buildTemplate(title, description) {
+  return `---
+title: "${title}"
+description: "${description}"
+date: ${todayIso()}
+---
+
+# ${title}
+
+<Callout>
+  Write your introduction here.
+</Callout>
+
+## Overview
+
+Your content goes here.
+
+## Key Concepts
+
+<Definition term="Term">
+  Define your key terms here using the Definition component.
+</Definition>
+
+## Summary
+
+<Callout variant="success">
+  Summarize what the reader has learned.
+</Callout>
+`;
+}
+const newCommand = new Command().name("new").description("Scaffold a new blank .mdx page with starter components").argument("[title]", "page title (will be slugified for the filename)").option("-o, --out <dir>", "output directory").option(
+  "-p, --path <segments...>",
+  "optional sub-path segments placed between --out and the filename"
+).action(
+  async (titleArg, opts) => {
+    console.log();
+    let title = titleArg;
+    if (!title) {
+      const res = await prompts({
+        type: "text",
+        name: "title",
+        message: "Page title",
+        validate: (v) => v.trim() ? true : "Title cannot be empty"
+      });
+      if (!res.title) process.exit(0);
+      title = res.title;
+    }
+    let outDir = opts.out;
+    if (!outDir) {
+      const res = await prompts({
+        type: "text",
+        name: "out",
+        message: "Output directory",
+        initial: "content"
+      });
+      if (res.out === void 0) process.exit(0);
+      outDir = res.out || "content";
+    }
+    const { description } = await prompts({
+      type: "text",
+      name: "description",
+      message: "Short description (optional)",
+      initial: ""
+    });
+    const slug = slugify(title);
+    const fileName = `${slug}.mdx`;
+    const segments = opts.path ?? [];
+    const cwd = process.cwd();
+    const absoluteOut = path.isAbsolute(outDir) ? outDir : path.join(cwd, outDir);
+    const targetDir = path.join(absoluteOut, ...segments);
+    const filePath = path.join(targetDir, fileName);
+    const relativePath = path.relative(cwd, filePath);
+    if (await fs.pathExists(filePath)) {
+      const { overwrite } = await prompts({
+        type: "confirm",
+        name: "overwrite",
+        message: `${relativePath} already exists. Overwrite?`,
+        initial: false
+      });
+      if (!overwrite) {
+        console.log(chalk.yellow("Cancelled."));
+        process.exit(0);
+      }
+    }
+    await fs.ensureDir(targetDir);
+    await fs.writeFile(
+      filePath,
+      buildTemplate(title, description || title),
+      "utf-8"
+    );
+    console.log();
+    console.log(`  ${chalk.green("\u2713")} ${chalk.bold(relativePath)}`);
+    console.log();
+    console.log(
+      chalk.dim("  Open the file and replace the placeholder content.")
+    );
+    console.log();
+  }
+);
+export {
+  newCommand
+};

package/dist/commands/remove.d.ts

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

package/dist/commands/remove.js

@@ -0,0 +1,134 @@
+import { Command } from "commander";
+import prompts from "prompts";
+import chalk from "chalk";
+import fs from "fs-extra";
+import path from "path";
+import { getConfig } from "../utils/get-config.js";
+import {
+  COMPONENT_MDX_MAP,
+  COMPONENT_FILES
+} from "../lib/component-registry.js";
+async function unpatchMdxComponents(componentName, componentsDir, cwd) {
+  const mapping = COMPONENT_MDX_MAP[componentName];
+  if (!mapping) return;
+  const mdxPath = path.join(cwd, componentsDir, "mdx-components.tsx");
+  if (!await fs.pathExists(mdxPath)) return;
+  let content = await fs.readFile(mdxPath, "utf-8");
+  const lines = content.split("\n");
+  content = lines.filter((line) => !line.includes(`from "${mapping.importFile}"`)).join("\n");
+  for (const [element, component] of Object.entries(mapping.elementMappings)) {
+    content = content.replace(
+      new RegExp(`
+[ 	]+${element}:\\s*${component},`, "g"),
+      ""
+    );
+  }
+  for (const exportName of mapping.imports) {
+    const alreadyMapped = Object.values(mapping.elementMappings).includes(
+      exportName
+    );
+    if (!alreadyMapped) {
+      content = content.replace(new RegExp(`
+[ 	]+${exportName},`, "g"), "");
+    }
+  }
+  await fs.writeFile(mdxPath, content, "utf-8");
+}
+async function discoverInstalled(componentsDir, cwd) {
+  const dir = path.join(cwd, componentsDir);
+  if (!await fs.pathExists(dir)) return [];
+  const files = await fs.readdir(dir);
+  const installed = [];
+  for (const [name, componentFiles] of Object.entries(COMPONENT_FILES)) {
+    const ownFiles = componentFiles.filter((f) => !f.startsWith("lib/"));
+    if (ownFiles.length > 0 && ownFiles.every((f) => files.includes(f)))
+      installed.push(name);
+  }
+  if (files.includes("mdx-components.tsx")) installed.push("mdx-components");
+  const libDir = componentsDir.startsWith("src/") ? "src/lib" : "lib";
+  if (await fs.pathExists(path.join(cwd, libDir, "utils.ts")))
+    installed.push("utils");
+  return [...new Set(installed)];
+}
+const remove = new Command().name("remove").description("Remove installed components from your project").argument("[components...]", "components to remove").action(async (components) => {
+  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\n"));
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  if (components.length === 0) {
+    const installed = await discoverInstalled(config.componentsDir, cwd);
+    if (installed.length === 0) {
+      console.log(chalk.yellow("No installed components found.\n"));
+      process.exit(0);
+    }
+    const { selected } = await prompts({
+      type: "multiselect",
+      name: "selected",
+      message: "Which components would you like to remove?",
+      choices: installed.map((name) => ({ title: name, value: name }))
+    });
+    if (!selected || selected.length === 0) {
+      console.log(chalk.yellow("Nothing selected.\n"));
+      process.exit(0);
+    }
+    components = selected;
+  }
+  const { confirmed } = await prompts({
+    type: "confirm",
+    name: "confirmed",
+    message: `Remove ${components.length} component${components.length !== 1 ? "s" : ""}? (${components.join(", ")})`,
+    initial: false
+  });
+  if (!confirmed) {
+    console.log(chalk.yellow("\nCancelled.\n"));
+    process.exit(0);
+  }
+  console.log();
+  const removed = [];
+  const notFound = [];
+  for (const name of components) {
+    const files = name === "mdx-components" ? ["mdx-components.tsx"] : COMPONENT_FILES[name];
+    if (!files) {
+      notFound.push(name);
+      continue;
+    }
+    let deleted = false;
+    const libRoot = config.componentsDir.startsWith("src/") ? path.join(cwd, "src") : cwd;
+    for (const file of files) {
+      const filePath = file.startsWith("lib/") ? path.join(libRoot, file) : path.join(cwd, config.componentsDir, file);
+      if (await fs.pathExists(filePath)) {
+        await fs.remove(filePath);
+        deleted = true;
+      }
+    }
+    await unpatchMdxComponents(name, config.componentsDir, cwd);
+    if (deleted) {
+      removed.push(name);
+      console.log(chalk.green(`  \u2713 removed ${name}`));
+    } else {
+      notFound.push(name);
+      console.log(chalk.dim(`  \u2013 ${name} (not installed)`));
+    }
+  }
+  console.log();
+  if (removed.length > 0) {
+    console.log(
+      chalk.bold(
+        `Removed ${removed.length} component${removed.length !== 1 ? "s" : ""}.`
+      )
+    );
+  }
+  if (notFound.length > 0) {
+    console.log(
+      chalk.yellow(`${notFound.length} not found: ${notFound.join(", ")}`)
+    );
+  }
+  console.log();
+});
+export {
+  remove
+};

package/dist/commands/save.d.ts

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

package/dist/commands/save.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import fs from "fs-extra";
+import { saveMdxPage } from "../utils/save-mdx-page.js";
+const save = new Command().name("save").description("Save an MDX string to a structured file path").requiredOption("-o, --out <dir>", "root output folder (e.g. content, docs)").requiredOption(
+  "-p, --path <segments...>",
+  "ordered path segments \u2014 all but the last become folders, last becomes filename"
+).option("-f, --file <file>", "read MDX content from a file instead of stdin").action(async (opts) => {
+  console.log();
+  let content;
+  if (opts.file) {
+    if (!await fs.pathExists(opts.file)) {
+      console.log(chalk.red(`\u2717 File not found: ${opts.file}`));
+      process.exit(1);
+    }
+    content = await fs.readFile(opts.file, "utf-8");
+  } else if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    content = Buffer.concat(chunks).toString("utf-8");
+  } else {
+    console.log(
+      chalk.red("\u2717 Provide MDX via --file or pipe it through stdin")
+    );
+    console.log();
+    console.log(chalk.dim("Examples:"));
+    console.log(
+      chalk.dim(
+        "  docsui save --out content --path 2025 ds bst intro --file page.mdx"
+      )
+    );
+    console.log(
+      chalk.dim(
+        "  echo '<Callout>Hello</Callout>' | docsui save --out content --path 2025 ds bst intro"
+      )
+    );
+    process.exit(1);
+  }
+  const spinner = ora("Writing MDX file\u2026").start();
+  try {
+    const result = await saveMdxPage({
+      content,
+      outDir: opts.out,
+      path: opts.path
+    });
+    spinner.succeed("MDX file saved");
+    console.log();
+    console.log(`  ${chalk.green("\u2713")} ${chalk.bold(result.relativePath)}`);
+    console.log();
+  } catch (error) {
+    spinner.fail("Failed to save MDX file");
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(msg));
+    process.exit(1);
+  }
+});
+export {
+  save
+};

package/dist/commands/update.d.ts

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

package/dist/commands/update.js

@@ -0,0 +1,247 @@
+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 { writeComponent } from "../utils/write-component.js";
+import {
+  FILE_TO_COMPONENT,
+  COMPONENT_MDX_MAP
+} from "../lib/component-registry.js";
+async function patchMdxComponents(componentName, componentsDir, cwd) {
+  const mapping = COMPONENT_MDX_MAP[componentName];
+  if (!mapping) return;
+  if (mapping.imports.length === 0 && Object.keys(mapping.elementMappings).length === 0)
+    return;
+  let mdxPath = path.join(cwd, componentsDir, "mdx-components.tsx");
+  if (!await fs.pathExists(mdxPath)) {
+    const jsxPath = path.join(cwd, componentsDir, "mdx-components.jsx");
+    if (await fs.pathExists(jsxPath)) mdxPath = jsxPath;
+    else return;
+  }
+  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");
+    content = exportIdx !== -1 ? content.slice(0, exportIdx) + importLine + content.slice(exportIdx) : 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);
+}
+async function diffComponent(data, config, cwd) {
+  const changedFiles = [];
+  const framework = config.framework ?? "unknown";
+  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 (!await fs.pathExists(filePath)) {
+      changedFiles.push(file.path);
+      continue;
+    }
+    const existing = await fs.readFile(filePath, "utf-8");
+    let incoming = file.content;
+    if (framework === "react") {
+      incoming = incoming.replace(/^["']use client["']\n\n?/m, "");
+    }
+    if (existing.trim() !== incoming.trim()) {
+      changedFiles.push(file.path);
+    }
+  }
+  return {
+    name: data.name,
+    data,
+    changedFiles,
+    hasChanges: changedFiles.length > 0
+  };
+}
+async function discoverInstalled(componentsDir, cwd) {
+  const dir = path.join(cwd, componentsDir);
+  if (!await fs.pathExists(dir)) return [];
+  const files = await fs.readdir(dir);
+  const found = files.map((f) => FILE_TO_COMPONENT[f]).filter((n) => !!n);
+  const libDir = componentsDir.startsWith("src/") ? "src/lib" : "lib";
+  if (await fs.pathExists(path.join(cwd, libDir, "utils.ts"))) {
+    found.unshift("utils");
+  }
+  return [...new Set(found)];
+}
+const update = new Command().name("update").description("Update installed components to their latest versions").argument(
+  "[components...]",
+  "components to update (omit to update all installed)"
+).action(async (targets) => {
+  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\n"));
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  let toUpdate;
+  if (targets.length > 0) {
+    toUpdate = targets;
+  } else {
+    toUpdate = await discoverInstalled(config.componentsDir, cwd);
+    if (toUpdate.length === 0) {
+      console.log(chalk.yellow("No installed components found."));
+      console.log(
+        chalk.dim("  Run: npx docsui-cli@latest add <component>\n")
+      );
+      process.exit(0);
+    }
+  }
+  const spinner = ora("Checking for updates...").start();
+  try {
+    const componentsData = [];
+    const processed = /* @__PURE__ */ new Set();
+    async function fetchRecursive(name) {
+      if (processed.has(name)) return;
+      processed.add(name);
+      const data = await fetchComponent(name);
+      if (data.registryDependencies?.length) {
+        for (const dep of data.registryDependencies) {
+          await fetchRecursive(dep);
+        }
+      }
+      componentsData.push(data);
+    }
+    for (const name of toUpdate) {
+      await fetchRecursive(name);
+    }
+    const diffs = await Promise.all(
+      componentsData.map((data) => diffComponent(data, config, cwd))
+    );
+    spinner.stop();
+    console.log();
+    const maxLen = Math.max(...diffs.map((d) => d.name.length));
+    for (const diff of diffs) {
+      const name = diff.name.padEnd(maxLen);
+      if (diff.hasChanges) {
+        console.log(
+          `  ${chalk.yellow("~")}  ${name}  ${chalk.dim(diff.changedFiles.join(", "))}`
+        );
+      } else {
+        console.log(
+          `  ${chalk.green("\u2713")}  ${name}  ${chalk.dim("up to date")}`
+        );
+      }
+    }
+    console.log();
+    const changed = diffs.filter((d) => d.hasChanges);
+    if (changed.length === 0) {
+      console.log(chalk.green("All components are up to date."));
+      console.log();
+      process.exit(0);
+    }
+    console.log(
+      chalk.bold(
+        `${changed.length} component${changed.length !== 1 ? "s have" : " has"} updates.`
+      )
+    );
+    console.log();
+    const { strategy } = await prompts({
+      type: "select",
+      name: "strategy",
+      message: "How would you like to proceed?",
+      choices: [
+        {
+          title: `Overwrite all  ${chalk.dim(`(${changed.length} component${changed.length !== 1 ? "s" : ""})`)}`,
+          value: "all"
+        },
+        { title: "Skip all", value: "skip" },
+        { title: "Choose which to update", value: "pick" }
+      ]
+    });
+    if (!strategy || strategy === "skip") {
+      console.log(chalk.yellow("\nSkipped. No files written.\n"));
+      process.exit(0);
+    }
+    let toWrite = [];
+    if (strategy === "all") {
+      toWrite = changed;
+    } else {
+      const { selected } = await prompts({
+        type: "multiselect",
+        name: "selected",
+        message: "Select components to update",
+        choices: changed.map((d) => ({
+          title: d.name,
+          value: d.name,
+          description: d.changedFiles.join(", "),
+          selected: true
+        }))
+      });
+      if (!selected || selected.length === 0) {
+        console.log(chalk.yellow("\nNothing selected. No files written.\n"));
+        process.exit(0);
+      }
+      toWrite = changed.filter((d) => selected.includes(d.name));
+    }
+    console.log();
+    const writeSpinner = ora("Installing dependencies...").start();
+    const allDeps = /* @__PURE__ */ new Set();
+    for (const diff of toWrite) {
+      diff.data.dependencies?.forEach((d) => allDeps.add(d));
+    }
+    if (allDeps.size > 0) await installDependencies(Array.from(allDeps));
+    writeSpinner.text = "Writing updated components...";
+    for (const diff of toWrite) {
+      await writeComponent(diff.data, config);
+      await patchMdxComponents(diff.name, config.componentsDir, cwd);
+    }
+    writeSpinner.succeed("Done!");
+    console.log();
+    for (const diff of toWrite) {
+      console.log(chalk.green(`  \u2713 ${diff.name}`));
+    }
+    console.log();
+  } catch (error) {
+    spinner.fail("Update failed");
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`  ${msg}
+`));
+    process.exit(1);
+  }
+});
+export {
+  update
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import prompts from "prompts";
+import { add } from "./commands/add.js";
+import { init } from "./commands/init.js";
+import { list } from "./commands/list.js";
+import { update } from "./commands/update.js";
+import { remove } from "./commands/remove.js";
+import { doctor } from "./commands/doctor.js";
+import { save } from "./commands/save.js";
+import { newCommand } from "./commands/new.js";
+import { startMcpServer } from "./commands/mcp.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf-8")
+);
+process.on("SIGINT", () => process.exit(0));
+process.on("SIGTERM", () => process.exit(0));
+async function main() {
+  if (process.argv[2] === "mcp") {
+    await startMcpServer();
+    return;
+  }
+  const program = new Command().name("docsui").description("Add beautiful MDX components to your project").version(
+    packageJson.version || "0.0.1",
+    "-v, --version",
+    "display the version number"
+  );
+  program.addCommand(init).addCommand(add).addCommand(list).addCommand(update).addCommand(remove).addCommand(doctor).addCommand(save).addCommand(newCommand);
+  if (process.argv.length <= 2) {
+    console.log();
+    const { action } = await prompts({
+      type: "select",
+      name: "action",
+      message: "What would you like to do?",
+      choices: [
+        {
+          title: "Add components",
+          value: "add",
+          description: "Add MDX components to your project"
+        },
+        {
+          title: "Update components",
+          value: "update",
+          description: "Update installed components to latest"
+        },
+        {
+          title: "Initialize project",
+          value: "init",
+          description: "Set up docsui in your project"
+        },
+        {
+          title: "Remove components",
+          value: "remove",
+          description: "Remove installed components from your project"
+        },
+        {
+          title: "List components",
+          value: "list",
+          description: "Show all available components"
+        },
+        {
+          title: "Doctor",
+          value: "doctor",
+          description: "Check project health \u2014 missing deps, broken imports"
+        },
+        {
+          title: "Save MDX",
+          value: "save",
+          description: "Save an MDX string to a structured .ai.mdx file"
+        },
+        {
+          title: "New page",
+          value: "new",
+          description: "Scaffold a new blank .mdx page with starter components"
+        }
+      ]
+    });
+    if (!action) process.exit(0);
+    process.argv.push(action);
+  }
+  program.parse();
+}
+main();