@programinglive/dev-workflow-mcp-server 1.1.7 → 1.1.16

package/docs/web-dashboard.md

@@ -0,0 +1,163 @@
+# Dev Workflow Web Dashboard
+
+Learn how to start and use the Dev Workflow dashboard included with the MCP server. The dashboard exposes project history, summaries, and aggregates through a small Node.js service.
+
+## Prerequisites
+
+Before launching the dashboard, confirm the following:
+
+- Node.js 18+ installed (same requirement as the MCP server)
+- Project dependencies installed with `npm install`
+- Workflow history stored under `.state/` (created automatically when using the MCP server)
+
+> **Plesk users:** follow the [Plesk installation guide](../README.md#option-3-install-on-plesk-hosting) first and ensure SSH access is enabled.
+
+## Features
+
+- **Task history browser** – Paginated list of completed workflow entries.
+- **Summary stats** – Counts of tasks by type and recent activity timeline.
+- **Aggregated trends** – Daily, monthly, or yearly breakdowns of workflow activity.
+- **Multi-user support** – Switch between user identifiers recorded in the `.state` directory.
+
+## Getting Started
+
+Launch the dashboard from your project directory:
+
+```bash
+npm run web
+```
+
+When the server is ready you will see:
+
+```
+🌐 Dev Workflow Dashboard running at http://localhost:3111
+```
+
+Open the URL in your browser. If port 3111 is in use, the script automatically selects a nearby free port.
+
+### Choosing a Port
+
+Set `DEV_WORKFLOW_WEB_PORT` to force a specific port:
+
+```bash
+DEV_WORKFLOW_WEB_PORT=5000 npm run web
+```
+
+### Selecting a User
+
+The dashboard defaults to the `default` user. Append `?user=<USER_ID>` to view another user’s data. User IDs map to the subdirectories under `.state/users/`.
+
+```
+http://localhost:3111/?user=my-teammate
+```
+
+## Navigation
+
+The HTML frontend lives in `web/index.html`. The default UI includes:
+
+- **Summary cards** – Total tasks completed and last active date.
+- **Recent tasks table** – Paginated entries with task descriptions and timestamps.
+- **Charts** (if script extensions are enabled) – Visual trends per frequency selection.
+
+## API Reference
+
+Interact with the dashboard programmatically using the JSON endpoints served by `web/server.js`.
+
+### `GET /api/summary`
+
+Returns aggregate statistics for a user.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+
+**Response**
+
+```json
+{
+  "summary": {
+    "totalTasks": 12,
+    "taskTypes": { "feature": 8, "bugfix": 3, "refactor": 1 },
+    "lastActive": "2025-10-01T09:25:41.123Z",
+    "recentTasks": [
+      { "description": "feat: add billing webhooks", "type": "feature", "timestamp": "2025-10-01T09:25:41.123Z" }
+    ],
+    "updatedAt": "2025-10-01T09:30:00.000Z"
+  }
+}
+```
+
+### `GET /api/history`
+
+Returns paginated task history.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+- `page` *(optional, number)* – Page number (default `1`).
+- `pageSize` *(optional, number)* – Items per page (default `20`, max `100`).
+- `startDate` *(optional, string)* – Filter by ISO date (inclusive).
+- `endDate` *(optional, string)* – Filter by ISO date (inclusive).
+
+**Response**
+
+```json
+{
+  "entries": [
+    {
+      "id": 42,
+      "user_id": "default",
+      "task_description": "feat: add reporting endpoint",
+      "task_type": "feature",
+      "commit_message": "feat: add reporting endpoint",
+      "timestamp": "2025-09-30T09:18:00.000Z"
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "pageSize": 20
+}
+```
+
+### `GET /api/history-summary`
+
+Returns an array of task counts grouped by period.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+- `frequency` *(optional, string)* – `daily`, `monthly`, or `yearly` (default `daily`).
+- `startDate`, `endDate` *(optional, string)* – Limit range by ISO dates.
+
+**Response**
+
+```json
+{
+  "summary": [
+    { "period": "2025-09-30", "count": 3 },
+    { "period": "2025-09-29", "count": 1 }
+  ]
+}
+```
+
+## Configuration
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `DEV_WORKFLOW_WEB_PORT` | Port for the dashboard | `3111` or next available |
+| `DEV_WORKFLOW_USER_ID` | User identifier when launching via MCP | auto-generated |
+| `DEV_WORKFLOW_STATE_FILE` | Overrides path to workflow state JSON | auto-detected |
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Server fails with `better-sqlite3` build error | Install Python 3 and build tools (Windows) or ensure SQLite build dependencies exist (Linux/macOS). |
+| Dashboard shows empty data | Confirm the MCP server has generated `.state/users/<user>/workflow-state.json` and that the chosen `user` matches. |
+| Port already in use | Set `DEV_WORKFLOW_WEB_PORT` to a free port before running `npm run web`. |
+
+## Related Topics
+
+- [Main README](../README.md)
+- [Workflow State Internals](./state.md) *(coming soon)*
+- [CLI Tools](../README.md#🛠️-available-tools)

package/exec.js

@@ -1,4 +1,49 @@
 import { exec as execCallback } from "child_process";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
 import { promisify } from "util";
 
-export const exec = promisify(execCallback);
+const execPromise = promisify(execCallback);
+
+function findRepoRoot(startDir) {
+  if (!startDir) {
+    return null;
+  }
+
+  let current = path.resolve(startDir);
+  const { root } = path.parse(current);
+
+  while (true) {
+    if (existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+
+    if (current === root) {
+      return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+
+    current = parent;
+  }
+}
+
+function getDefaultCwd() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const candidateDirs = [process.cwd(), process.env.INIT_CWD, moduleDir];
+  return candidateDirs.reduce((resolved, candidate) => {
+    if (resolved) {
+      return resolved;
+    }
+    return findRepoRoot(candidate) || null;
+  }, null) || process.cwd();
+}
+
+export function exec(command, options = {}) {
+  const execOptions = options.cwd ? options : { ...options, cwd: getDefaultCwd() };
+  return execPromise(command, execOptions);
+}

package/index.js

@@ -32,8 +32,7 @@ export { createCommitMessageParts, determineReleaseTypeFromCommit } from "./comm
 export { containsTestFilesInStatus, workingTreeSummary } from "./git-helpers.js";
 export { WorkflowState } from "./workflow-state.js";
 
-export const workflowState = new WorkflowState();
-await workflowState.load();
+export let workflowState = null;
 
 const __filename = fileURLToPath(import.meta.url);
 
@@ -184,14 +183,90 @@ Use 'check_ready_to_commit' to verify workflow completion.
 
 // Start server
 export async function main() {
+  try {
+    // Initialize workflow state
+    workflowState = new WorkflowState();
+    await workflowState.load();
+    await workflowState.ensurePrimaryFile();
+  } catch (error) {
+    console.error("Warning: Failed to initialize workflow state:", error.message);
+    // Continue anyway - workflow state is optional for MCP to function
+    workflowState = new WorkflowState();
+  }
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("Dev Workflow MCP Server running on stdio");
 }
 
-if (process.argv[1] === __filename) {
-  main().catch((error) => {
-    console.error("Server error:", error);
+// --- Lightweight CLI: dev-workflow-mcp call <toolName> [--args '<json>'] ---
+async function cliMain(argv) {
+  const [, , subcommand, toolName, ...rest] = argv;
+  if (subcommand !== "call") return false;
+
+  if (!toolName || typeof toolName !== "string" || toolName.trim() === "") {
+    console.error("Usage: dev-workflow-mcp call <toolName> [--args '<json>']");
+    process.exit(2);
+  }
+
+  // Parse --args '<json>' if provided
+  let rawArgs = undefined;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--args") {
+      rawArgs = rest[i + 1];
+      break;
+    }
+  }
+
+  try {
+    // Initialize workflow state similar to the server path
+    workflowState = new WorkflowState();
+    await workflowState.load();
+    await workflowState.ensurePrimaryFile();
+
+    const request = {
+      params: {
+        name: toolName,
+        arguments: rawArgs ?? {},
+      },
+    };
+
+    const response = await handleToolCall({
+      request,
+      normalizeRequestArgs,
+      workflowState,
+      exec,
+      git: {
+        hasWorkingChanges,
+        hasTestChanges,
+        hasStagedChanges,
+        getStagedChanges,
+        getCurrentBranch,
+        getLastCommitMessage,
+        workingTreeSummary,
+      },
+      utils: { shellEscape, determineReleaseTypeFromCommit, createCommitMessageParts },
+    });
+
+    const text = response?.content?.[0]?.text || "";
+    console.log(text);
+    const isError = /^\s*[⚠️❌]/u.test(text);
+    process.exit(isError ? 1 : 0);
+  } catch (error) {
+    console.error("CLI error:", error.message || String(error));
     process.exit(1);
-  });
+  }
+}
+
+const isDirectRun = process.argv[1] === __filename;
+if (isDirectRun) {
+  // If invoked with a CLI subcommand, run it; otherwise start MCP server
+  if (process.argv[2] === "call") {
+    cliMain(process.argv);
+  } else {
+    main().catch((error) => {
+      console.error("Server error:", error);
+      process.exit(1);
+    });
+  }
 }

package/install.js

@@ -25,7 +25,11 @@ async function install() {
       return;
     }
 
-    const stateFile = path.join(projectRoot, '.workflow-state.json');
+    const stateDir = path.join(projectRoot, '.state');
+    const stateFile = path.join(stateDir, 'workflow-state.json');
+
+    // Create .state directory if it doesn't exist
+    await fs.mkdir(stateDir, { recursive: true });
 
     // Check if state file already exists
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.1.7",
+  "version": "1.1.16",
   "description": "MCP server to enforce development workflow discipline",
   "type": "module",
   "main": "index.js",
@@ -8,16 +8,19 @@
     "dev-workflow-mcp": "index.js"
   },
   "scripts": {
+    "build": "vite build",
+    "dev": "node --watch index.js",
+    "start": "node index.js",
+    "local": "node index.js",
     "test": "node --test",
     "check": "node --check index.js",
-    "start": "node index.js",
-    "dev": "node --watch index.js",
     "prepare": "husky",
     "postinstall": "node install.js",
     "release": "standard-version",
     "release:major": "node release-wrapper.js major",
     "release:minor": "node release-wrapper.js minor",
-    "release:patch": "node release-wrapper.js patch"
+    "release:patch": "node release-wrapper.js patch",
+    "web": "node web/server.js"
   },
   "keywords": [
     "mcp",
@@ -27,8 +30,18 @@
   ],
   "author": "",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/programinglive/dev-workflow-mcp-server.git"
+  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.8.0",
+    "esbuild": "^0.25.0",
+    "get-port": "^7.1.0",
+    "husky": "^9.1.7",
+    "standard-version": "^9.5.0",
+    "vite": "^7.1.12"
   },
   "publishConfig": {
     "access": "public"
@@ -36,9 +49,7 @@
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
-    "@programinglive/commiter": "^1.0.0",
-    "husky": "^9.1.7",
-    "standard-version": "^9.5.0"
+    "@programinglive/commiter": "^1.1.0"
   },
   "standard-version": {
     "releaseCommitMessageFormat": "chore(release): {{currentTag}} 🚀",

package/release-wrapper.js

@@ -22,7 +22,32 @@ async function main() {
     process.exit(1);
   }
 
-  const statePath = path.join(projectRoot, '.workflow-state.json');
+  // Prefer state under INIT_CWD to support per-project runs and tests.
+  // If DEV_WORKFLOW_USER_ID is set and a user-scoped file exists, use it; otherwise fall back to legacy path.
+  const baseStateDir = path.join(projectRoot, '.state');
+  const legacyStatePath = path.join(baseStateDir, 'workflow-state.json');
+  let resolvedUserId = (process.env.DEV_WORKFLOW_USER_ID || '').trim();
+  if (!resolvedUserId) {
+    try {
+      const fileUserId = (await fs.readFile(path.join(baseStateDir, 'user-id'), 'utf8')).trim();
+      if (fileUserId) {
+        resolvedUserId = fileUserId;
+      }
+    } catch {
+      // no user-id file; legacy layout likely
+    }
+  }
+  const userStatePath = resolvedUserId ? path.join(baseStateDir, 'users', resolvedUserId, 'workflow-state.json') : null;
+
+  let statePath = legacyStatePath;
+  if (userStatePath) {
+    try {
+      await fs.access(userStatePath);
+      statePath = userStatePath;
+    } catch {
+      // fall back to legacy path
+    }
+  }
   let state;
 
   try {

package/tests/build.test.js

@@ -0,0 +1,37 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { readFile, access } from 'fs/promises';
+import { exec as execCallback } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+
+const exec = promisify(execCallback);
+
+test('build generates dist/index.mjs file', async () => {
+  const { stderr } = await exec('npm run build');
+  // Allow the known vite warning about node:process
+  const knownWarning = '[plugin vite:resolve] Module "node:process" has been externalized for browser compatibility';
+  const actualStderr = stderr.replace(/\x1B\[[0-9;]*m/g, ''); // Remove ANSI codes
+  assert(
+    actualStderr === '' || actualStderr.includes(knownWarning),
+    `Build should not have unexpected errors: ${actualStderr}`
+  );
+  
+  // Verify the file exists
+  const distPath = path.join(process.cwd(), 'dist', 'index.mjs');
+  await access(distPath);
+  
+  // Verify it contains expected content
+  const content = await readFile(distPath, 'utf-8');
+  assert(content.includes('main'), 'Bundle should contain main function');
+  assert(content.length > 1000, 'Bundle should be substantial');
+});
+
+test('build script exists in package.json', async () => {
+  const packagePath = path.join(process.cwd(), 'package.json');
+  const content = await readFile(packagePath, 'utf-8');
+  const pkg = JSON.parse(content);
+  
+  assert.strictEqual(typeof pkg.scripts.build, 'string');
+  assert(pkg.scripts.build.includes('vite build'));
+});

package/tests/exec.test.js

@@ -0,0 +1,35 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { exec } from '../exec.js';
+import { tmpdir } from 'os';
+import { mkdtemp, rm } from 'fs/promises';
+import path from 'path';
+
+test('exec runs commands successfully', async () => {
+  const echoCommand = process.platform === 'win32' ? 'echo hello world' : 'echo "hello world"';
+  const { stdout } = await exec(echoCommand);
+  const normalized = stdout.trim().replace(/^"(.*)"$/, '$1');
+  assert.strictEqual(normalized, 'hello world');
+});
+
+test('exec respects explicit cwd option', async () => {
+  const tempDir = await mkdtemp(path.join(tmpdir(), 'mcp-test-'));
+  
+  try {
+    const dirCommand = process.platform === 'win32' ? 'cd' : 'pwd';
+    const { stdout } = await exec(dirCommand, { cwd: tempDir });
+    // Just verify it runs in the specified directory (path may vary by platform)
+    assert(stdout.trim().toLowerCase().includes('mcp-test-'));
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test('exec handles command errors', async () => {
+  try {
+    await exec('command-that-does-not-exist');
+    assert.fail('Should have thrown an error');
+  } catch (error) {
+    assert(error.code !== undefined || error.message.includes('command-not-found'));
+  }
+});