@programinglive/dev-workflow-mcp-server 1.7.0 → 1.7.10

package/.gitattributes

@@ -0,0 +1,10 @@
+# Enforce LF for all text files (suppresses warnings on Windows)
+* text=auto eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary

package/.github/workflows/github-release.yml

@@ -12,6 +12,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   release:
@@ -28,6 +29,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "20"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Determine version
         id: version
@@ -47,6 +49,21 @@ jobs:
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install web dependencies
+        run: npm ci --prefix web
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --provenance
+
       - name: Generate release notes
         run: |
           echo "Extracting release notes for version ${{ steps.version.outputs.version }}"

package/CHANGELOG.md

@@ -2,7 +2,164 @@
 
 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.7.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.6.0...v1.7.0) (2025-12-06)
+### [1.7.10](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.9...v1.7.10) (2025-12-16)
+
+
+### 🧹 Chores
+
+* update release notes and finalize ci config ([92ac78a](https://github.com/programinglive/dev-workflow-mcp-server/commit/92ac78aeefa1ced8e8a076185bb6689463a46e80))
+
+
+### 📝 Documentation
+
+* update PRD and release notes for v1.7.9 ([024b3c2](https://github.com/programinglive/dev-workflow-mcp-server/commit/024b3c25cd1703622a5f86d6eb09055ea93678d2))
+
+### [1.7.9](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.8...v1.7.9) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** apply official npm trusted publishing config ([9256583](https://github.com/programinglive/dev-workflow-mcp-server/commit/925658336c093c4e2fcfca30dfe469262d67c02d))
+
+### [1.7.8](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.7...v1.7.8) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** remove all token config for pure OIDC publishing ([d4759cc](https://github.com/programinglive/dev-workflow-mcp-server/commit/d4759ccf492396c22fa5aa0fdfbd624c571f7f42))
+
+### [1.7.7](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.6...v1.7.7) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** remove duplicates and apply robust trusted publishing config ([eedb661](https://github.com/programinglive/dev-workflow-mcp-server/commit/eedb661fce4461de68b636e8e7b60b4f0cf465b3))
+
+### [1.7.6](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.5...v1.7.6) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** restore registry config with token fallback for Trusted Publishing ([542615c](https://github.com/programinglive/dev-workflow-mcp-server/commit/542615cb95fe1aaac5f1a5be18694a7577b8eb86))
+
+### [1.7.5](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.4...v1.7.5) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** switch to tokenless trusted publishing ([fdfc4a9](https://github.com/programinglive/dev-workflow-mcp-server/commit/fdfc4a9a86485ee60f0f650e16aa9195671d9ab3))
+
+### [1.7.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.3...v1.7.4) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** add id-token permission for npm provenance ([8930338](https://github.com/programinglive/dev-workflow-mcp-server/commit/8930338aaf90616f1c741c4634ac8e96d3c43fb7))
+
+### [1.7.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.2...v1.7.3) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** add web dependencies installation step ([7d5dc62](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d5dc62a213d3105c2329a1fb810cc6260fe4815))
+
+### [1.7.2](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.1...v1.7.2) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* **ci:** consolidate release and publish workflows ([98e5b31](https://github.com/programinglive/dev-workflow-mcp-server/commit/98e5b31fb64e39b1c846ce594215fb38ab13bf19))
+
+### [1.7.1](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.0...v1.7.1) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* build errors and warnings ([dc24831](https://github.com/programinglive/dev-workflow-mcp-server/commit/dc2483188a58d932590503ec2058c51e3de78d0b))
+* suppress remaining build warnings ([f7d9b2d](https://github.com/programinglive/dev-workflow-mcp-server/commit/f7d9b2d9fb695e6699d65456747c21a301b62fee))
+
+## [1.7.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.6.3...v1.7.0) (2025-12-16)
+
+
+### 🐛 Bug Fixes
+
+* handle null CustPL in birthday-customers.blade.php (ERP-19) ([71b8f7e](https://github.com/programinglive/dev-workflow-mcp-server/commit/71b8f7ebbf83266008e28446630be97ae24e1d64))
+
+
+### ♻️ Refactors
+
+* integrate database adapters into workflow state ([370cbb4](https://github.com/programinglive/dev-workflow-mcp-server/commit/370cbb416b49c758239177296978f7deba5e49e2))
+
+
+### 📝 Documentation
+
+* update PRD and add configuration guide ([1dfccf5](https://github.com/programinglive/dev-workflow-mcp-server/commit/1dfccf5e37eee2994acaf9067320cf13a64fd515))
+* update release notes for 1.6.3 ([afb9fb9](https://github.com/programinglive/dev-workflow-mcp-server/commit/afb9fb9b4c14be0a9f8ecfada3bb72ca75b7f116))
+
+
+### 🧹 Chores
+
+* add mysql2 and pg dependencies ([94423d7](https://github.com/programinglive/dev-workflow-mcp-server/commit/94423d72aab3cb1c2ee47d9a4995e05cceda1f11))
+* **release:** null 🚀 ([93a17e2](https://github.com/programinglive/dev-workflow-mcp-server/commit/93a17e26f1995fda34d2ae40f61f39b697dc03bf))
+* **release:** null 🚀 ([033097e](https://github.com/programinglive/dev-workflow-mcp-server/commit/033097eecd04b2dd3f9299d497ebe71d32f470b9))
+* **release:** null 🚀 ([91c800a](https://github.com/programinglive/dev-workflow-mcp-server/commit/91c800a584f4b967fe60b8058684d5224543f26b))
+* **release:** null 🚀 ([f0958c4](https://github.com/programinglive/dev-workflow-mcp-server/commit/f0958c40f187c0bd4ff77cb2f628fb2338dafa6b))
+* **release:** null 🚀 ([ac3cc6e](https://github.com/programinglive/dev-workflow-mcp-server/commit/ac3cc6e8a5dea2d119c072fbb8029947e234643c))
+* **release:** null 🚀 ([f3f9a00](https://github.com/programinglive/dev-workflow-mcp-server/commit/f3f9a00059c435d2e18940f8a4b41e166a779ff3))
+* **release:** null 🚀 ([bcf7d95](https://github.com/programinglive/dev-workflow-mcp-server/commit/bcf7d9560af34b0a257bfe6566a0cd1572ebb5d1))
+* **release:** null 🚀 ([74df6d6](https://github.com/programinglive/dev-workflow-mcp-server/commit/74df6d6d2972ab2c4702da7e773ab651a41daaa3))
+* **release:** null 🚀 ([0d9dc4d](https://github.com/programinglive/dev-workflow-mcp-server/commit/0d9dc4d3ba751bbe69aecf6221eb79ea2f54ccd9))
+* **release:** null 🚀 ([9667012](https://github.com/programinglive/dev-workflow-mcp-server/commit/966701266afec03b6f621670d2217b98c1a85eb1))
+* **release:** null 🚀 ([db25d0c](https://github.com/programinglive/dev-workflow-mcp-server/commit/db25d0c9117e00d20584a5a175a727f16219bfe9))
+* **release:** null 🚀 ([50d5353](https://github.com/programinglive/dev-workflow-mcp-server/commit/50d535373b080de2b765b0ac9c32ce6f7d4a55f7))
+* **release:** null 🚀 ([ee0a540](https://github.com/programinglive/dev-workflow-mcp-server/commit/ee0a54097cc481c2aeb74ca99a41b34914ab540f))
+* **release:** null 🚀 ([92558af](https://github.com/programinglive/dev-workflow-mcp-server/commit/92558af18f41169760dfbe069f32c9e4969b656d))
+* **release:** null 🚀 ([cd851ac](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd851ac6d3ddd91286b63a83d05a1a5a5a17aee6))
+* **release:** null 🚀 ([49ec562](https://github.com/programinglive/dev-workflow-mcp-server/commit/49ec5629b8308dc9ed19672b07966c3711748817))
+* **release:** null 🚀 ([bcc7a3c](https://github.com/programinglive/dev-workflow-mcp-server/commit/bcc7a3c1a554dbea2dce16585ef926bed925e062))
+
+
+### ✨ Features
+
+* implement database adapters for sqlite, mysql, postgres ([8e7416a](https://github.com/programinglive/dev-workflow-mcp-server/commit/8e7416a467286eaa26051e8e0b4af5f350295087))
+* persist active workflow state to database ([d29546d](https://github.com/programinglive/dev-workflow-mcp-server/commit/d29546dee52940170a9a855146ca870fa078cf66))
+
+### [1.6.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.6.2...v1.6.3) (2025-12-06)
+
+
+### 📝 Documentation
+
+* update release notes for 1.6.2 ([f0c2d49](https://github.com/programinglive/dev-workflow-mcp-server/commit/f0c2d4965f3e08afdaccae5eb49f7ea7d21a6ed3))
+
+
+### 🐛 Bug Fixes
+
+* add light mode support to docs page ([490cf22](https://github.com/programinglive/dev-workflow-mcp-server/commit/490cf2210253a7498cbb3d3a33d1c329672a2dfa))
+
+### [1.6.2](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.6.1...v1.6.2) (2025-12-06)
+
+
+### 📝 Documentation
+
+* update release notest for 1.6.1 ([72a9284](https://github.com/programinglive/dev-workflow-mcp-server/commit/72a92847444436e2c4bd17407e664117fe08a31f))
+
+
+### ✅ Tests
+
+* update create_documentation test to verify PRD check and remove incompatible jest test ([a7f2b28](https://github.com/programinglive/dev-workflow-mcp-server/commit/a7f2b28e65116cfb556767e7e6b25c0b4cdba613))
+
+
+### ✨ Features
+
+* add PRD file existence check to create_documentation workflow step ([62cdee3](https://github.com/programinglive/dev-workflow-mcp-server/commit/62cdee3f7402ed70e3e36003020e84958cdd4a3d))
+* add PRD file existence check to create_documentation workflow step ([6c51012](https://github.com/programinglive/dev-workflow-mcp-server/commit/6c510121980789c3d0e96376fe0375fbaf78a656))
+
+### [1.6.1](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.6.0...v1.6.1) (2025-12-06)
+
+
+### 🐛 Bug Fixes
+
+* add table header to release notes for release script compatibility ([44e47fc](https://github.com/programinglive/dev-workflow-mcp-server/commit/44e47fc49ee9334cad82df095de1277038d0a0e9))
 
 ## [1.6.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.5.11...v1.6.0) (2025-12-06)
 

package/README.md

@@ -181,9 +181,76 @@ Antigravity users should configure the MCP server in their `mcp_config.json`.
 
 See [Antigravity Getting Started](./docs/antigravity/GETTING-STARTED.md) for detailed instructions and troubleshooting.
 
-## 🏗️ Build System
+## ⚙️ Configuration
+
+### Database Backend
+
+By default, the server uses a local **SQLite** database stored in `.state/dev-workflow.db`. You can switch to **MySQL** or **PostgreSQL** for centralized storage using environment variables.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEV_WORKFLOW_DB_TYPE` | Database driver (`sqlite`, `mysql`, `postgres`) | `sqlite` |
+| `DEV_WORKFLOW_DB_URL` | Connection string for MySQL/Postgres | `null` |
+| `DEV_WORKFLOW_DB_PATH` | Override path for the SQLite database file | `<project>/.state/dev-workflow.db` |
+
+#### Examples
+
+**MySQL:**
+```bash
+export DEV_WORKFLOW_DB_TYPE=mysql
+export DEV_WORKFLOW_DB_URL="mysql://user:password@localhost:3306/dev_workflow"
+```
+
+**PostgreSQL:**
+```bash
+export DEV_WORKFLOW_DB_TYPE=postgres
+export DEV_WORKFLOW_DB_URL="postgresql://user:password@localhost:5432/dev_workflow"
+```
+
+### User & State Management
+
+| Variable | Description |
+|----------|-------------|
+| `DEV_WORKFLOW_USER_ID` | Override the auto-generated user ID (e.g., set to your name/email) |
+| `DEV_WORKFLOW_STATE_FILE` | Override the location of the `workflow-state.json` file |
+
+### Using Multiple Clients (Antigravity & Windsurf)
+
+If you use multiple AI coding tools simultaneously (e.g., Antigravity and Windsurf) on the same project, they will share the same workflow state by default.
+
+To maintain **separate, distinct sessions** for each tool, configure a unique `DEV_WORKFLOW_USER_ID` for each.
+
+**Antigravity Config (`mcp_config.json`):**
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "args": ["path/to/server/index.js"],
+      "env": {
+        "DEV_WORKFLOW_USER_ID": "antigravity_user"
+      }
+    }
+  }
+}
+```
+
+**Windsurf Config:**
+Add the environment variable in your Windsurf MCP settings:
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "args": ["path/to/server/index.js"],
+      "env": {
+        "DEV_WORKFLOW_USER_ID": "windsurf_user"
+      }
+    }
+  }
+}
+```
 
-This project includes a Vite-based build system for creating optimized distributions.
 
 ### Scripts
 
@@ -353,6 +420,7 @@ The tool will:
 2. `create_tests`
 3. `run_tests` with `testsPassed`, `testCommand`, and optional `testDetails`
 4. `create_documentation` with `documentationType` and `documentationSummary`
+   - **Requires**: `docs/product/PRD.md` must exist before documentation can be marked complete
 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`
@@ -360,6 +428,10 @@ The tool will:
 
 All arguments except the optional flags are required and must be non-empty strings.
 
+### Documentation Requirements
+
+The `create_documentation` step enforces that a PRD (Product Requirements Document) exists at `docs/product/PRD.md` before documentation can be marked as complete. This ensures all projects maintain a current PRD that describes the product's goals, features, and requirements.
+
 ## 🚫 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:

package/db/adapters/base.js

@@ -0,0 +1,46 @@
+export class DbAdapter {
+    constructor(config = {}) {
+        this.config = config;
+    }
+
+    async connect() {
+        throw new Error("connect() must be implemented by subclass");
+    }
+
+    async migrate() {
+        throw new Error("migrate() must be implemented by subclass");
+    }
+
+    /**
+     * @param {string} userId - User identifier
+     * @param {string} projectPath - Path/ID of the project
+     * @param {Object} entry - Workflow history entry
+     */
+    async insertHistoryEntry(userId, projectPath, entry) {
+        throw new Error("insertHistoryEntry() must be implemented by subclass");
+    }
+
+    async updateSummaryForUser(userId, projectPath) {
+        throw new Error("updateSummaryForUser() must be implemented by subclass");
+    }
+
+    async getSummaryForUser(userId, projectPath) {
+        throw new Error("getSummaryForUser() must be implemented by subclass");
+    }
+
+    async getHistoryForUser(userId, projectPath, options = {}) {
+        throw new Error("getHistoryForUser() must be implemented by subclass");
+    }
+
+    async getHistorySummary(userId, projectPath, options = {}) {
+        throw new Error("getHistorySummary() must be implemented by subclass");
+    }
+
+    async saveState(userId, projectPath, state) {
+        throw new Error("saveState() must be implemented by subclass");
+    }
+
+    async getState(userId, projectPath) {
+        throw new Error("getState() must be implemented by subclass");
+    }
+}

package/db/adapters/mysql.js

@@ -0,0 +1,292 @@
+import mysql from "mysql2/promise";
+import { DbAdapter } from "./base.js";
+
+const FREQUENCY_FORMATS = {
+    daily: "%Y-%m-%d",
+    monthly: "%Y-%m",
+    yearly: "%Y",
+};
+
+export class MysqlAdapter extends DbAdapter {
+    constructor(config = {}) {
+        super(config);
+        this.pool = null;
+    }
+
+    async connect() {
+        if (!this.pool) {
+            this.pool = mysql.createPool({
+                uri: this.config.connectionUrl,
+                waitForConnections: true,
+                connectionLimit: 10,
+                queueLimit: 0,
+                // Support named parameters or handle manually? mysql2 supports '?' by default.
+            });
+            await this.migrate();
+        }
+    }
+
+    async migrate() {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.query(`
+        CREATE TABLE IF NOT EXISTS workflow_history (
+          id INT AUTO_INCREMENT PRIMARY KEY,
+          user_id VARCHAR(255) NOT NULL,
+          project_path VARCHAR(255) DEFAULT '',
+          task_description TEXT NOT NULL,
+          task_type VARCHAR(50) NOT NULL,
+          commit_message TEXT,
+          timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+          forced TINYINT(1) DEFAULT 0,
+          force_reason TEXT,
+          dropped TINYINT(1) DEFAULT 0,
+          drop_reason TEXT,
+          UNIQUE KEY uniq_workflow_entry (user_id, project_path, timestamp, task_description(100))
+        )
+      `);
+
+            await conn.query(`
+        CREATE TABLE IF NOT EXISTS project_summary (
+          user_id VARCHAR(255),
+          project_path VARCHAR(255) DEFAULT '',
+          total_tasks INT DEFAULT 0,
+          task_types JSON,
+          last_active DATETIME,
+          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          recent_tasks JSON,
+          PRIMARY KEY (user_id, project_path)
+        )
+      `);
+
+            await conn.query(`
+        CREATE TABLE IF NOT EXISTS workflow_state (
+          user_id VARCHAR(255),
+          project_path VARCHAR(255) DEFAULT '',
+          state_json JSON,
+          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          PRIMARY KEY (user_id, project_path)
+        )
+      `);
+
+            // Indexes are effectively covered by PRIMARY/UNIQUE keys, but we can add secondary if needed.
+        } finally {
+            conn.release();
+        }
+    }
+
+    async insertHistoryEntry(userId, projectPath, entry) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        // MySQL INSERT ON DUPLICATE KEY UPDATE
+        const query = `
+      INSERT INTO workflow_history
+      (user_id, project_path, task_description, task_type, commit_message, timestamp, forced, force_reason, dropped, drop_reason)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON DUPLICATE KEY UPDATE
+        commit_message=VALUES(commit_message),
+        forced=VALUES(forced),
+        force_reason=VALUES(force_reason),
+        dropped=VALUES(dropped),
+        drop_reason=VALUES(drop_reason)
+    `;
+
+        await this.pool.execute(query, [
+            userId,
+            normalizedProjectPath,
+            entry.taskDescription,
+            entry.taskType,
+            entry.commitMessage,
+            entry.timestamp || new Date().toISOString(),
+            entry.forced ? 1 : 0,
+            entry.forceReason || null,
+            entry.dropped ? 1 : 0,
+            entry.dropReason || null
+        ]);
+
+        await this.updateSummaryForUser(userId, normalizedProjectPath);
+    }
+
+    async updateSummaryForUser(userId, projectPath) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const [rows] = await this.pool.execute(`
+      SELECT task_type, timestamp, task_description
+      FROM workflow_history
+      WHERE user_id = ? AND project_path = ?
+      ORDER BY timestamp DESC
+      LIMIT 20
+    `, [userId, normalizedProjectPath]);
+
+        const taskTypes = {};
+        for (const row of rows) {
+            taskTypes[row.task_type] = (taskTypes[row.task_type] || 0) + 1;
+        }
+
+        const recentTasks = rows.slice(0, 5).map(r => ({
+            description: r.task_description,
+            type: r.task_type,
+            timestamp: r.timestamp,
+        }));
+
+        const lastActive = rows[0]?.timestamp || null;
+
+        const upsert = `
+      INSERT INTO project_summary
+      (user_id, project_path, total_tasks, task_types, last_active, recent_tasks, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON DUPLICATE KEY UPDATE
+        total_tasks=VALUES(total_tasks),
+        task_types=VALUES(task_types),
+        last_active=VALUES(last_active),
+        recent_tasks=VALUES(recent_tasks),
+        updated_at=VALUES(updated_at)
+    `;
+
+        await this.pool.execute(upsert, [
+            userId,
+            normalizedProjectPath,
+            rows.length,
+            JSON.stringify(taskTypes),
+            lastActive,
+            JSON.stringify(recentTasks),
+            new Date().toISOString()
+        ]);
+    }
+
+    async getSummaryForUser(userId, projectPath) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const [rows] = await this.pool.execute(`
+      SELECT * FROM project_summary WHERE user_id = ? AND project_path = ?
+    `, [userId, normalizedProjectPath]);
+
+        const row = rows[0];
+        if (!row) return null;
+
+        return {
+            totalTasks: row.total_tasks,
+            taskTypes: row.task_types, // MySQL driver typically parses JSON columns automatically
+            lastActive: row.last_active,
+            recentTasks: row.recent_tasks,
+            updatedAt: row.updated_at,
+        };
+    }
+
+    async getHistoryForUser(userId, projectPath, options = {}) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const { page = 1, pageSize = 20, startDate, endDate } = options;
+        const sanitizedPage = Math.max(1, Number.isFinite(Number(page)) ? Math.floor(Number(page)) : 1);
+        const sanitizedPageSize = Math.min(100, Math.max(1, Number.isFinite(Number(pageSize)) ? Math.floor(Number(pageSize)) : 20));
+        const offset = (sanitizedPage - 1) * sanitizedPageSize;
+
+        const clauses = [];
+        const params = [userId, normalizedProjectPath];
+
+        if (startDate) {
+            clauses.push("DATE(timestamp) >= DATE(?)");
+            params.push(startDate);
+        }
+        if (endDate) {
+            clauses.push("DATE(timestamp) <= DATE(?)");
+            params.push(endDate);
+        }
+
+        const where = ["user_id = ?", "project_path = ?", ...clauses].join(" AND ");
+
+        const [countRows] = await this.pool.execute(
+            `SELECT COUNT(*) as total FROM workflow_history WHERE ${where}`,
+            params
+        );
+        const total = countRows[0].total;
+
+        const [entries] = await this.pool.execute(`
+      SELECT *
+      FROM workflow_history
+      WHERE ${where}
+      ORDER BY timestamp DESC
+      LIMIT ?
+      OFFSET ?
+    `, [...params, sanitizedPageSize.toString(), offset.toString()]); // prepared statement params often stringified in strict mode, but execute handles numbers usually.
+
+        return {
+            entries,
+            total,
+            page: sanitizedPage,
+            pageSize: sanitizedPageSize,
+        };
+    }
+
+    async getHistorySummary(userId, projectPath, options = {}) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const { startDate, endDate, frequency = "daily" } = options;
+        const format = FREQUENCY_FORMATS[frequency] || FREQUENCY_FORMATS.daily;
+
+        const clauses = [];
+        const params = [userId, normalizedProjectPath];
+        if (startDate) {
+            clauses.push("DATE(timestamp) >= DATE(?)");
+            params.push(startDate);
+        }
+        if (endDate) {
+            clauses.push("DATE(timestamp) <= DATE(?)");
+            params.push(endDate);
+        }
+
+        const where = ["user_id = ?", "project_path = ?", ...clauses].join(" AND ");
+
+        const [rows] = await this.pool.execute(`
+      SELECT DATE_FORMAT(timestamp, '${format}') AS period, COUNT(*) AS count
+      FROM workflow_history
+      WHERE ${where}
+      GROUP BY period
+      ORDER BY period DESC
+    `, params);
+
+        return rows;
+    }
+
+    async saveState(userId, projectPath, state) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const query = `
+      INSERT INTO workflow_state
+      (user_id, project_path, state_json, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON DUPLICATE KEY UPDATE
+        state_json=VALUES(state_json),
+        updated_at=VALUES(updated_at)
+    `;
+
+        await this.pool.execute(query, [
+            userId,
+            normalizedProjectPath,
+            JSON.stringify(state),
+            new Date().toISOString()
+        ]);
+    }
+
+    async getState(userId, projectPath) {
+        await this.connect();
+        const normalizedProjectPath = projectPath || '';
+
+        const [rows] = await this.pool.execute(`
+      SELECT state_json FROM workflow_state WHERE user_id = ? AND project_path = ?
+    `, [userId, normalizedProjectPath]);
+
+        const row = rows[0];
+        if (!row) return null;
+
+        // mysql2 usually parses JSON columns, but if not:
+        return typeof row.state_json === 'string' ? JSON.parse(row.state_json) : row.state_json;
+    }
+}
+