@programinglive/dev-workflow-mcp-server 1.7.16 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.8.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.17...v1.8.0) (2025-12-26)
+
+
+### ♻️ Refactors
+
+* complete handlers.js modularization and fix all tests ([af5b3d6](https://github.com/programinglive/dev-workflow-mcp-server/commit/af5b3d60db025611e9a84a27ccc78f5999d0ead7))
+* split handlers.test.js into smaller focused test modules ([321bbe5](https://github.com/programinglive/dev-workflow-mcp-server/commit/321bbe50d34348202f9e096e5b1903cae519dac6))
+
+### [1.7.17](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.16...v1.7.17) (2025-12-26)
+
+
+### 📝 Documentation
+
+* update release notes for v1.7.16 ([0afd96b](https://github.com/programinglive/dev-workflow-mcp-server/commit/0afd96b754717953eb162f65426129457fc8626e))
+
+
+### ✨ Features
+
+* allow skipping release step ([004e4fa](https://github.com/programinglive/dev-workflow-mcp-server/commit/004e4fae071e064b2c2efb9d69ecd97e794d3cb8))
+
+
+### 🧹 Chores
+
+* add @programinglive/commiter setup ([1d2a19d](https://github.com/programinglive/dev-workflow-mcp-server/commit/1d2a19d0453b50c6f0db35b15924b51a27c4891a))
+
 ### [1.7.16](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.15...v1.7.16) (2025-12-24)
 
 

package/README.md

@@ -512,7 +512,7 @@ This keeps workflow state local to each developer's machine.
 - `create_documentation` - Mark documentation as created
 - `check_ready_to_commit` - Verify all steps are complete
 - `commit_and_push` - Commit and push changes
-- `perform_release` - Record release details
+- `perform_release` - Record release details (or use `skip_release` when the project has no release automation)
 - `complete_task` - Mark task as complete and reset
 - `force_complete_task` - Force completion with reason
 - `drop_task` - Abandon current task
@@ -553,6 +553,7 @@ The tool will:
 5. `check_ready_to_commit`
 6. `commit_and_push` with `commitMessage` and optional `branch`
 7. `perform_release` with `releaseCommand`, plus optional `releaseNotes`, `releaseType`, and `preset`
+   - Alternatively call `skip_release` with a justification when the repository has no Node-based release step (e.g., Python-only or docs-only tasks)
 8. `complete_task` reusing `commitMessage`
 
 All arguments except the optional flags are required and must be non-empty strings.
@@ -571,7 +572,7 @@ The package ships with a release guard (`release-wrapper.js`) that backs the `np
 
 If any requirements are missing, the guard exits with guidance to return to the MCP tools. This prevents accidentally bumping versions or tagging releases outside the managed workflow. To release correctly:
 
-1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client.
+1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client, or `skip_release {"reason":"<explanation>"}` if no release applies.
 2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
 
 ### Automated npm Publishing

package/docs/release-notes/RELEASE_NOTES.md

@@ -4,6 +4,7 @@ Authoritative history of user-visible changes for the Development Workflow MCP S
 
 | Version | Date | Notes |
 |---------|------|-------|
+| 1.7.17 | 2025-12-26 | update release notes for v1.7.16 (0afd96b) |
 | 1.7.16 | 2025-12-24 | align database schema with dashboard and improve user ID handling (69e7f38) |
 | 1.7.15 | 2025-12-19 | optimize startup performance and add database connection resilience (bff2714) |
 | 1.7.14 | 2025-12-19 | add API dependencies and update login to use API client (94bb42f) |
@@ -44,6 +45,15 @@ Authoritative history of user-visible changes for the Development Workflow MCP S
 
 
 
+
+
+## 1.7.17 – 📝 Documentation
+
+Released on **2025-12-26**.
+
+- update release notes for v1.7.16 (0afd96b)
+- allow skipping release step (004e4fa)
+- add @programinglive/commiter setup (1d2a19d)
 
 ## 1.7.16 – 🐛 Bug Fixes
 

package/git-helpers.js

@@ -151,6 +151,15 @@ export async function getCurrentBranch() {
   }
 }
 
+export async function getStatusOutput() {
+  try {
+    const { stdout } = await exec("git status --porcelain");
+    return stdout;
+  } catch (error) {
+    return "";
+  }
+}
+
 export async function getPrimaryBranch() {
   try {
     // Check if 'main' exists on origin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.7.16",
+  "version": "1.8.0",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "mcpName": "io.github.programinglive/dev-workflow-mcp-server",
@@ -62,11 +62,13 @@
   "devDependencies": {
     "@commitlint/cli": "^20.2.0",
     "@commitlint/config-conventional": "^20.2.0",
-    "@programinglive/commiter": "^1.2.16",
+    "@programinglive/commiter": "^1.2.17",
     "autoprefixer": "^10.4.22",
+    "cross-env": "^10.1.0",
     "husky": "^9.1.7",
     "postcss": "^8.5.6",
     "standard-version": "^9.5.0",
+    "supertest": "^7.1.4",
     "tailwindcss": "^3.4.18"
   },
   "standard-version": {

package/scripts/release.cjs

@@ -11,6 +11,9 @@ const FS_FOK_PRELOAD_FLAG = buildPreloadFlag(fsFokPreloadPath);
 
 require('./preload/fs-f-ok.cjs');
 
+const DEFAULT_PRD_RELATIVE_PATH = path.join('docs', 'PRD.md');
+const DEFAULT_PRD_DISPLAY_PATH = 'docs/PRD.md';
+
 const VALID_RELEASE_TYPES = new Set([
   'major',
   'minor',
@@ -161,6 +164,8 @@ function runRelease({
     throw new Error('Working tree has uncommitted changes. Commit or stash before running release.');
   }
 
+  ensurePrdPresence({ cwd, dependencies });
+
   const testResult = runProjectTests({ spawn, env });
   if (testResult && typeof testResult.status === 'number' && testResult.status !== 0) {
     return testResult;
@@ -219,9 +224,31 @@ module.exports = {
   detectPackageManager,
   runProjectTests,
   runRelease,
-  isWorkingTreeClean
+  isWorkingTreeClean,
+  ensurePrdPresence
 };
 
+function ensurePrdPresence({ cwd = process.cwd(), dependencies = {} } = {}) {
+  const {
+    fsExistsSync = fs.existsSync,
+    logger = console,
+    prdRelativePath = DEFAULT_PRD_RELATIVE_PATH,
+    prdDisplayPath = DEFAULT_PRD_DISPLAY_PATH
+  } = dependencies;
+
+  const resolvedPath = path.isAbsolute(prdRelativePath)
+    ? prdRelativePath
+    : path.join(cwd, prdRelativePath);
+
+  if (fsExistsSync(resolvedPath)) {
+    return true;
+  }
+
+  const warn = typeof logger?.warn === 'function' ? logger.warn.bind(logger) : console.warn.bind(console);
+  warn(`⚠️  Product Requirements Document missing (${prdDisplayPath}). Add ${DEFAULT_PRD_DISPLAY_PATH} so teams understand release expectations.`);
+  return false;
+}
+
 function buildPreloadFlag(filePath) {
   const resolved = path.resolve(filePath);
   const escaped = resolved.includes(' ')

package/tests/build.test.js

@@ -8,7 +8,7 @@ import path from 'path';
 const exec = promisify(execCallback);
 
 test('build generates dist/index.mjs file', async () => {
-  const { stderr } = await exec('NODE_ENV=development npm run build:server');
+  const { stderr } = await exec('npx cross-env NODE_ENV=development npm run build:server');
   // Allow the known vite warning about node:process
   const knownWarning = '[plugin vite:resolve] Module "node:process" has been externalized for browser compatibility';
   const tailwindOutput = '≈ tailwindcss';

package/tests/handlers-commit.test.js

@@ -0,0 +1,174 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { handleToolCall } from "../tools/handlers.js";
+import { withWorkflowState, testUtils, createRequest, createGitMock } from "./test-helpers.js";
+
+test("commit_and_push commits changes and pushes", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.readyToCommit = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.testsSkipped = false;
+    workflowState.state.testsCreated = true;
+    workflowState.state.testsPassed = true;
+    workflowState.state.currentPhase = "commit";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("commit_and_push", { commitMessage: "" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        hasWorkingChanges: async () => true,
+        getStagedChanges: async () => [{ status: "M", path: "src/index.js" }],
+        getStatusOutput: async () => "M tests/handlers.test.js\nM src/index.js",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+      }),
+      utils: testUtils,
+    });
+
+    const pushCommand = commands.find((command) => command.startsWith("git push"));
+    assert.ok(pushCommand, "git push should be executed during commit");
+    assert.ok(
+      pushCommand.startsWith("git push origin"),
+      "push command should target origin"
+    );
+    assert.equal(
+      commands.some((command) => command.startsWith("git commit")),
+      true,
+      "git commit should be executed"
+    );
+    assert.ok(
+      response.content[0].text.includes("Commit and push completed!"),
+      "response should confirm commit and push"
+    );
+    assert.equal(workflowState.state.commitAndPushCompleted, true);
+    assert.equal(workflowState.state.lastCommitMessage.length > 0, true);
+    assert.equal(workflowState.state.currentPhase, "release");
+  });
+});
+
+test("commit_and_push uses primary branch when no branch specified", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.readyToCommit = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.testsSkipped = false;
+    workflowState.state.testsCreated = true;
+    workflowState.state.testsPassed = true;
+    workflowState.state.currentPhase = "commit";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("commit_and_push", { commitMessage: "feat: test" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        hasWorkingChanges: async () => true,
+        getStagedChanges: async () => [{ status: "M", path: "src/index.js" }],
+        getCurrentBranch: async () => "feature/test",
+        getStatusOutput: async () => "M tests/handlers.test.js\nM src/index.js",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+      }),
+      utils: testUtils,
+    });
+
+    const pushCommand = commands.find((command) => command.startsWith("git push"));
+    assert.ok(pushCommand, "git push should be executed");
+    assert.ok(
+      /origin\s+['"]?main['"]?/.test(pushCommand),
+      "push should use primary branch (main) when no branch specified"
+    );
+  });
+});
+
+test("commit_and_push falls back to master when main not found", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.readyToCommit = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.testsSkipped = false;
+    workflowState.state.testsCreated = true;
+    workflowState.state.testsPassed = true;
+    workflowState.state.currentPhase = "commit";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("commit_and_push", { commitMessage: "feat: test" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        hasWorkingChanges: async () => true,
+        getStagedChanges: async () => [{ status: "M", path: "src/index.js" }],
+        getPrimaryBranch: async () => "master",
+        getStatusOutput: async () => "M tests/handlers.test.js\nM src/index.js",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+      }),
+      utils: testUtils,
+    });
+
+    const pushCommand = commands.find((command) => command.startsWith("git push"));
+    assert.ok(pushCommand, "git push should be executed");
+    assert.ok(
+      /origin\s+['"]?master['"]?/.test(pushCommand),
+      "push should use master when main not found"
+    );
+  });
+});
+
+test("commit_and_push recognizes already committed work", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.readyToCommit = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.testsSkipped = false;
+    workflowState.state.testsCreated = true;
+    workflowState.state.testsPassed = true;
+    workflowState.state.currentPhase = "commit";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("commit_and_push", { commitMessage: "" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        hasWorkingChanges: async () => false,
+        getLastCommitMessage: async () => "fix: previous work",
+        getStatusOutput: async () => "",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+      }),
+      utils: testUtils,
+    });
+
+    assert.ok(
+      response.content[0].text.includes("No changes detected"),
+      "response should indicate no changes"
+    );
+    assert.equal(workflowState.state.commitAndPushCompleted, true);
+    assert.equal(workflowState.state.currentPhase, "release");
+  });
+});

package/tests/handlers-release.test.js

@@ -0,0 +1,212 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { handleToolCall } from "../tools/handlers.js";
+import { withWorkflowState, testUtils, createRequest, createGitMock } from "./test-helpers.js";
+
+test("perform_release runs release command before pushing with tags", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.lastPushBranch = "feature/split";
+    workflowState.state.lastCommitMessage = "fix: address issue";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      if (command === "git status --porcelain") {
+        return { stdout: "" };
+      }
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("perform_release", { command: "npm run release" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    const releaseCommand = commands.find((command) => command.startsWith("npm run release"));
+    assert.ok(releaseCommand, "release command should run");
+    assert.ok(
+      commands.some((command) => command.startsWith("git push --follow-tags")),
+      "release should push tags"
+    );
+  });
+});
+
+test("perform_release accepts shorthand patch command", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.lastCommitMessage = "fix: adjust labels";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      if (command === "git status --porcelain") {
+        return { stdout: "" };
+      }
+      return { stdout: "" };
+    };
+
+    await handleToolCall({
+      request: createRequest("perform_release", { command: "patch" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    const releaseCommand = commands.find((command) => command.startsWith("npm run release"));
+    assert.ok(releaseCommand, "release command should run with patch");
+  });
+});
+
+test("perform_release respects explicit releaseType option", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      if (command === "git status --porcelain") {
+        return { stdout: "" };
+      }
+      return { stdout: "" };
+    };
+
+    await handleToolCall({
+      request: createRequest("perform_release", {
+        command: "npm run release",
+        releaseType: "minor",
+      }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    const releaseCommand = commands.find((command) => command.startsWith("npm run release"));
+    assert.ok(releaseCommand, "release command should run");
+    assert.ok(
+      releaseCommand.includes("-- --release-as minor"),
+      "release command should append provided releaseType"
+    );
+  });
+});
+
+test("perform_release blocks when new changes detected", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      if (command === "git status --porcelain") {
+        return { stdout: "?? new-file.js" };
+      }
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("perform_release", { command: "patch" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        hasWorkingChanges: async () => true,
+        getStatusOutput: async () => "?? new-file.js",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+        workingTreeSummary: () => ({ hasChanges: true, lines: ["?? new-file.js"] }),
+      }),
+      utils: testUtils,
+    });
+
+    assert.ok(
+      response.content[0].text.includes("run 'commit_and_push' again"),
+      "response should instruct to recommit"
+    );
+    assert.equal(workflowState.state.currentPhase, "commit");
+    assert.equal(workflowState.state.commitAndPushCompleted, false);
+  });
+});
+
+test("perform_release requires commit_and_push completion when tree is clean", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = false;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.lastPushBranch = "";
+    workflowState.state.lastCommitMessage = "";
+    await workflowState.save();
+
+    const commands = [];
+    const execStub = async (command) => {
+      commands.push(command);
+      return { stdout: "" };
+    };
+
+    const response = await handleToolCall({
+      request: createRequest("perform_release", { command: "npm run release" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: execStub,
+      git: createGitMock({
+        getLastCommitMessage: async () => "chore: already pushed",
+        getStatusOutput: async () => "",
+        containsTestFilesInStatus: (statusOutput) => statusOutput.includes("tests/"),
+      }),
+      utils: testUtils,
+    });
+
+    assert.ok(
+      response.content[0].text.includes("commit_and_push"),
+      "response should mention commit_and_push requirement"
+    );
+  });
+});
+
+test("skip_release records justification and advances to completion phase", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.lastCommitMessage = "chore: docs";
+    workflowState.state.releaseSkipped = false;
+    workflowState.state.released = false;
+    workflowState.state.releaseCommand = "";
+    await workflowState.save();
+
+    const response = await handleToolCall({
+      request: createRequest("skip_release", { reason: "Python project – no npm release" }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: async () => ({ stdout: "" }),
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    const text = response.content[0].text;
+    assert.ok(text.includes("Release step skipped"), "response should mention release was skipped");
+    assert.equal(workflowState.state.releaseSkipped, true);
+    assert.equal(workflowState.state.releaseSkippedReason, "Python project – no npm release");
+    assert.equal(workflowState.state.releaseCommand, "(skipped)");
+    assert.equal(workflowState.state.currentPhase, "ready_to_complete");
+    assert.equal(workflowState.state.released, false);
+  });
+});

package/tests/handlers-workflow.test.js

@@ -0,0 +1,68 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { handleToolCall } from "../tools/handlers.js";
+import { withWorkflowState, testUtils, createRequest, createGitMock } from "./test-helpers.js";
+
+test("run_tests guidance mentions core documentation types", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.bugFixed = true;
+    workflowState.state.testsCreated = true;
+    await workflowState.save();
+
+    const response = await handleToolCall({
+      request: createRequest("run_tests", {
+        passed: true,
+        testCommand: "npm test",
+      }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: async () => ({ stdout: "" }),
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    const text = response.content[0].text;
+    assert.ok(
+      text.includes("create or update documentation using 'create_documentation'"),
+      "run_tests guidance should mention create or update documentation",
+    );
+    assert.ok(
+      text.includes('"PRD", "README", "RELEASE_NOTES"'),
+      "run_tests guidance should list core documentation types",
+    );
+  });
+});
+
+test("create_documentation verifies PRD file exists", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.testsPassed = true;
+    await workflowState.save();
+
+    const response = await handleToolCall({
+      request: createRequest("create_documentation", {
+        documentationType: "PRD",
+        summary: "Updated PRD for documentation workflow expectations",
+      }),
+      normalizeRequestArgs: (args) => ({ args, error: null }),
+      workflowState,
+      exec: async () => ({ stdout: "" }),
+      git: createGitMock(),
+      utils: testUtils,
+    });
+
+    assert.equal(workflowState.state.documentationCreated, true);
+    assert.equal(workflowState.state.documentationType, "PRD");
+    assert.equal(
+      workflowState.state.documentationSummary,
+      "Updated PRD for documentation workflow expectations",
+    );
+    assert.ok(
+      response.content[0].text.includes("Documentation created/updated!"),
+      "create_documentation response should mention created/updated",
+    );
+    assert.ok(
+      response.content[0].text.includes("PRD verified"),
+      "create_documentation response should verify PRD file",
+    );
+  });
+});