@programinglive/dev-workflow-mcp-server 1.8.1 → 1.9.1

package/README.md

@@ -1,51 +1,26 @@
-# 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.
-
-### 🛡️ Resilience Features
-- **Startup Resilience**: 5-second connection timeouts for external databases.
-- **Background Loading**: Non-critical assets (compatibility mirrors) initialize in the background to ensure sub-second startup.
-- **Diagnostic Mode**: Automatic startup timing logs displayed in stderr.
-
-## 🎯 Purpose
-
-This MCP server guides you through a disciplined development workflow:
-
-1. **Start Conscious** - Be clear about what you're coding
-2. **Fix/Implement** - Write your code
-3. **Create Tests** - Always test your changes
-4. **Run Tests** - Tests must pass (GREEN)
-5. **Document** - Update documentation
-6. **Commit & Push** - Let the server stage, commit, **and push** your changes once verification passes (if you make new edits afterward, the workflow moves back to this step automatically)
-7. **Release** - After the push succeeds, record the release details before closing out the task
-
-## 🆕 What's New in v1.8.0
-
-- **Modular Handler Architecture** – `tools/handlers.js` now re-exports focused handler modules, improving maintainability and bundler behavior.
-- **Organized Test Suite** – The 1k-line `tests/handlers.test.js` has been split into `handlers-*.test.js` files with shared helpers, reducing duplication and clarifying intent.
-- **Shared Test Utilities** – New `tests/test-helpers.js` centralizes workflow state setup, request builders, and git mocks.
-- **Documentation Refresh** – PRD moved to `docs/PRD.md` root, status bumped to v1.8.0, and release notes updated to reflect the current workflow.
-- **Release Hygiene** – Recommended flow now includes `npm run release:<type>` followed by `git push --follow-tags origin main` to keep stages clean.
-
-## 🚀 Installation
-
-### Option 1: Install as Dependency in Your Project (Recommended)
-
-Each project gets its own isolated workflow state file.
-
-```bash
-npm install @programinglive/dev-workflow-mcp-server
+# Dev Workflow MCP Server
+
+MCP server yang memaksa kamu mengikuti disiplin development workflow: **test → dokumentasi → commit → release**, tanpa bisa dilewatkan.
+
+```mermaid
+graph LR
+    A[start_task] --> B[Implement]
+    B --> C[mark_bug_fixed]
+    C --> D[create_tests]
+    D --> E[run_tests]
+    E -- FAIL --> B
+    E -- PASS --> F[create_documentation]
+    F --> G[check_ready_to_commit]
+    G --> H[commit_and_push]
+    H --> I[perform_release / skip_release]
+    I --> J[complete_task]
 ```
 
-This will automatically create a `.state/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
+## Quick Start — 3 Menit
+
+### 1. Clone & Install
 
 ```bash
 git clone https://github.com/programinglive/dev-workflow-mcp-server.git
@@ -53,790 +28,400 @@ cd dev-workflow-mcp-server
 npm install
 ```
 
