openprompt-lang 0.3.0 → 0.4.0

package/src/mcp-server.js

@@ -0,0 +1,605 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, existsSync, statSync } from "fs"
+import { join, extname } from "path"
+import { lintFile } from "./utils/annotations.js"
+import { loadConfig } from "./utils/config.js"
+import {
+  searchTemplates,
+  getTemplate,
+  getLanguage,
+  getLanguageIndex,
+} from "./utils/language-loader.js"
+import { scanForLearnErrors, generateTests, writeTestFile } from "./utils/error-learner.js"
+import { scaffoldFolders } from "./commands/scaffold.js"
+import { extractLesson, extractTags } from "./utils/template-utils.js"
+import { findAllFiles, countFiles } from "./utils/file-utils.js"
+
+const SERVER_INFO = {
+  name: "openPrompt-Lang",
+  version: "0.3.0",
+}
+
+const TOOLS = [
+  {
+    name: "validate",
+    description:
+      "[PRE-COMMIT CHECK] Scan project for annotation errors. Use BEFORE commits or when troubleshooting annotation warnings. Returns file-by-file errors and warnings. If errors found, use lint_file on specific files to debug.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: { type: "string", description: "Path to file to validate" },
+        dir: { type: "string", description: "Directory to scan for files (default: cwd)" },
+      },
+    },
+  },
+  {
+    name: "lint_file",
+    description:
+      "[FILE LINTING] Debug a single file's annotations in detail. Returns parsed annotations, errors, and warnings. More detailed than validate for individual files. Use strict mode for thorough checking.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: { type: "string", description: "Path to the source file" },
+        strict: { type: "boolean", description: "Enable strict mode (warnings become errors)" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "parse_code",
+    description:
+      "[QUICK PARSE] Validate annotation syntax inline without reading from disk. Use during code generation or editing to verify annotation syntax before writing to file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: { type: "string", description: "Source code containing @annotations" },
+      },
+      required: ["code"],
+    },
+  },
+  {
+    name: "context",
+    description:
+      "[CONTEXT EXTRACTION] Extract project structure with config summary and annotated file list. Use when you need a bird's-eye view of the project or before generating documentation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dir: { type: "string", description: "Project directory (default: cwd)" },
+        scope: { type: "string", description: "Filter by @scope module name" },
+      },
+    },
+  },
+  {
+    name: "search_templates",
+    description:
+      "[TEMPLATE DISCOVERY] Find relevant templates before using teach_template. Searches by keyword (button, auth, fetch, form). Returns matching templates with descriptions and metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        lang: { type: "string", description: "Language module (react, vue)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "generate_tests",
+    description:
+      "[TEST GENERATION] Generate Vitest test cases from @learn-error annotations. AFTER documenting a bug with @learn-error, run this to create regression tests. Optionally write to file with output parameter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sourceDir: { type: "string", description: "Source directory to scan (default: cwd)" },
+        lang: { type: "string", description: "Language module (react, vue)" },
+        output: { type: "string", description: "Output path for generated test file (optional)" },
+      },
+    },
+  },
+  {
+    name: "teach_template",
+    description:
+      "[LEARN PATTERNS] Show structured lesson and code from a template. Use when implementing a known pattern (button, auth, form, fetch). Takes templateId like 'button-shadcn' or 'hook-useAuth'. Returns lesson, best practices, fix history, and optionally the code. Run search_templates first to find relevant templates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: {
+          type: "string",
+          description: "Template ID to teach (e.g. button-shadcn, hook-useAuth)",
+        },
+        lang: { type: "string", description: "Language module (react, vue)" },
+        showCode: { type: "boolean", description: "Include full template code in output" },
+      },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "analyze_project",
+    description:
+      "[PROJECT AUDIT] First tool to run when starting work on an unknown project. Returns config summary, file counts by type, and annotation stats. Use to understand project structure before making changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dir: { type: "string", description: "Project directory (default: cwd)" },
+      },
+    },
+  },
+  {
+    name: "scaffold_project",
+    description:
+      "[PROJECT SETUP] Create project folder structure and scaffold files. Use when initializing a new project or adding a module. Takes framework id (react, vue). Creates folders, .gitignore, prompt-lang.json, AGENTS.md.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        framework: { type: "string", description: "Framework/language id (react, vue)" },
+        name: { type: "string", description: "Project subdirectory name (optional)" },
+        force: { type: "boolean", description: "Overwrite existing files" },
+      },
+      required: ["framework"],
+    },
+  },
+]
+
+function sendMessage(msg) {
+  const data = JSON.stringify(msg)
+  process.stdout.write(data + "\n")
+}
+
+function sendError(id, code, message) {
+  sendMessage({ jsonrpc: "2.0", id, error: { code, message } })
+}
+
+function sendResult(id, result) {
+  sendMessage({ jsonrpc: "2.0", id, result })
+}
+
+function formatResult(type, summary, details, actions) {
+  const parts = [`## Result: ${type}`, "", summary]
+  if (details && details.length) {
+    parts.push("", "### Details", ...details.map((d) => `- ${d}`))
+  }
+  if (actions && actions.length) {
+    parts.push("", "### Recommended Actions", ...actions.map((a) => `- ${a}`))
+  }
+  return parts.join("\n")
+}
+
+function toolResult(text, isError = false) {
+  return { content: [{ type: "text", text }], isError }
+}
+
+async function handleToolCall(name, args) {
+  switch (name) {
+    case "validate": {
+      const dir = args?.dir || args?.filePath || process.cwd()
+      const target = join(process.cwd(), dir)
+      if (!existsSync(target)) return toolResult(`Path not found: ${target}`, true)
+
+      // If target is a directory, scan for annotated files
+      if (statSync(target).isDirectory()) {
+        const allFiles = []
+        function walk(d) {
+          let entries
+          try {
+            entries = readdirSync(d, { withFileTypes: true })
+          } catch {
+            return
+          }
+          for (const e of entries) {
+            if (e.name.startsWith(".") || e.name === "node_modules" || e.name === "dist") continue
+            const p = join(d, e.name)
+            if (e.isDirectory()) walk(p)
+            else if (e.isFile() && /\.(ts|tsx|js|jsx)$/.test(e.name)) allFiles.push(p)
+          }
+        }
+        walk(target)
+        if (allFiles.length === 0)
+          return toolResult(
+            formatResult(
+              "info",
+              "No source files found in directory.",
+              [`Scanned: ${target}`],
+              ["Run scaffold_project to initialize project structure."]
+            )
+          )
+        let totalAnn = 0,
+          totalErr = 0,
+          totalWarn = 0
+        const details = []
+        for (const f of allFiles) {
+          const code = readFileSync(f, "utf-8")
+          const result = lintFile(code)
+          totalAnn += result.annotations.length
+          totalErr += result.errors.length
+          totalWarn += result.warnings.length
+          if (result.errors.length || result.warnings.length) {
+            const rel = f.replace(target + "/", "")
+            for (const e of result.errors) details.push(`❌ ${rel}: ${e}`)
+            for (const w of result.warnings) details.push(`⚠ ${rel}: ${w}`)
+          }
+        }
+        const status = totalErr > 0 ? "error" : totalWarn > 0 ? "warning" : "success"
+        const actions = []
+        if (totalErr > 0) actions.push("Fix errors listed above, then run validate again")
+        if (totalWarn > 0) actions.push("Review warnings — some may indicate potential issues")
+        if (totalErr === 0 && totalWarn === 0)
+          actions.push("Project annotations are valid. Ready for commit.")
+        return toolResult(
+          formatResult(
+            status,
+            `Scanned ${allFiles.length} files: ${totalAnn} annotations, ${totalErr} errors, ${totalWarn} warnings`,
+            details.length ? details : [`✅ All annotations valid across ${allFiles.length} files`],
+            actions
+          )
+        )
+      }
+
+      const result = lintFile(readFileSync(target, "utf-8"))
+      const status =
+        result.errors.length > 0 ? "error" : result.warnings.length > 0 ? "warning" : "success"
+      const actions = []
+      if (result.errors.length > 0) actions.push("Fix errors, then re-run validate on this file")
+      if (result.warnings.length > 0) actions.push("Review warnings before committing")
+      if (result.errors.length === 0 && result.warnings.length === 0)
+        actions.push("File is valid. No issues found.")
+      return toolResult(
+        formatResult(
+          status,
+          `File: ${args?.filePath || target}: ${result.annotations.length} annotations, ${result.errors.length} errors, ${result.warnings.length} warnings`,
+          [...result.errors.map((e) => `❌ ${e}`), ...result.warnings.map((w) => `⚠ ${w}`)],
+          actions
+        )
+      )
+    }
+
+    case "lint_file": {
+      const filePath = join(process.cwd(), args.filePath)
+      if (!existsSync(filePath))
+        return toolResult(
+          formatResult(
+            "error",
+            "File not found",
+            [`Path: ${filePath}`],
+            ["Verify the file path and try again"]
+          ),
+          true
+        )
+      const code = readFileSync(filePath, "utf-8")
+      const result = lintFile(code, args.strict)
+      const status =
+        result.errors.length > 0 ? "error" : result.warnings.length > 0 ? "warning" : "success"
+      return toolResult(
+        formatResult(
+          status,
+          `${args.filePath}: ${result.annotations.length} annotations`,
+          [
+            ...result.annotations.map((a) => `@${a.name}(${a.raw})`),
+            ...result.errors.map((e) => `❌ ${e}`),
+            ...result.warnings.map((w) => `⚠ ${w}`),
+          ],
+          result.errors.length
+            ? ["Fix errors and re-run lint_file"]
+            : result.warnings.length
+              ? ["Review warnings"]
+              : ["File is valid"]
+        )
+      )
+    }
+
+    case "parse_code": {
+      if (!args?.code)
+        return toolResult(
+          formatResult(
+            "error",
+            "No code provided",
+            [],
+            ["Pass a 'code' parameter with annotation source text"]
+          ),
+          true
+        )
+      const result = lintFile(args.code)
+      const status =
+        result.errors.length > 0 ? "error" : result.warnings.length > 0 ? "warning" : "success"
+      return toolResult(
+        formatResult(
+          status,
+          `${result.annotations.length} annotations found`,
+          [
+            ...result.annotations.map((a) => `@${a.name}(${a.raw})`),
+            ...result.errors.map((e) => `❌ ${e}`),
+            ...result.warnings.map((w) => `⚠ ${w}`),
+          ],
+          result.errors.length ? ["Fix annotation syntax"] : ["Annotation syntax is valid"]
+        )
+      )
+    }
+
+    case "context": {
+      const dir = args?.dir || process.cwd()
+      const cwd = join(process.cwd(), dir)
+      let config = null
+      try {
+        config = loadConfig(cwd)
+      } catch {}
+      const details = [`Directory: ${dir}`, `Config: ${config ? "found" : "none"}`]
+      if (config) {
+        details.push(
+          `Name: ${config.name || "unnamed"}`,
+          `Language: ${config.lenguaje || "unknown"}`,
+          `Stack: ${(config.stack?.base || []).join(", ")}`
+        )
+      }
+      const actions = config
+        ? ["Run validate to check annotation health"]
+        : ["Run init or scaffold_project to create project config"]
+      return toolResult(formatResult("success", "Project context extracted", details, actions))
+    }
+
+    case "search_templates": {
+      const lang = args?.lang || "react"
+      const query = args?.query || ""
+      const results = searchTemplates(query, { lang })
+      if (!results.length)
+        return toolResult(
+          formatResult(
+            "info",
+            `No templates match "${query}" in ${lang}`,
+            [],
+            ["Try a different query or check available templates with lang list"]
+          )
+        )
+      return toolResult(
+        formatResult(
+          "success",
+          `${results.length} templates found for "${query}" in ${lang}`,
+          results.map(
+            (t, i) => `${i + 1}. ${t.id}: ${t.description || "no description"} — ${t.category}`
+          ),
+          [
+            "Run teach_template with a template ID to learn more",
+            "Use showCode=true in teach_template to see the implementation",
+          ]
+        )
+      )
+    }
+
+    case "generate_tests": {
+      const sourceDir = args?.sourceDir || process.cwd()
+      const lang = args?.lang || "react"
+      const dir = join(process.cwd(), sourceDir)
+      if (!existsSync(dir))
+        return toolResult(formatResult("error", "Directory not found", [`Path: ${dir}`], []), true)
+      const errors = scanForLearnErrors(dir, lang)
+      if (!errors.length)
+        return toolResult(
+          formatResult(
+            "info",
+            "No @learn-error annotations found",
+            [`Scanned: ${dir}`],
+            ["After fixing a bug, add @learn-error to the file and re-run generate_tests"]
+          )
+        )
+      const tests = generateTests(errors, lang)
+      const details = [`Learned errors found: ${errors.length}`, `Tests generated: ${tests.length}`]
+      if (args?.output) {
+        const outPath = join(process.cwd(), args.output)
+        writeTestFile(errors, outPath, lang)
+        details.push(`Written to: ${args.output}`)
+      }
+      const actions = [
+        args?.output
+          ? `Run: npx vitest run ${args.output}`
+          : "Pass 'output' parameter to write test file to disk",
+      ]
+      return toolResult(
+        formatResult(
+          "success",
+          `Generated ${tests.length} tests from ${errors.length} learned errors`,
+          [...details, "", ...tests],
+          actions
+        )
+      )
+    }
+
+    case "teach_template": {
+      const lang = args?.lang || "react"
+      const template = getTemplate(args.templateId, lang)
+      if (!template)
+        return toolResult(
+          formatResult(
+            "error",
+            `Template "${args.templateId}" not found in ${lang}`,
+            [],
+            [`Run search_templates with keywords to find available templates in ${lang}`]
+          ),
+          true
+        )
+      const langObj = getLanguage(lang)
+      const meta = template.metadata
+      const details = [
+        `${meta.name}: ${meta.description || ""}`,
+        `Category: ${meta.category}`,
+        `Purposes: ${meta.purposes?.join(", ") || "general"}`,
+      ]
+      if (meta.variants?.length) details.push(`Variants: ${meta.variants.join(", ")}`)
+      if (meta.sizes?.length) details.push(`Sizes: ${meta.sizes.join(", ")}`)
+      details.push(
+        `Dark mode: ${meta.darkMode ? "yes" : "no"}`,
+        `Responsive: ${meta.responsive ? "yes" : "no"}`,
+        `Deps: ${meta.dependencies?.join(", ") || "none"}`
+      )
+      if (meta.hasTeachMe) {
+        const lesson = extractLesson(template.content)
+        if (lesson) details.push("", "--- LESSON ---", lesson)
+      }
+      const goodP = extractTags(template.content, "@goodPractice")
+      const badP = extractTags(template.content, "@badPractice")
+      if (goodP.length) details.push("", "--- GOOD PRACTICES ---", ...goodP.map((g) => `✅ ${g}`))
+      if (badP.length) details.push("", "--- BAD PRACTICES ---", ...badP.map((b) => `❌ ${b}`))
+      if (args?.showCode) {
+        const clean = template.content
+          .split("\n")
+          .filter((l) => !l.trim().startsWith("// @"))
+          .join("\n")
+        details.push("", "--- CODE ---", clean)
+      }
+      const actions = [
+        "Use this pattern in your project",
+        `Run scaffold_project to set up the project structure`,
+      ]
+      return toolResult(
+        formatResult("success", `${meta.name} — ${langObj?.name || lang}`, details, actions)
+      )
+    }
+
+    case "analyze_project": {
+      const dir = args?.dir || process.cwd()
+      const cwd = join(process.cwd(), dir)
+      if (!existsSync(cwd))
+        return toolResult(formatResult("error", "Directory not found", [`Path: ${cwd}`], []), true)
+      let config = null
+      try {
+        config = loadConfig(cwd)
+      } catch {}
+      const counts = countFiles(cwd)
+      const allFiles = findAllFiles(cwd)
+      const annResults = []
+      for (const f of allFiles) {
+        try {
+          const code = readFileSync(f, "utf-8")
+          const r = lintFile(code)
+          if (r.annotations.length || r.errors.length || r.warnings.length) {
+            annResults.push({ file: f.replace(cwd + "/", ""), ...r })
+          }
+        } catch {}
+      }
+      const details = [
+        `Config: ${config ? "found" : "none"}`,
+        `Name: ${config?.name || "unnamed"}`,
+        `Language: ${config?.lenguaje || "unknown"}`,
+        `Stack: ${(config?.stack?.base || []).join(", ")}`,
+        "",
+        `Total files: ${counts.total}`,
+        `.ts: ${counts.ts} | .tsx: ${counts.tsx} | .js: ${counts.js} | .jsx: ${counts.jsx} | .css: ${counts.css}`,
+        "",
+        `Files with annotations: ${annResults.length}`,
+        ...annResults.map(
+          (r) =>
+            `${r.file}: ${r.annotations.length} annotations, ${r.errors.length} errors, ${r.warnings.length} warnings`
+        ),
+      ]
+      const actions = config
+        ? [
+            "Run validate to check annotation consistency",
+            "Run search_templates to find relevant patterns",
+          ]
+        : ["Run init to set up project configuration"]
+      return toolResult(formatResult("success", `Project analysis: ${dir}`, details, actions))
+    }
+
+    case "scaffold_project": {
+      const output = await scaffoldFolders(args.framework, {
+        name: args?.name,
+        force: args?.force,
+      })
+      if (!output)
+        return toolResult(
+          formatResult(
+            "error",
+            `Failed to scaffold "${args.framework}"`,
+            [],
+            ["Verify the framework id is valid (react, vue)"]
+          ),
+          true
+        )
+      const actions = [
+        "Run validate to verify structure",
+        "Run search_templates to find relevant patterns for your first component",
+      ]
+      return toolResult(
+        formatResult(
+          "success",
+          `Scaffold "${args.framework}" created`,
+          [`Location: ${output}`],
+          actions
+        )
+      )
+    }
+
+    default:
+      return toolResult(`Unknown tool: ${name}`, true)
+  }
+}
+
+export function startServer() {
+  let buffer = ""
+
+  process.stdin.setEncoding("utf-8")
+  process.stdin.on("data", async (chunk) => {
+    buffer += chunk
+    const lines = buffer.split("\n")
+    buffer = lines.pop() || ""
+
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+
+      let msg
+      try {
+        msg = JSON.parse(trimmed)
+      } catch {
+        continue
+      }
+
+      if (msg.jsonrpc !== "2.0") continue
+
+      const { id, method, params } = msg
+
+      switch (method) {
+        case "initialize": {
+          sendResult(id, {
+            protocolVersion: "1.0",
+            capabilities: { tools: {} },
+            serverInfo: SERVER_INFO,
+          })
+          break
+        }
+
+        case "tools/list": {
+          sendResult(id, { tools: TOOLS })
+          break
+        }
+
+        case "tools/call": {
+          try {
+            const result = await handleToolCall(params.name, params.arguments)
+            sendResult(id, result)
+          } catch (err) {
+            sendError(id, -1, err.message)
+          }
+          break
+        }
+
+        case "shutdown": {
+          sendResult(id, null)
+          process.exitCode = 0
+          process.stdout.once("drain", () => process.exit(0))
+          // Force exit after 1s even if drain never fires
+          setTimeout(() => process.exit(0), 1000).unref()
+          break
+        }
+
+        default:
+          sendError(id, -32601, `Method not found: ${method}`)
+      }
+    }
+  })
+
+  process.stdin.on("end", () => process.exit(0))
+}
+
+// Auto-start when executed directly, not when imported
+const isDirectRun =
+  process.argv[1] &&
+  (process.argv[1].endsWith("mcp-server.js") || process.argv[1].endsWith("mcp-server"))
+if (isDirectRun) startServer()