@programinglive/dev-workflow-mcp-server 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.1.5](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.4...v1.1.5) (2025-10-25)
+
+
+### ✨ Features
+
+* enforce release guard and per-project workflow state ([1c845a1](https://github.com/programinglive/dev-workflow-mcp-server/commit/1c845a1eb164863ab0269510b142e28ed1ea2136))
+
+### [1.1.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.3...v1.1.4) (2025-10-25)
+
+
+### 🐛 Bug Fixes
+
+* ensure install script uses project root for workflow state ([8b8b32f](https://github.com/programinglive/dev-workflow-mcp-server/commit/8b8b32f5c436b256ec1edb05a406405a5c2455c1))
+
 ### [1.1.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.2...v1.1.3) (2025-10-25)
 
 

package/README.md

@@ -24,7 +24,7 @@ Each project gets its own isolated workflow state file.
 npm install @programinglive/dev-workflow-mcp-server
 ```
 
-This will automatically create a `.workflow-state.json` file in your project root, keeping workflow history separate per project.
+This will automatically create a `.workflow-state.json` file in the **project where you ran `npm install`** (using npm's `INIT_CWD`), keeping workflow history separate per project. If you're installing the package itself (inside `node_modules`), the script skips creation so it never pollutes the shared package directory.
 
 ### Option 2: Install from Source
 
@@ -149,6 +149,19 @@ If you're using this package, add this to your project's `.gitignore`:
 
 This keeps workflow state local to each developer's machine.
 
+## 🚫 Releasing Without the Workflow Steps
+
+The package ships with a release guard (`release-wrapper.js`) that backs the `npm run release:*` scripts. The guard refuses to run unless:
+
+- The current workflow phase is **release**
+- `check_ready_to_commit` and `commit_and_push` have been completed
+- A release has not already been recorded for the active task
+
+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.
+2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
+
 ## 🛠️ Available Tools
 
 ### Tool Argument Requirements

package/install.js

@@ -14,8 +14,17 @@ const __dirname = path.dirname(__filename);
 
 async function install() {
   try {
-    // Get the project root (where npm install was run)
-    const projectRoot = process.cwd();
+    // npm sets INIT_CWD to the directory where `npm install` was originally invoked.
+    // Fallback to process.cwd() if it's not present (e.g., older npm versions).
+    const projectRoot = process.env.INIT_CWD || process.cwd();
+
+    // If INIT_CWD points inside node_modules, this script is being executed
+    // while installing the package itself. In that case, skip creating a state file.
+    if (projectRoot.includes(`node_modules${path.sep}`)) {
+      console.log('ℹ️ Skipping workflow state creation inside node_modules.');
+      return;
+    }
+
     const stateFile = path.join(projectRoot, '.workflow-state.json');
 
     // Check if state file already exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "MCP server to enforce development workflow discipline",
   "type": "module",
   "main": "index.js",
@@ -15,9 +15,9 @@
     "prepare": "husky",
     "postinstall": "node install.js",
     "release": "standard-version",
-    "release:major": "npm run release -- --release-as major",
-    "release:minor": "npm run release -- --release-as minor",
-    "release:patch": "npm run release -- --release-as patch"
+    "release:major": "node release-wrapper.js major",
+    "release:minor": "node release-wrapper.js minor",
+    "release:patch": "node release-wrapper.js patch"
   },
   "keywords": [
     "mcp",

package/release-wrapper.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const RELEASE_TYPES = new Set(['major', 'minor', 'patch']);
+
+async function main() {
+  const releaseTypeArg = (process.argv[2] || '').toLowerCase();
+
+  if (!RELEASE_TYPES.has(releaseTypeArg)) {
+    console.error(
+      '❌ Release guard: expected release type argument (major | minor | patch). Example: npm run release:patch'
+    );
+    process.exit(1);
+  }
+
+  const projectRoot = process.env.INIT_CWD || process.cwd();
+  if (projectRoot.includes(`node_modules${path.sep}`)) {
+    console.error('❌ Release guard: refusing to run inside node_modules.');
+    process.exit(1);
+  }
+
+  const statePath = path.join(projectRoot, '.workflow-state.json');
+  let state;
+
+  try {
+    const raw = await fs.readFile(statePath, 'utf8');
+    state = JSON.parse(raw);
+  } catch (error) {
+    console.error(
+      `❌ Release guard: cannot locate workflow state at ${statePath}. Make sure the dev-workflow MCP is installed and you have started a task.`
+    );
+    process.exit(1);
+  }
+
+  const errors = [];
+  if (state.currentPhase !== 'release') {
+    errors.push(
+      "Current workflow phase isn't 'release'. Complete documentation, commit, and push steps first."
+    );
+  }
+  if (!state.readyCheckCompleted) {
+    errors.push("'check_ready_to_commit' has not been completed.");
+  }
+  if (!state.commitAndPushCompleted) {
+    errors.push("'commit_and_push' has not been completed.");
+  }
+  if (state.released) {
+    errors.push('A release has already been recorded for this task.');
+  }
+
+  if (errors.length) {
+    console.error('❌ Release guard blocked the release:');
+    for (const message of errors) {
+      console.error(`  • ${message}`);
+    }
+    console.error("\nUse 'perform_release' through the dev-workflow MCP after completing the missing steps.");
+    process.exit(1);
+  }
+
+  const runRelease = async () => {
+    if (process.env.DEV_WORKFLOW_SKIP_RELEASE === '1') {
+      console.log('ℹ️ DEV_WORKFLOW_SKIP_RELEASE=1 detected. Skipping actual release command.');
+      return 0;
+    }
+
+    return await new Promise((resolve, reject) => {
+      const child = spawn(
+        'npm',
+        ['run', 'release', '--', '--release-as', releaseTypeArg],
+        { stdio: 'inherit', shell: process.platform === 'win32', cwd: projectRoot }
+      );
+
+      child.on('error', (error) => reject(error));
+      child.on('close', (code) => resolve(code));
+    });
+  };
+
+  try {
+    const exitCode = await runRelease();
+    if (exitCode !== 0) {
+      console.error(`❌ Release command exited with code ${exitCode}.`);
+      process.exit(exitCode);
+    }
+  } catch (error) {
+    console.error(`❌ Failed to run release command: ${error.message}`);
+    process.exit(1);
+  }
+
+  state.released = true;
+  state.releaseCommand = `npm run release:${releaseTypeArg}`;
+  state.currentPhase = 'ready_to_complete';
+
+  try {
+    await fs.writeFile(statePath, JSON.stringify(state, null, 2));
+  } catch (error) {
+    console.error(`❌ Release guard: failed to update workflow state. ${error.message}`);
+    process.exit(1);
+  }
+
+  console.log('✅ Release recorded in workflow state. You can now run complete_task.');
+}
+
+main();

package/tests/release-wrapper.test.js

@@ -0,0 +1,91 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+const PROJECT_ROOT = path.resolve(new URL("..", import.meta.url).pathname);
+const RELEASE_WRAPPER = path.join(PROJECT_ROOT, "release-wrapper.js");
+
+async function runWrapper({ state, args = ["patch"], env = {} }) {
+  const dir = await mkdtemp(path.join(tmpdir(), "release-wrapper-test-"));
+  const statePath = path.join(dir, ".workflow-state.json");
+  await writeFile(statePath, JSON.stringify(state, null, 2));
+
+  const childEnv = {
+    ...process.env,
+    INIT_CWD: dir,
+    DEV_WORKFLOW_SKIP_RELEASE: "1",
+    ...env,
+  };
+
+  return await new Promise((resolve) => {
+    const child = spawn(
+      process.execPath,
+      [RELEASE_WRAPPER, ...args],
+      {
+        cwd: PROJECT_ROOT,
+        env: childEnv,
+        stdio: ["ignore", "pipe", "pipe"],
+      }
+    );
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on("close", async (code) => {
+      let updatedState = null;
+      try {
+        const rawState = await readFile(statePath, "utf8");
+        updatedState = JSON.parse(rawState);
+      } catch {
+        // ignore
+      }
+
+      await rm(dir, { recursive: true, force: true });
+      resolve({ code, stdout, stderr, updatedState });
+    });
+  });
+}
+
+test("release-wrapper blocks when workflow phase is not release", async () => {
+  const result = await runWrapper({
+    state: {
+      currentPhase: "commit",
+      readyCheckCompleted: true,
+      commitAndPushCompleted: true,
+      released: false,
+    },
+  });
+
+  assert.equal(result.code, 1);
+  assert.ok(result.stderr.includes("Release guard blocked the release"));
+  assert.ok(result.stderr.includes("Current workflow phase"));
+  assert.equal(result.updatedState.released, false);
+});
+
+test("release-wrapper marks release after validation passes", async () => {
+  const result = await runWrapper({
+    state: {
+      currentPhase: "release",
+      readyCheckCompleted: true,
+      commitAndPushCompleted: true,
+      released: false,
+      releaseCommand: "",
+    },
+  });
+
+  assert.equal(result.code, 0);
+  assert.ok(result.stdout.includes("Release recorded"));
+  assert.equal(result.updatedState.released, true);
+  assert.equal(result.updatedState.currentPhase, "ready_to_complete");
+  assert.equal(result.updatedState.releaseCommand, "npm run release:patch");
+});

package/workflow-state.js

@@ -5,8 +5,30 @@ import { fileURLToPath } from "url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+function resolveDefaultStateFile() {
+  if (process.env.DEV_WORKFLOW_STATE_FILE) {
+    return path.resolve(process.env.DEV_WORKFLOW_STATE_FILE);
+  }
+
+  const cwd = process.cwd();
+  if (!cwd.includes(`node_modules${path.sep}`)) {
+    return path.join(cwd, ".workflow-state.json");
+  }
+
+  if (process.env.INIT_CWD) {
+    return path.join(process.env.INIT_CWD, ".workflow-state.json");
+  }
+
+  const [beforeNodeModules] = cwd.split(`node_modules${path.sep}`);
+  if (beforeNodeModules) {
+    return path.join(beforeNodeModules, ".workflow-state.json");
+  }
+
+  return path.join(__dirname, ".workflow-state.json");
+}
+
 export class WorkflowState {
-  constructor(stateFilePath = path.join(__dirname, ".workflow-state.json")) {
+  constructor(stateFilePath = resolveDefaultStateFile()) {
     this.stateFile = stateFilePath;
     this.state = {
       currentPhase: "idle",