-> **Windows prerequisites:** Installing dependencies from source compiles native modules such as `better-sqlite3`. Make sure Python 3 (added to PATH) and the Visual Studio Build Tools “Desktop development with C++” workload are installed before running `npm install`. Without them, npm will fail with a “need python” or build error.
+> **Windows**: `better-sqlite3` butuh native build. Install [Python 3](https://python.org) + [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) dulu sebelum `npm install`.
 
-### Option 3: Install on Plesk Hosting
+### 2. Test Server Berjalan
 
-Plesk supports Node.js applications through its Node.js extension. To deploy the MCP server on a Plesk subscription:
+```bash
+node index.js call get_workflow_status
+```
 
-1. **Enable Node.js support** – Ensure the Plesk administrator has installed the Node.js extension and enabled SSH access for your subscription.
-2. **Upload the project** – Either clone the repository or upload an archive into the directory you will run it from (e.g., `httpdocs/dev-workflow-mcp-server`). From SSH you can run:
-   ```bash
-   cd httpdocs
-   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
-   cd dev-workflow-mcp-server
-   ```
-3. **Install dependencies** – In Plesk’s **Node.js** panel use “NPM install” (or run `npm install --production` over SSH). Linux hosts already ship the Python/build toolchain required for `better-sqlite3`; if your plan uses a Windows host, install Python 3 and the Visual Studio Build Tools beforehand or ask your provider to enable them.
-4. **Define environment variables** – In the Node.js panel add any environment variables you need (for example `DEV_WORKFLOW_USER_ID` or `DEV_WORKFLOW_STATE_FILE`). This keeps state files outside the web root if desired.
-5. **Configure the application** – Set **Application startup file** to `index.js` and **Application mode** to `production`. Plesk will run the server with `node index.js`.
-6. **Start/Restart the app** – Click “Restart App” so Plesk launches the MCP server with the new configuration. When you update the code, rerun “NPM install” and restart.
+Output:
 
-> **Tip:** The MCP server communicates over stdio. If you only need it as a CLI tool, you can also run `npx @programinglive/dev-workflow-mcp-server` directly in an SSH session without keeping it running under the Node.js panel.
+```
+📊 Current Workflow Status:
+Phase: idle
+Task: (none)
+Next step: idle
+```
 
-> **Important:** MCP clients (Windsurf, Claude Desktop, etc.) must launch the server process locally via stdio. Hosting the dashboard on a public domain does **not** expose the MCP interface. Without SSH or another way to execute `node index.js` on the server, users cannot connect their MCP clients to the hosted instance.
+### 3. Hubungkan ke MCP Client
 
-### Option 4: Deploy with Docker on Google Cloud
+Lihat bagian [Konfigurasi MCP Client](#-konfigurasi-mcp-client) di bawah.
 
-Deploy the MCP server to Google Cloud Compute Engine using Docker and PostgreSQL for a production-ready, cloud-hosted setup.
+---
 
-**Quick Start:**
-1. SSH into your GCP instance
-2. Run the setup script: `bash scripts/setup-gcp-instance.sh`
-3. Clone the repository and configure `.env`
-4. Start containers: `docker-compose up -d`
-5. Update your local MCP client config to connect via SSH
+## 🛠️ Available Tools
 
-**Benefits:**
-- ✅ PostgreSQL database for robust data persistence
-- ✅ Containerized deployment for consistency
-- ✅ Remote access via SSH tunneling
-- ✅ Easy updates and rollbacks
+| Tool | Fungsi |
+|---|---|
+| `start_task` | Mulai task baru (wajib pertama) |
+| `create_feature_flow` | Catat alur fitur dengan Mermaid |
+| `mark_bug_fixed` | Tandai implementasi selesai |
+| `create_tests` | Tandai tests sudah dibuat |
+| `skip_tests` | Lewati tests dengan alasan |
+| `run_tests` | Catat hasil test (blokir commit jika fail) |
+| `create_documentation` | Tandai docs sudah dibuat |
+| `check_ready_to_commit` | Verifikasi semua step selesai |
+| `commit_and_push` | `git add` → `commit` → `push` otomatis |
+| `perform_release` | Catat release version |
+| `skip_release` | Lewati release (docs-only task) |
+| `complete_task` | Selesai & reset workflow |
+| `get_workflow_status` | Cek fase saat ini |
+| `view_history` | Lihat riwayat task selesai |
+| `run_full_workflow` | Jalankan semua step sekaligus (1 command) |
+| `project_summary` | Ringkasan aktivitas project |
+
+### Contoh Percakapan
 
-See the [GCP Deployment Guide](./docs/GCP_DEPLOYMENT.md) for complete step-by-step instructions.
+```
+"Start a new task: add user authentication, type: feature"
+→ start_task called, phase moves to coding
 
+[kamu ngoding]
 
-#### Two Usage Modes
+"Mark as fixed: login with JWT token"
+→ mark_bug_fixed, phase moves to testing
 
-- **Local (source)**: Point your MCP client to `index.js`. This runs directly from source and requires no build step. Recommended for MCP usage.
-- **Production (built)**: Run `npm run build` once to generate `dist/`. This creates an optimized bundle but isn’t needed for MCP usage.
+[tulis test]
 
-### 3. Configure in Windsurf/Claude Desktop
+"Create tests done"
+→ create_tests
 
-Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with the absolute path to this repository on your machine.
+"Run tests: passed=true, command='npm test', details='12 tests passed'"
+→ run_tests, phase moves to documentation
 
-#### macOS
+"Create docs: type=README, summary='Added auth section'"
+→ create_documentation, phase moves to ready_to_commit
 
-- **Windsurf** (`~/Library/Application Support/Windsurf/config.json`):
+"Check if ready to commit"
+→ check_ready_to_commit → ✅ READY
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "cwd": "<PROJECT_ROOT>",
-      "args": ["index.js"],
-      "env": {
-        "DEV_WORKFLOW_DB_TYPE": "postgres",
-        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
-      }
-    }
-  }
-}
-```
+"Commit and push: message='feat(auth): add JWT authentication'"
+→ commit_and_push (auto git add/commit/push), phase moves to release
 
-- **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+"Perform release: command='npm run release:minor'"
+→ perform_release, phase moves to ready_to_complete
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
-    }
-  }
-}
+"Complete task: commitMessage='feat(auth): add JWT authentication'"
+→ complete_task, workflow reset to idle
 ```
 
-#### Windows
+---
 
-- **Windsurf** (`%APPDATA%\Windsurf\config.json`):
+## ⚙️ Konfigurasi MCP Client
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
-    }
-  }
-}
-```
+### OpenCode
 
