simplemdg-dev-cli 2.0.4 → 2.4.5

package/src/core/doctor.ts

@@ -0,0 +1,70 @@
+import path from "node:path";
+import fs from "fs-extra";
+import type { TDoctorPackageResult, TPackageOccurrence } from "./types";
+
+async function findPackageJsonFiles(startPath: string, packageName: string): Promise<string[]> {
+  const packagePathParts = packageName.startsWith("@") ? packageName.split("/") : [packageName];
+  const result: string[] = [];
+
+  async function walk(directoryPath: string, depth: number): Promise<void> {
+    if (depth > 8) {
+      return;
+    }
+
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true }).catch(() => []);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      if (entry.name === ".git") {
+        continue;
+      }
+
+      const entryPath = path.join(directoryPath, entry.name);
+
+      if (entry.name === "node_modules") {
+        const packageJsonPath = path.join(entryPath, ...packagePathParts, "package.json");
+
+        if (await fs.pathExists(packageJsonPath)) {
+          result.push(packageJsonPath);
+        }
+
+        await walk(entryPath, depth + 1);
+        continue;
+      }
+
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+
+      await walk(entryPath, depth + 1);
+    }
+  }
+
+  await walk(startPath, 0);
+  return result;
+}
+
+export async function doctorPackage(options: { repositoryPath: string; packageName: string }): Promise<TDoctorPackageResult> {
+  const packageJsonFiles = await findPackageJsonFiles(options.repositoryPath, options.packageName);
+  const occurrences: TPackageOccurrence[] = [];
+
+  for (const packageJsonFile of packageJsonFiles) {
+    const packageJson = await fs.readJson(packageJsonFile).catch(() => undefined) as { version?: string } | undefined;
+    occurrences.push({
+      version: packageJson?.version,
+      path: packageJsonFile,
+    });
+  }
+
+  const versions = [...new Set(occurrences.map((item) => item.version).filter((version): version is string => Boolean(version)))];
+
+  return {
+    packageName: options.packageName,
+    versions,
+    occurrences,
+    hasMultipleVersions: versions.length > 1,
+  };
+}

package/src/core/guide.ts

