@programinglive/dev-workflow-mcp-server 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.2.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.3...v1.2.4) (2025-11-11)
+
+
+### ✨ Features
+
+* **docs:** prebuild markdown docs ([84272b6](https://github.com/programinglive/dev-workflow-mcp-server/commit/84272b690e7da88cab60f3b29449044d875261d6))
+
 ### [1.2.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.2...v1.2.3) (2025-11-11)
 
 

package/README.md

@@ -1,5 +1,11 @@
 # Development Workflow MCP Server
 
+<p align="left">
+  <a href="https://www.npmjs.com/package/@programinglive/dev-workflow-mcp-server"><img src="https://img.shields.io/npm/v/@programinglive/dev-workflow-mcp-server.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@programinglive/dev-workflow-mcp-server"><img src="https://img.shields.io/npm/dm/@programinglive/dev-workflow-mcp-server.svg" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
+</p>
+
 An MCP (Model Context Protocol) server that helps enforce development discipline and workflow best practices. This server acts as your coding conscience, reminding you to follow proper development workflows.
 
 ## 🎯 Purpose
@@ -190,6 +196,7 @@ Open `http://localhost:3111` in a browser to view the dashboard UI (`web/index.h
 Running `npm run build` generates:
 - `dist/index.mjs` - Optimized ES module bundle
 - Source maps and other build artifacts
+- `dist/docs/` - Pre-rendered HTML documentation generated from Markdown via `scripts/build-docs.js`
 
 The build bundles all source files while externalizing Node.js built-in modules and dependencies, resulting in a single file distribution.
 
@@ -200,6 +207,16 @@ For MCP server usage, point your client at `index.js` (source) to avoid stdio tr
 - Performance optimization
 - Embedding in other projects
 
+#### PowerShell CLI tip
+
+When invoking the lightweight CLI from PowerShell, use `--%` to prevent PowerShell from rewriting JSON arguments, for example:
+
+```powershell
+node --% index.js call start_task --args "{\"description\":\"Convert docs to HTML during build\",\"type\":\"feature\"}"
+```
+
+The `--%` prefix and escaped double quotes ensure the JSON reaches the MCP server unchanged.
+
 ## 📁 Project-Specific Workflow State
 
 When you install this package in a project, a `.state/workflow-state.json` file is automatically created in your project root. This file:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "build": "vite build",
+    "postbuild": "node scripts/build-docs.js",
     "dev": "node --watch index.js",
     "start": "node index.js",
     "local": "node index.js",
@@ -50,7 +51,8 @@
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
-    "@programinglive/commiter": "^1.1.0"
+    "@programinglive/commiter": "^1.1.0",
+    "marked": "^12.0.2"
   },
   "standard-version": {
     "releaseCommitMessageFormat": "chore(release): {{currentTag}} 🚀",

package/scripts/build-docs.js

@@ -0,0 +1,38 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { marked } from 'marked';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.join(__dirname, '..');
+
+const docs = [
+  {
+    key: 'README.md',
+    source: path.join(projectRoot, 'README.md'),
+    output: 'README.html',
+  },
+  {
+    key: 'web-dashboard.md',
+    source: path.join(projectRoot, 'docs', 'web-dashboard.md'),
+    output: 'web-dashboard.html',
+  },
+];
+
+const distDocDir = path.join(projectRoot, 'dist', 'docs');
+
+async function buildDocs() {
+  await mkdir(distDocDir, { recursive: true });
+
+  for (const doc of docs) {
+    const markdown = await readFile(doc.source, 'utf-8');
+    const html = marked.parse(markdown);
+    await writeFile(path.join(distDocDir, doc.output), html, 'utf-8');
+  }
+}
+
+buildDocs().catch((error) => {
+  console.error('Failed to build documentation assets:', error);
+  process.exitCode = 1;
+});

package/tests/build.test.js

@@ -25,6 +25,15 @@ test('build generates dist/index.mjs file', async () => {
   const content = await readFile(distPath, 'utf-8');
   assert(content.includes('main'), 'Bundle should contain main function');
   assert(content.length > 1000, 'Bundle should be substantial');
+
+  const docDir = path.join(process.cwd(), 'dist', 'docs');
+  const docFiles = ['README.html', 'web-dashboard.html'];
+  for (const file of docFiles) {
+    const fullPath = path.join(docDir, file);
+    await access(fullPath);
+    const docContent = await readFile(fullPath, 'utf-8');
+    assert(docContent.includes('<h1'), `${file} should contain HTML output`);
+  }
 });
 
 test('build script exists in package.json', async () => {

package/web/index.html

@@ -865,8 +865,11 @@
           throw new Error(`Failed to load document (${response.status})`);
         }
         const payload = await response.json();
-        const html = marked.parse(payload.content || '');
+        const rawContent = payload.content || '';
+        const format = (payload.format || 'markdown').toLowerCase();
+        const html = format === 'html' ? rawContent : marked.parse(rawContent);
         docModalContent.innerHTML = html;
+
         lucide.createIcons();
 
         if (headingText) {

package/web/server.js

@@ -9,11 +9,39 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const projectRoot = join(__dirname, "..");
 
-const allowedDocs = {
-  "README.md": join(projectRoot, "README.md"),
-  "web-dashboard.md": join(projectRoot, "docs", "web-dashboard.md"),
+const docSources = {
+  "README.md": {
+    markdown: join(projectRoot, "README.md"),
+    html: join(projectRoot, "dist", "docs", "README.html"),
+  },
+  "web-dashboard.md": {
+    markdown: join(projectRoot, "docs", "web-dashboard.md"),
+    html: join(projectRoot, "dist", "docs", "web-dashboard.html"),
+  },
 };
 
+async function resolveDocContent(docKey) {
+  const entry = docSources[docKey];
+  if (!entry) {
+    return { exists: false };
+  }
+
+  // Try HTML first, fall back to Markdown in development or if HTML missing.
+  const candidates = [entry.html, entry.markdown];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      const content = await readFile(candidate, "utf-8");
+      const format = candidate.endsWith(".html") ? "html" : "markdown";
+      return { exists: true, content, format };
+    } catch {
+      // try next candidate
+    }
+  }
+
+  return { exists: false };
+}
+
 function getPreferredPort() {
   const fromEnv = process.env.PORT || process.env.DEV_WORKFLOW_WEB_PORT;
 
@@ -59,31 +87,31 @@ async function start() {
         res.end(JSON.stringify({ summary }));
       } else if (req.method === "GET" && url.pathname === "/api/docs") {
         const rawDocKey = url.searchParams.get("doc");
+        const availableDocs = Object.keys(docSources);
+
         if (!rawDocKey) {
           res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ docs: Object.keys(allowedDocs) }));
+          res.end(JSON.stringify({ docs: availableDocs }));
           return;
         }
 
         const docKey = rawDocKey.trim();
-        const resolvedKey = Object.keys(allowedDocs).find((key) => key.toLowerCase() === docKey.toLowerCase());
+        const resolvedKey = availableDocs.find((key) => key.toLowerCase() === docKey.toLowerCase());
         if (!resolvedKey) {
           res.writeHead(404, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Document not found", requested: docKey, available: Object.keys(allowedDocs) }));
+          res.end(JSON.stringify({ error: "Document not found", requested: docKey, available: availableDocs }));
           return;
         }
 
-        const docPath = allowedDocs[resolvedKey];
-
-        try {
-          await access(docPath);
-          const content = await readFile(docPath, "utf-8");
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ doc: resolvedKey, content }));
-        } catch (error) {
+        const result = await resolveDocContent(resolvedKey);
+        if (!result.exists) {
           res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: error.message }));
+          res.end(JSON.stringify({ error: "Document asset is missing" }));
+          return;
         }
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ doc: resolvedKey, content: result.content, format: result.format }));
       } else {
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");