-- **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`):
+Tambahkan ke `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "mcpServers": {
+  "mcp": {
     "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
+      "type": "local",
+      "command": ["node", "C:\\path\\to\\dev-workflow-mcp-server\\index.js"],
+      "enabled": true
     }
   }
 }
 ```
 
-#### Linux
+### Claude Desktop
 
-- **Windsurf** (`~/.config/windsurf/config.json`):
+File: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) atau `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
+      "args": ["C:\\path\\to\\dev-workflow-mcp-server\\index.js"]
     }
   }
 }
 ```
 
-- **Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
+### Windsurf
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
-    }
-  }
-}
-```
-
-> **Note:** On Windows paths in JSON require escaped backslashes (e.g., `"C:\\path\\to\\project"`).
-
-#### Full Windsurf MCP Config Example (macOS)
-
-If you keep this repository checked out at `/Users/alex/code/dev-workflow-mcp-server` and want to point Windsurf at a hosted PostgreSQL instance, drop the following into `~/Library/Application Support/Windsurf/mcp_config.json`:
+File: `%APPDATA%\Windsurf\config.json` (Windows) atau `~/Library/Application Support/Windsurf/config.json` (macOS)
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
-      "args": ["index.js"],
-      "env": {
-        "DEV_WORKFLOW_DB_TYPE": "postgres",
-        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
-      }
+      "cwd": "C:\\path\\to\\dev-workflow-mcp-server",
+      "args": ["index.js"]
     }
   }
 }
 ```
 
-This mirrors the Windows configuration shared in previous releases, but avoids `npx` lookup issues on macOS by launching the local `index.js` directly.
-
-### 4. Restart Windsurf/Claude Desktop
-
-After adding the configuration, restart the application to load the MCP server.
-
+### Antigravity
 
-### 5. Configure in Antigravity
-
-Antigravity users should configure the MCP server in their `mcp_config.json`.
-
-**Windows:** `%APPDATA%\Antigravity\mcp_config.json` or `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
+File: `%APPDATA%\Antigravity\mcp_config.json`
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
+      "args": ["C:\\path\\to\\dev-workflow-mcp-server\\index.js"]
     }
   }
 }
 ```
 
-See [Antigravity Getting Started](./docs/antigravity/GETTING-STARTED.md) for detailed instructions and troubleshooting.
-
-### ⚡ Performance Optimization (Recommended)
+> **Performance tip**: Gunakan `node index.js` langsung, jangan `npx`, agar startup lebih cepat.
 
-To ensure the fastest possible startup (critical for IDE-integrated clients like Claude Desktop), we recommend pointing directly to `index.js` using `node` rather than `npx`. This avoids the overhead of checking for package updates.
+---
 
-**Optimized Configuration:**
+## 🔧 Configuration
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"],
-      "env": {
-        "DEV_WORKFLOW_USER_ID": "your_user_id"
-      }
-    }
-  }
-}
-```
+### Database
 
-The server automatically times its own startup and logs it to stderr:
-`Dev Workflow MCP Server running on stdio (startup took 15ms)`
+Default pakai **SQLite** (file-based, zero config). Bisa ganti ke PostgreSQL/MySQL:
 
-## ⚙️ Configuration
-
-### Database Setup
-
-The server supports **SQLite** (default), **MySQL**, and **PostgreSQL**.
-
-#### Configuration via `.env`
-1. Copy `.env.example` to `.env`:
-   ```bash
-   cp .env.example .env
-   ```
-2. Edit `.env` with your settings:
-   ```ini
-   DEV_WORKFLOW_DB_TYPE=mysql
-   DEV_WORKFLOW_DB_URL=mysql://user:pass@localhost:3306/db
-   ```
-
-#### Configuration via Environment Variables
-Alternatively, export variables directly:.
-
-| 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"
+# .env atau environment variable
+DEV_WORKFLOW_DB_TYPE=postgres
+DEV_WORKFLOW_DB_URL=postgresql://user:pass@localhost:5432/devworkflow
 ```
 
-#### 🛠️ Database Schema Normalization (Postgres/MySQL)
-To ensure compatibility with existing reporting dashboards, the `PostgresAdapter` and `MysqlAdapter` automatically normalize column names:
-- `task_description` → DB column: `description`
-- `timestamp` → DB column: `completed_at`
-
-The adapters use aliases in queries so the MCP tools still receive the expected `task_description` and `timestamp` fields.
-
-#### 👤 User ID Handling (Postgres/MySQL)
-These databases use an `INTEGER` column for `user_id`.
-- **Numeric strings** (e.g., `"1"`) are parsed directly into integers.
-- **Non-numeric strings** (e.g., `"programinglive"`) are automatically hashed into a consistent, positive integer to ensure compatibility with the schema while maintaining unique user isolation.
+| Var | Default | Deskripsi |
+|---|---|---|
+| `DEV_WORKFLOW_DB_TYPE` | `sqlite` | `sqlite`, `mysql`, atau `postgres` |
+| `DEV_WORKFLOW_DB_URL` | — | Connection string (untuk MySQL/Postgres) |
+| `DEV_WORKFLOW_DB_PATH` | `.state/dev-workflow.db` | Path SQLite (opsional) |
+| `DEV_WORKFLOW_USER_ID` | auto-generated | ID user untuk isolasi multi-user |
+| `DEV_WORKFLOW_STATE_FILE` | auto-resolve | Path override workflow-state.json |
 
+### Project-Specific State
 
-### User & State Management
+Setiap project punya workflow state sendiri di `.state/users/<user-id>/workflow-state.json`. File ini otomatis di-gitignore.
 
-| 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"
-      }
-    }
-  }
-}
-```
+Untuk isolasi multi-client (misal Windsurf + Antigravity pakai state terpisah):
 