@@ -0,0 +1,261 @@
+import http from "node:http";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import fs from "fs-extra";
+import chalk from "chalk";
+import prompts from "prompts";
+
+const GUIDE_FILE_NAME = "USER_GUIDE.md";
+
+type TGuideMode = "terminal" | "web" | "commander-help";
+
+function getPackageRootPath(): string {
+  return path.resolve(__dirname, "..", "..");
+}
+
+async function readGuideMarkdown(): Promise<string> {
+  const packageRootPath = getPackageRootPath();
+  const guidePath = path.join(packageRootPath, GUIDE_FILE_NAME);
+
+  if (await fs.pathExists(guidePath)) {
+    return fs.readFile(guidePath, "utf8");
+  }
+
+  const readmePath = path.join(packageRootPath, "README.md");
+
+  if (await fs.pathExists(readmePath)) {
+    return fs.readFile(readmePath, "utf8");
+  }
+
+  return `# SimpleMDG Dev CLI\n\nGuide file was not found. Run smdg --help to see command help.`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+function inlineMarkdown(value: string): string {
+  return escapeHtml(value)
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+}
+
+function markdownToHtml(markdown: string): string {
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  const htmlLines: string[] = [];
+  let inCodeBlock = false;
+  let codeLines: string[] = [];
+  let inList = false;
+
+  function closeList(): void {
+    if (inList) {
+      htmlLines.push("</ul>");
+      inList = false;
+    }
+  }
+
+  function closeCodeBlock(): void {
+    if (inCodeBlock) {
+      htmlLines.push(`<pre><code>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
+      codeLines = [];
+      inCodeBlock = false;
+    }
+  }
+
+  for (const line of lines) {
+    if (line.trim().startsWith("```")) {
+      if (inCodeBlock) {
+        closeCodeBlock();
+      } else {
+        closeList();
+        inCodeBlock = true;
+        codeLines = [];
+      }
+      continue;
+    }
+
+    if (inCodeBlock) {
+      codeLines.push(line);
+      continue;
+    }
+
+    const trimmedLine = line.trim();
+
+    if (!trimmedLine) {
+      closeList();
+      continue;
+    }
+
+    const headingMatch = /^(#{1,4})\s+(.+)$/.exec(trimmedLine);
+    if (headingMatch) {
+      closeList();
+      const level = headingMatch[1].length;
+      htmlLines.push(`<h${level}>${inlineMarkdown(headingMatch[2])}</h${level}>`);
+      continue;
+    }
+
+    const bulletMatch = /^[-*]\s+(.+)$/.exec(trimmedLine);
+    if (bulletMatch) {
+      if (!inList) {
+        htmlLines.push("<ul>");
+        inList = true;
+      }
+      htmlLines.push(`<li>${inlineMarkdown(bulletMatch[1])}</li>`);
+      continue;
+    }
+
+    closeList();
+    htmlLines.push(`<p>${inlineMarkdown(trimmedLine)}</p>`);
+  }
+
+  closeCodeBlock();
+  closeList();
+
+  return htmlLines.join("\n");
+}
+
+function buildGuideHtml(markdown: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>SimpleMDG Dev CLI Guide</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body {
+      margin: 0;
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #0f172a;
+      color: #e5e7eb;
+      line-height: 1.65;
+    }
+    .layout {
+      max-width: 980px;
+      margin: 0 auto;
+      padding: 40px 24px 80px;
+    }
+    .card {
+      background: #111827;
+      border: 1px solid #334155;
+      border-radius: 18px;
+      padding: 28px;
+      box-shadow: 0 20px 50px rgba(0, 0, 0, 0.35);
+    }
+    h1 { margin-top: 0; font-size: 34px; color: #ffffff; }
+    h2 { margin-top: 36px; padding-top: 22px; border-top: 1px solid #334155; color: #93c5fd; }
+    h3 { color: #bfdbfe; }
+    p, li { color: #d1d5db; }
+    code {
+      background: #1f2937;
+      color: #fbbf24;
+      padding: 2px 6px;
+      border-radius: 6px;
+      font-size: 0.92em;
+    }
+    pre {
+      background: #020617;
+      color: #e5e7eb;
+      padding: 16px;
+      border-radius: 12px;
+      overflow-x: auto;
+      border: 1px solid #1e293b;
+    }
+    pre code { background: transparent; color: inherit; padding: 0; }
+    ul { padding-left: 24px; }
+    .hint {
+      margin-bottom: 18px;
+      padding: 12px 14px;
+      border-radius: 12px;
+      background: #172554;
+      color: #dbeafe;
+      border: 1px solid #1d4ed8;
+    }
+  </style>
+</head>
+<body>
+  <main class="layout">
+    <div class="hint">Local visual guide. Keep this terminal open. Press Ctrl + C to stop the guide server.</div>
+    <article class="card">
+      ${markdownToHtml(markdown)}
+    </article>
+  </main>
+</body>
+</html>`;
+}
+
+function openBrowser(url: string): void {
+  const platform = process.platform;
+
+  if (platform === "win32") {
+    spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+    return;
+  }
+
+  if (platform === "darwin") {
+    spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+    return;
+  }
+
+  spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+}
+
+export async function printUserGuide(): Promise<void> {
+  const markdown = await readGuideMarkdown();
+  console.log(markdown);
+}
+
+export async function openUserGuideInBrowser(port?: string): Promise<void> {
+  const markdown = await readGuideMarkdown();
+  const html = buildGuideHtml(markdown);
+  const requestedPort = port?.trim() ? Number(port.trim()) : 0;
+
+  if (port?.trim() && (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535)) {
+    throw new Error("Guide port must be a number from 1 to 65535");
+  }
+
+  const server = http.createServer((request, response) => {
+    if (request.url === "/" || request.url === "/index.html") {
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      response.end(html);
+      return;
+    }
+
+    response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+    response.end("Not found");
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(requestedPort, "127.0.0.1", () => resolve());
+  });
+
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : requestedPort;
+  const url = `http://127.0.0.1:${actualPort}`;
+
+  console.log(chalk.green(`SimpleMDG Dev CLI guide: ${url}`));
+  console.log(chalk.gray("Press Ctrl + C to stop the guide server."));
+  openBrowser(url);
+}
+
+export async function askRootHelpMode(): Promise<TGuideMode> {
+  const response = await prompts({
+    type: "select",
+    name: "mode",
+    message: "How do you want to view SimpleMDG CLI help?",
+    choices: [
+      { title: "View quick guide in terminal", value: "terminal" },
+      { title: "Open visual guide in browser", value: "web" },
+      { title: "Show command help", value: "commander-help" },
+    ],
+    initial: 0,
+  });
+
+  return (response.mode ?? "commander-help") as TGuideMode;
+}

package/src/core/install.ts

@@ -0,0 +1,91 @@
+import fs from "fs-extra";
+import fastGlob from "fast-glob";
+import { execa } from "execa";
+import { splitCommand } from "./process";
+import type { TInstallRepositoryOptions, TInstallRepositoryResult } from "./types";
+
+function replaceVariables(content: string, variableValues: Record<string, string>): string {
+  return content.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (fullMatch: string, variableName: string) => {
+    return variableValues[variableName] ?? fullMatch;
+  });
+}
+
+function mergePackageOverrides(packageJson: Record<string, unknown>, temporaryOverrides: Record<string, string>): Record<string, unknown> {
+  if (Object.keys(temporaryOverrides).length === 0) {
+    return packageJson;
+  }
+
+  const currentOverrides = typeof packageJson.overrides === "object" && packageJson.overrides !== null && !Array.isArray(packageJson.overrides)
+    ? packageJson.overrides as Record<string, unknown>
+    : {};
+
+  return {
+    ...packageJson,
+    overrides: {
+      ...currentOverrides,
+      ...temporaryOverrides,
+    },
+  };
+}
+
+export async function installRepository(options: TInstallRepositoryOptions): Promise<TInstallRepositoryResult> {
+  const filePaths = await fastGlob(options.filePatterns, {
+    cwd: options.repositoryPath,
+    absolute: true,
+    onlyFiles: true,
+    ignore: ["node_modules/**", "dist/**", ".git/**"],
+  });
+
+  const originalContents = new Map<string, string>();
+
+  try {
+    for (const filePath of filePaths) {
+      const originalContent = await fs.readFile(filePath, "utf8");
+      originalContents.set(filePath, originalContent);
+      let nextContent = replaceVariables(originalContent, options.variableValues);
+
+      if (filePath.endsWith("package.json")) {
+        const packageJson = JSON.parse(nextContent) as Record<string, unknown>;
+        nextContent = `${JSON.stringify(mergePackageOverrides(packageJson, options.temporaryOverrides), null, 2)}\n`;
+      }
+
+      if (nextContent !== originalContent) {
+        await fs.writeFile(filePath, nextContent, "utf8");
+      }
+    }
+
+    const { command, args } = splitCommand(options.installCommand);
+    const childProcess = execa(command, args, {
+      cwd: options.repositoryPath,
+      reject: false,
+      all: false,
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    childProcess.stdout?.on("data", (chunk: Buffer) => {
+      const value = chunk.toString();
+      stdout += value;
+      options.onLog?.(value);
+    });
+
+    childProcess.stderr?.on("data", (chunk: Buffer) => {
+      const value = chunk.toString();
+      stderr += value;
+      options.onErrorLog?.(value);
+    });
+
+    const result = await childProcess;
+
+    return {
+      stdout,
+      stderr,
+      exitCode: result.exitCode ?? 0,
+    };
+  } finally {
+    for (const [filePath, content] of originalContents.entries()) {
+      await fs.writeFile(filePath, content, "utf8");
+    }
+  }
+}

package/src/core/navigator.ts

@@ -0,0 +1,164 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { searchableSelectChoice } from "./prompts";
+
+const BACK_VALUE = "__SMDG_NAV_BACK__";
+const EXIT_VALUE = "__SMDG_NAV_EXIT__";
+
+// Commands that exist only for internal/background use and should never be
+// offered in the interactive menu.
+const INTERNAL_COMMAND_NAMES = new Set(["apps-cache-refresh"]);
+
+function isHidden(command: Command): boolean {
+  return Boolean((command as unknown as { _hidden?: boolean })._hidden);
+}
+
+function getNavigableChildren(command: Command): Command[] {
+  return command.commands.filter((child) => {
+    if (child.name() === "help") {
+      return false;
+    }
+
+    if (isHidden(child)) {
+      return false;
+    }
+
+    return !INTERNAL_COMMAND_NAMES.has(child.name());
+  });
+}
+
+function isGroup(command: Command): boolean {
+  return getNavigableChildren(command).length > 0;
+}
+
+function buildBreadcrumb(command: Command): string {
+  const names: string[] = [];
+  let current: Command | null | undefined = command;
+
+  while (current) {
+    names.unshift(current.name());
+    current = current.parent;
+  }
+
+  // The bin is published as `smdg`; show that shorter name in breadcrumbs.
+  if (names[0] === "simplemdg") {
+    names[0] = "smdg";
+  }
+
+  return names.join(" ");
+}
+
+function buildChoiceTitle(command: Command): string {
+  const aliases = command.aliases();
+  const aliasText = aliases.length ? chalk.gray(` (${aliases.join(", ")})`) : "";
+  const marker = isGroup(command) ? chalk.cyan(" ›") : "";
+  const description = command.description();
+  const descriptionText = description ? `  ${chalk.gray(`— ${description}`)}` : "";
+
+  return `${chalk.bold(command.name())}${aliasText}${marker}${descriptionText}`;
+}
+
+async function dispatchLeaf(leaf: Command): Promise<void> {
+  console.log(chalk.gray(`→ ${buildBreadcrumb(leaf)}`));
+  console.log("");
+  // Parsing the leaf with no user args runs its action with default options.
+  // Each leaf already prompts interactively for whatever it still needs.
+  await leaf.parseAsync([], { from: "user" });
+}
+
+/**
+ * Drive interactive navigation starting from a group command. Shows the list of
+ * subcommands, lets the user descend into nested groups, and finally runs the
+ * selected leaf command (which collects its own options interactively).
+ */
+export async function runGroupNavigator(startGroup: Command): Promise<void> {
+  const stack: Command[] = [startGroup];
+
+  while (stack.length > 0) {
+    const current = stack[stack.length - 1];
+    const children = getNavigableChildren(current);
+
+    if (children.length === 0) {
+      await dispatchLeaf(current);
+      return;
+    }
+
+    const choices = children.map((child) => ({
+      title: buildChoiceTitle(child),
+      value: child.name(),
+    }));
+
+    if (stack.length > 1) {
+      choices.push({ title: chalk.yellow("← Back"), value: BACK_VALUE });
+    }
+
+    choices.push({ title: chalk.gray("✕ Exit"), value: EXIT_VALUE });
+
+    let picked: string;
+
+    try {
+      picked = await searchableSelectChoice({
+        message: `${chalk.cyan(buildBreadcrumb(current))} — type to filter, then select`,
+        choices,
+        allowCustomValue: false,
+        limit: 20,
+      });
+    } catch {
+      // ESC / cancel: step back one level, or exit when at the top.
+      if (stack.length > 1) {
+        stack.pop();
+        continue;
+      }
+
+      return;
+    }
+
+    if (picked === EXIT_VALUE) {
+      return;
+    }
+
+    if (picked === BACK_VALUE) {
+      stack.pop();
+      continue;
+    }
+
+    const selected = children.find((child) => child.name() === picked);
+
+    if (!selected) {
+      return;
+    }
+
+    if (isGroup(selected)) {
+      stack.push(selected);
+      continue;
+    }
+
+    await dispatchLeaf(selected);
+    return;
+  }
+}
+
+/**
+ * Attach the interactive navigator to every group command in the tree. After
+ * this, invoking a group without a subcommand (e.g. `smdg cf` or `smdg cf db`)
+ * opens a searchable menu of its subcommands instead of printing help.
+ *
+ * Leaf commands keep their own action handlers untouched. Existing default
+ * actions on group commands are replaced by the navigator so navigation stays
+ * consistent across the whole CLI.
+ */
+export function enableInteractiveNavigation(program: Command): void {
+  const attach = (command: Command): void => {
+    for (const child of command.commands) {
+      if (isGroup(child)) {
+        child.action(async () => {
+          await runGroupNavigator(child);
+        });
+      }
+
+      attach(child);
+    }
+  };
+
+  attach(program);
+}