-**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"
-      }
+      "args": ["path/to/index.js"],
+      "env": { "DEV_WORKFLOW_USER_ID": "windsurf" }
     }
   }
 }
 ```
 
+---
 
+## 🧰 One-Command Stack Setup (OpenCode V2)
 
-### ✅ Testing
-
-The project uses Node.js native test runner (`node --test`).
+`scripts/setup-stack.js` installs the whole AI agent stack: the dev-workflow MCP
+server, [obra/superpowers](https://github.com/obra/superpowers) skills, and
+[RTK](https://github.com/rtk-ai/rtk) token compression.
 
 ```bash
-npm test
+node scripts/setup-stack.js      # any platform
 ```
 
-This runs:
-- Unit tests for workflow logic
-- Integration tests for `.env` configuration
-- DB Adapter tests (SQLite always; MySQL/Postgres if configured)
+Platform wrappers (they only install RTK, run `npm install`, then delegate):
 
-#### Testing Database Adapters
-To verify MySQL or PostgreSQL adapters, run tests with the environment variable set:
+```powershell
+pwsh scripts/bootstrap-windows.ps1
+```
 
 ```bash
-# Test MySQL
-export DEV_WORKFLOW_DB_URL="mysql://root:pass@localhost:3306/test_db"
-node --test tests/db-adapters.test.js
-
-# Test PostgreSQL
-export DEV_WORKFLOW_DB_URL="postgres://postgres:pass@localhost:5432/test_db"
-node --test tests/db-adapters.test.js
+bash scripts/bootstrap-unix.sh
 ```
 
-### Scripts
-
-- `npm run build` - Bundle the source into `dist/index.mjs` for distribution
-- `npm run dev` - Run in development mode with file watching
-- `npm run local` - Alias for running from source (same as `npm start`)
-- `npm run web` - Launch the lightweight workflow dashboard for browsing task history (see [Web Dashboard docs](./docs/web-dashboard.md))
-
-#### `npm run web`
-
-This command starts the dashboard defined in `web/server.js`, giving you a quick view of workflow history and summary statistics.
+### What it does
+
+1. **Finds the real config directory.** Runs `opencode debug paths` and uses the
+   reported `config` path. OpenCode V2 resolves this to `~/.config/opencode` on
+   **every** platform, including Windows - `%APPDATA%\opencode` is not read.
+2. **Backs up `opencode.json`** to `secrets/opencode-backup-<timestamp>.json`
+   before touching it.
+3. **Registers Superpowers** under the V2 `plugins` key (the V1 `plugin` key is
+   deprecated and ignored by V2).
+4. **Registers the MCP server** under `mcp.servers` via `opencode mcp add`, which
+   writes a schema-valid `Mcp.LocalConfigEncoded` entry.
+5. **Installs dependencies.** Without `npm install` the server dies at startup
+   with `ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`.
+6. **Smoke tests the server**, then verifies with `opencode mcp list` and
+   `opencode plugin list`. Exits non-zero when any check fails, so a broken
+   install can no longer report success.
+7. **Creates `AGENTS.md`** in the current project if missing.
+
+### Tests
 
 ```bash
-npm run web
-# 🌐 Dev Workflow Dashboard running at http://localhost:3111
+npm test                            # full suite
+node --test tests/setup-stack.test.js
 ```
 
-- **Default port:** 3111 (or the next free port if occupied).
-- **Environment overrides:** Honors `PORT` (common on hosts like Plesk/Render) or `DEV_WORKFLOW_WEB_PORT` before falling back to auto-selection.
-- **Query parameter:** `?user=<id>` lets you inspect another user’s history (defaults to `default`).
-- **API endpoints:**
-  - `GET /api/version` → current package version from `package.json` (used by dashboard to display version dynamically).
-  - `GET /api/summary?user=<id>` → overall stats for the user.
-  - `GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` → paginated task history.
-  - `GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly` → aggregated counts over time.
-
-Open `http://localhost:3111` in a browser to view the dashboard UI (`web/index.html`).
-
-### Build Output
-
-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.
+`tests/test-helpers.js` exports `stripNpmNotices()`, which removes npm's own
+`npm warn`/`npm notice` chatter and Rollup's third-party annotation warnings from
+captured stderr before the build test asserts on it. Without it, a clean build
+could look broken on machines with a user-level `.npmrc` or with dependency
+versions that emit annotation warnings.
 
-### Usage
+### CI
 
-For MCP server usage, point your client at `index.js` (source) to avoid stdio transport compatibility issues. The built `dist/index.mjs` is primarily for:
-- npm package distribution
-- Performance optimization
-- Embedding in other projects
+`.github/workflows/ci.yml` runs on the **self-hosted runner on MMCH**, not on
+GitHub-hosted minutes:
 
-### MCP Tools Registry (Publishing)
-
-This package is configured for the official MCP Tools Registry using **npm package deployment**:
-
-- `package.json` declares `mcpName: "io.github.programinglive/dev-workflow-mcp-server"`.
-- `server.json` describes the server and links it to the npm package `@programinglive/dev-workflow-mcp-server`.
-
-To publish a new server version to the registry:
-
-1. Release a new npm version (for example):
-   - `npm test`
-   - `npm run release:patch` (runs your existing release pipeline and publishes to npm)
-2. Verify the new version exists on npm:
-   - `npm view @programinglive/dev-workflow-mcp-server version`
-3. Install the MCP publisher CLI (once per machine):
-   - `brew install mcp-publisher` (or follow the docs at https://modelcontextprotocol.info/tools/registry/publishing/)
-4. From this repo root, authenticate and publish:
-   - `mcp-publisher login github`
-   - `mcp-publisher publish`
-5. Optionally verify in the registry:
-   - `curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.programinglive/dev-workflow-mcp-server"`
-
-#### 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\"}"
+```yaml
+runs-on: [self-hosted, windows, mmch]
 ```
 
-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:
-
-- **Stores workflow history** specific to that project
-- **Tracks task progress** independently per project
-- **Should be gitignored** (already in `.gitignore` by default)
-- **Persists across sessions** so your workflow state is preserved
-- **Stays centralized** even if you run the server from nested build outputs like `dist/`. The MCP server walks back to the project root (looking for `.git` or `package.json`) before reading or writing workflow state, so you never need duplicate copies under build directories.
-
-Each project maintains its own isolated workflow history, so you can work on multiple projects without mixing their histories. Within that `.state` directory, the MCP server automatically creates a unique per-user subdirectory (e.g., `.state/users/user-abc123/`). The generated identifier persists locally so multiple developers sharing the same repository never clobber each other’s workflow files. If you prefer a specific name, set `DEV_WORKFLOW_USER_ID` before launching the server and that value will be used instead of the auto-generated ID.
+Two jobs:
 
-#### Choosing a User ID
+| Job | Steps |
+|---|---|
+| `test` | `npm ci` → `npm test` → `build:server` → `npm audit --omit=dev --audit-level=high` → setup-stack suite |
+| `web` | `npm ci` in `web/` → static export build → verify `out/index.html` and CSS size → `npm audit --audit-level=high` |
 
-Use cases:
+The `web` job exists because the dashboard is deployed to Netlify from `web/`
+and previously had no CI coverage at all. The CSS size check catches a Tailwind
+regression that a green build would otherwise hide.
 
-1. **Let the server choose** – Do nothing and the first time you run any MCP tool the server creates `.state/users/<random-id>/`. The dashboard `User ID` filter accepts that value (visible in the folder name or in workflow responses).
-2. **Set an explicit ID** – Before starting the server, export `DEV_WORKFLOW_USER_ID`:
+A pull request cannot merge green if either job fails.
 
-   ```bash
-   # macOS/Linux
-   export DEV_WORKFLOW_USER_ID=alice
-   node index.js
+Runner provisioning and troubleshooting are documented in
+[docs/homelab/ci-runner.md](./docs/homelab/ci-runner.md).
 
-   # Windows PowerShell
-   $env:DEV_WORKFLOW_USER_ID = "alice"
-   node index.js
-   ```
+### Dependency hygiene
 
-   Now all history for that session lands in `.state/users/alice/` and the dashboard can be filtered with `alice`.
-3. **Multiple users on one host** – Run separate processes (or MCP clients) with different `DEV_WORKFLOW_USER_ID` values. Each user’s workflow state remains isolated.
-
-> **Tip:** The web dashboard simply reads existing records. Typing a new value into the `User ID` filter will only return results after a workflow session has written history into `.state/users/<that-id>/`.
-
-### Adding to .gitignore
-
-If you're using this package, add this to your project's `.gitignore`:
-
-```
-.state/
+```bash
+npm audit                 # full tree (production + dev)
+npm audit --omit=dev      # production only
 ```
 
-This keeps workflow state local to each developer's machine.
+Both report `0 vulnerabilities`. `tar` is pinned via `overrides` in
+`package.json`; bump that pin when a new advisory lands rather than relying on
+the transitive range.
 
-> **Need to override the location?** Set `DEV_WORKFLOW_STATE_FILE=/absolute/path/to/your/project/.state/workflow-state.json` before launching the server (or inside your MCP client config). The server will honor that path, letting you keep the package installed centrally while maintaining per-project workflow history.
+The root `tailwindcss` devDependency was removed: it was added when the web
+dashboard still shipped a static HTML page, but that build step no longer
+exists. The dashboard under `web/` has its own Tailwind setup
+(`web/tailwind.config.ts`). The root `tailwind.config.js` pointed `content` at
+`web/public/**/*.{html,js}`, a directory that holds only SVG icons, so it
+generated nothing and was referenced by no script.
 
-## 🛠️ Available Tools
+---
 
-- `start_task` - Begin a new coding task
-- `mark_bug_fixed` - Mark the feature/bug as fixed (requires tests next)
-- `create_tests` - Mark that tests have been created
-- `skip_tests` - Skip tests with justification
-- `run_tests` - Record test results (must pass to proceed)
-- `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 (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
-- `get_workflow_status` - Show current status
-- `view_history` - View completed tasks
-- `continue_workflow` - Get next-step guidance
-- `rerun_workflow` - Reset and restart the current task from the beginning
-- `run_full_workflow` - Execute every workflow step in sequence with a single command (requires supplying the details for each phase)
-
-### `run_full_workflow`
-
-Use this when you already have all the information needed for each workflow phase and want to execute them in one go.
+## Release Workflow
 
-```json
-{
-  "summary": "Add payment webhooks",
-  "testCommand": "npm test",
-  "documentationType": "README",
-  "documentationSummary": "Document webhook configuration",
-  "commitMessage": "feat: add payment webhooks",
-  "releaseCommand": "npm run release:minor",
-  "releaseNotes": "Release webhook support",
-  "branch": "feature/payments",
-  "testsPassed": true,
-  "testDetails": "node --test; 42 tests",
-  "releaseType": "minor",
-  "preset": "minor"
-}
-```
+`.github/workflows/github-release.yml` runs on a `v*` tag and is split in two:
 
-The tool will:
+| Job | Runner | What it does |
+|---|---|---|
+| `build` | self-hosted MMCH | `npm ci` -> `npm test` -> `build:server` -> verify the built bundle starts -> `npm pack` -> upload tarball + metadata |
+| `publish` | `ubuntu-latest` | download tarball -> `npm publish --provenance` -> create/update the GitHub release |
 
-1. `mark_bug_fixed` using `summary`
-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`
-   - 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`
+**Why publish is not on MMCH:** npm provenance requires a supported cloud CI/CD
+provider with a **cloud-hosted** runner
+([docs](https://docs.npmjs.com/generating-provenance-statements)). A self-hosted
+runner cannot produce an attestation, so `--provenance` would have to be dropped
+and consumers would lose the ability to verify which commit the package was
+built from.
 
-All arguments except the optional flags are required and must be non-empty strings.
+The split keeps the expensive part - install, test, build, pack - on our own
+hardware, and spends hosted minutes only on a single publish step that runs when
+a release tag is pushed. Pull requests never touch the hosted runner.
 
-### Documentation Requirements
+Publishing authenticates through **npm Trusted Publishing (OIDC)** - no
+`NPM_TOKEN` secret is required, and `id-token: write` plus `registry-url` on
+`setup-node` is the whole configuration.
 
-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.
+### What goes into the package
 
-## 🚫 Releasing Without the Workflow Steps
+`.npmignore` keeps the published tarball to the runtime server: roughly 60 files
+and 65 kB. It excludes `.env*` (only `.env.example` ships), `.state/`, tests,
+CI config, `web/`, and docs. Without it npm falls back to `.gitignore`, which
+still allows tracked files such as `.env.production` into the tarball.
 
-The package ships with a release guard (`release-wrapper.js`) that backs the `npm run release:*` scripts. The guard refuses to run unless:
+`scripts/install-husky.js` runs from `prepare`. It installs git hooks only when
+a `.git` directory is present, so installing the package from the registry as a
+dependency does not fail on husky. The `husky || true` idiom is not portable to
+Windows, where npm runs scripts through `cmd.exe`.
 
-- 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:
+## 🏠 Homelab Development Guide
 
-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`.
+Repo ini juga berisi panduan konfigurasi homelab internal **programinglive** — Tailscale + SSH antar 3 mesin (MMCH, HELLOWORLD, Mac).
 
-### Automated npm Publishing
+| Dokumen | Isi |
+|---|---|
+| [docs/homelab/README.md](./docs/homelab/README.md) | Overview & quick reference |
+| [docs/homelab/infra-tailnet-ssh.md](./docs/homelab/infra-tailnet-ssh.md) | Tailnet + SSH setup lengkap |
+| [docs/homelab/cli-tools.md](./docs/homelab/cli-tools.md) | CLI tools per machine |
+| [docs/homelab/ci-runner.md](./docs/homelab/ci-runner.md) | Self-hosted CI runner di MMCH |
+| [docs/homelab/security-rules.md](./docs/homelab/security-rules.md) | Aturan keamanan |
+| [.agent/workflows/homelab-setup.md](./.agent/workflows/homelab-setup.md) | Workflow MCP untuk onboarding mesin baru |
 
-This repository ships with `.github/workflows/npm-publish.yml`, which publishes the package to npm whenever a git tag matching `v*` is pushed (for example, `v1.1.14`). To enable the workflow:
+> ⚠️ Repo ini **private**. Jangan bagikan ke publik.
 
-1. Create an npm automation token with publish rights (`npm token create --read-only false`).
-2. In the repository settings, add a secret named **`NPM_TOKEN`** containing that token.
-3. Ensure your release process pushes tags after running `npm run release:<type>` so the workflow triggers.
-4. Confirm `npm run build` succeeds locally; the workflow runs the build before publishing so broken bundles block the release.
-5. GitHub provenance is enabled via `npm publish --provenance`. Leave GitHub Actions' default OIDC permissions enabled so the job can request an ID token.
-6. Keep the `repository.url` field in `package.json` pointing at this GitHub repo. Provenance validation fails if it does not match the repository that built the package.
+---
 
-The workflow verifies that the tag version matches `package.json` before publishing and fails fast if they diverge.
+## 🚫 What This Server Prevents
 
-## 🛠️ Available Tools
+- ❌ Commit tanpa tests
+- ❌ Commit dengan tests yang fail
+- ❌ Commit tanpa dokumentasi
+- ❌ Lupa langkah workflow
+- ❌ Release tanpa commit & push
 
-### Tool Argument Requirements
+---
 
-All tool invocations validate their `arguments` payload before running:
-- Strings are parsed as JSON and must resolve to an object (key/value pairs).
-- Passing non-object data (numbers, arrays, plain text) triggers a guidance error.
-- Missing or malformed arguments safely default to empty input so the tool can respond with actionable reminders.
+## 💡 Tips
 
-Example (stringified JSON object):
-```
-{
-  "name": "start_task",
-  "arguments": "{\"description\":\"Add reporting endpoint\",\"type\":\"feature\"}"
-}
-```
+1. Selalu mulai dengan `start_task` — ini yang set intention kamu
+2. Jangan skip tests kecuali darurat — pakai `skip_tests` dengan alasan jelas
+3. Pakai `get_workflow_status` kapanpun untuk cek progress
+4. `run_full_workflow` = shortcut untuk task sederhana yang semua datanya sudah siap
+5. Untuk docs-only task, gunakan `skip_release` daripada memaksakan release
 
-### `start_task`
-Start a new coding task. This is your first step - be conscious about what you're coding.
+---
 
-**Parameters:**
-- `description` (string, required): Clear description of what you're going to code
-- `type` (enum, required): Type of task - "feature", "bugfix", "refactor", or "other"
+## 🧪 Run Tests
 
-**Example:**
-```
-Use the start_task tool with:
-- description: "Add user authentication to the login page"
-- type: "feature"
+```bash
+npm test
 ```
 
-### `mark_bug_fixed`
-Mark that the bug/feature is fixed. **Reminder: Now you MUST create tests!**
-
-**Parameters:**
-- `summary` (string, required): Brief summary of what was fixed/implemented
-
-### `create_tests`
-Confirm that you've created the necessary tests covering your change. Required before recording test results.
-
-**Parameters:** _none_
-
-### `skip_tests`
-Record an explicit justification when automated tests aren't feasible. Marks testing as satisfied so you can proceed with documentation and verification, while flagging the task for manual QA.
-
-**Parameters:**
-- `reason` (string, required): Why automated tests were skipped
-
-### `run_tests`
-Record test results. **NEVER commit if tests fail!** Only proceed if all tests are green.
-
-**Parameters:**
-- `passed` (boolean, required): Did all tests pass?
-- `testCommand` (string, required): The test command that was run
-- `details` (string, optional): Test results details
-
-**Example:**
 ```
-Use run_tests with:
-- passed: true
-- testCommand: "npm test"
-- details: "All 15 tests passed"
+ℹ tests 112
+ℹ pass 110
+ℹ fail 0
+ℹ skipped 2
 ```
 
-### `create_documentation`
-Mark that documentation has been created/updated. This is required before committing.
-
-**Parameters:**
-- `documentationType` (enum, required): "PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", or "other"
-- `summary` (string, required): What was documented
-
-### `check_ready_to_commit`
-Check if all workflow steps are completed and you're ready to commit & push.
-
-### `commit_and_push`
-Automatically run `git add`, `git commit`, and `git push` after the ready check passes.
-
-**Auto-detection of primary branch:** If no `branch` is specified, the tool automatically detects your project's primary branch by checking for `origin/main` first, then falling back to `origin/master`. This eliminates the need to specify the branch parameter for most projects.
-
-**Parameters:**
-- `commitMessage` (string, required): Conventional commit message to use
-- `branch` (string, optional): Target branch to push. If omitted, auto-detects primary branch (main or master)
-
-### `perform_release`
-Record the release after you've committed and pushed. Required before you can complete the task.
-
-**Parameters:**
-- `command` (string, required): Release command that was executed (e.g., `npm run release`)
-- `notes` (string, optional): Additional release notes
-
-### `complete_task`
-Mark the task as complete after successful commit & push. Resets workflow for next task.
-
-**Parameters:**
-- `commitMessage` (string, required): The commit message used
-
-### `drop_task`
-Abandon the current task without completing the workflow. Preserves an audit entry with context, then resets the state so you can start fresh.
-
-**Parameters:**
-- `reason` (string, optional): Additional detail about why the task was dropped
-
-### `get_workflow_status`
-Get current workflow status and what needs to be done next.
-
-### `view_history`
-View workflow history of completed tasks.
-
-**Parameters:**
-- `limit` (number, optional): Number of recent tasks to show (default: 10)
-
-## 📋 Available Prompts
-
-### `workflow_reminder`
-Get a complete reminder of the development workflow discipline.
-
-### `pre_commit_checklist`
-Get a pre-commit checklist to ensure nothing is missed before committing.
-
-## 🔄 Typical Workflow
-
-Here's how you'd use this MCP server in a typical coding session:
-
-1. **Start your task:**
-   ```
-   Ask Cascade to use start_task:
-   "Start a new task: implementing user profile page, type: feature"
-   ```
-
-2. **Code your feature/fix**
-   - Write your code as usual
+The two skipped tests are the MySQL and PostgreSQL adapters, which need a real
+database connection (`MYSQL_URL` / `PG_URL`). Everything else, including the
+SQLite adapter, runs.
 
-3. **Mark as fixed:**
-   ```
-   "Mark the feature as fixed: User profile page with avatar and bio completed"
-   ```
+If a Windows install fails on a native module, it is almost always a missing
+prebuild for your Node ABI rather than a broken test - see
+[docs/homelab/ci-runner.md](./docs/homelab/ci-runner.md#troubleshooting).
 
-4. **Create tests:**
-   - Write your tests
-   - The server will remind you this is mandatory!
+---
 
-5. **Run tests:**
-   ```
-   "Record test results: passed=true, command='npm test'"
-   ```
-   - If tests fail, the server will **block** you from proceeding!
+## 📦 Build
 
-7. **Document:**
-   ```
-   "Create documentation: type=README, summary='Added user profile section to docs'"
-   ```
-
-8. **Check readiness:**
-   ```
-   "Check if I'm ready to commit"
-   ```
-
-9. **Commit & Push:**
-   ```
-   "Commit and push: commitMessage='feat: add user profile page with tests and docs'"
-   ```
-
-10. **Record release:**
-   ```
-   "Record release: command='npm run release', notes='v1.2.3'"
-   ```
-
-11. **Complete:**
-   ```
-   "Complete the task with commit message: 'feat: add user profile page'"
-   ```
-
-12. **Drop task (optional):**
-   ```
-   "Drop task: reason='Switching to a different feature'"
-   ```
-
-## 🎯 Key Features
-
-- **Enforces discipline**: Won't let you skip steps
-- **Test-driven**: Blocks commits if tests fail
-- **Documentation reminder**: Ensures you document your work
-- **State tracking**: Remembers where you are in the workflow
-- **History**: Keeps track of completed tasks
-- **Prompts**: Quick reminders of best practices
-
-## 🚫 What This Server Prevents
-
-- ❌ Committing without tests
-- ❌ Committing with failing tests
-- ❌ Committing without documentation
-- ❌ Losing track of what you're working on
-- ❌ Skipping important workflow steps
-
-## 💡 Tips
-
-1. **Always start with `start_task`** - This sets your intention
-2. **Never skip tests without justification** - Use `skip_tests` only when absolutely necessary and document the reason for manual QA
-3. **Use `get_workflow_status`** - Check where you are anytime
-4. **Review history** - Learn from your past tasks
-5. **Follow the prompts** - They contain best practices
-
-## 🔧 Customization
-
-You can modify the workflow in `index.js`:
-- Add more workflow phases
-- Customize reminders
-- Add integration with your test runner
-- Add custom validation rules
-
-## 📝 State Management
-
-The server maintains state in `.state/workflow-state.json`:
-- Current phase
-- Task description
-- Completion status of each step
-- History of completed tasks
-
-This file is automatically created and managed by the server.
-It contains local, machine-specific progress and is ignored by git so each environment can manage its own workflow history without cross-contamination.
+```bash
+npm run build    # → dist/index.mjs (optimized bundle)
+npm run web      # → dashboard di http://localhost:3111
+```
 
-## 🤝 Integration with Your Rules
+Build output主要用于 npm distribution. Untuk MCP usage, gunakan source `index.js` langsung (lebih cepat startup).
 
-This MCP server aligns with your existing development rules:
-- ✅ Enforces test-first discipline
-- ✅ Prevents commits with failing tests
-- ✅ Reminds about documentation
-- ✅ Tracks workflow state
-- ✅ Maintains history
+---
 
 ## 📄 License
 
 MIT
-
-## 🙏 Contributing
-
-Feel free to customize this server to match your specific workflow needs!
-
-## 📜 Project Governance
-
-- [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [Contributing Guide](./CONTRIBUTING.md)
-- [Security Policy](./SECURITY.md)
-- [License](./LICENSE)