From 8f2ae6fc454074780cfeeee0b14a50076eb60b19 Mon Sep 17 00:00:00 2001 From: Ovidiu Galatan Date: Mon, 27 Jul 2026 17:22:44 +0300 Subject: [PATCH] docs(agents): fix broken steps and de-duplicate the instruction files WHAT: - CLAUDE.md collapses to `@AGENTS.md`. The two files were byte-identical except for one word, so AGENTS.md is now the single source of truth and the purpose line no longer names a specific agent. - Reshape "Commit discipline" into "Commits". The agents.md convention asks this section for runnable steps, so it now leads with the pre-commit commands the repo was missing and states plainly that nothing enforces them. The scope rule stays as one line, minus the release number and the unrelated SOCKS detail. - Drop the canary and dist-tag-rollback steps from the release gate. Nothing an agent reading this file ever performs; publishing is a human operation. - Replace the `npx mcp-wordpress-remote --help` smoke test. There is no argv handling anywhere in src/, so the binary starts the stdio server and hangs with no output. The step could never pass. It now checks that the packed dist/proxy.js is the tsup bundle rather than per-file output. - Correct "run all tests", which ran only tests/unit/ and silently skipped the three integration suites. - Add a Version section: package.json and MCP_WORDPRESS_REMOTE_VERSION in src/lib/config.ts must move together. WHY: Two copies of one file drift, and an edit to either would silently miss the other. The two commands were wrong in ways that only surface when someone trusts them: --help hangs, and "all tests" reported green while skipping a fifth of the suites. The version rule is not inferable from the code and has broken twice, once shipping a token directory named wordpress-remote-undefined. --- AGENTS.md | 17 ++++++++++------- CLAUDE.md | 33 +-------------------------------- 2 files changed, 11 insertions(+), 39 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 371a0b6..681329c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,29 @@ # mcp-wordpress-remote -MCP proxy server between Codex and a WordPress backend. +MCP proxy server between an MCP client and a WordPress backend. -## Commit discipline +## Commits -**Every line in a commit must trace to the stated goal.** No drive-by cleanups, no unrelated "improvements." The 0.2.20 race condition was caused by a harmless-looking capabilities change (`tools: {}` → `tools: { listChanged: false }`) bundled with an unrelated SOCKS proxy fix. Review every changed line — if it isn't required for the task, remove it before committing. +- Before committing, run `npm run check` and `npx jest tests/unit/ tests/integration/ --no-coverage`. CI runs the same steps on every PR (`.github/workflows/ci.yml`), so this only saves you the round trip — there is no pre-commit hook. +- Keep every line in a commit traceable to its stated goal. A one-token capabilities change (`tools: {}` → `tools: { listChanged: false }`) once rode along with an unrelated fix and caused a transport race. ## Pre-publish release gate "Works in repo" is not enough. Gate on "works from packed artifact in clean environment." 1. Build and pack: `npm ci && npm run build && npm pack` -2. Install tarball in a clean temp dir, run `npx mcp-wordpress-remote --help` +2. Install the tarball in a clean temp dir. Confirm `dist/proxy.js` is the tsup bundle (~2.4 MB single file), not per-file output — the binary has no `--help`, so it cannot be smoke-tested by invoking it bare 3. Test against a healthy WordPress endpoint (normal init + tools/list flow) 4. Test against a broken endpoint (fallback init, no malformed forwarding) 5. Debug logs: verify no forwarded requests fire before init settles -6. Publish canary first (`x.y.z-canary.1`), soak in real clients, then promote to latest -7. Know the last good version — be ready for immediate dist-tag rollback + +## Version + +The version lives in two places that must move together: `version` in `package.json` and `MCP_WORDPRESS_REMOTE_VERSION` in `src/lib/config.ts`. Letting them drift once shipped a token directory literally named `wordpress-remote-undefined`. The token store is namespaced by version, so any bump forces every user to re-authenticate. ## Testing -- Run all tests: `npx jest tests/unit/ --no-coverage` +- Run all tests: `npx jest tests/unit/ tests/integration/ --no-coverage` (`tests/unit/` alone skips the integration suites) - Build: `npm run build` - ESM mocking pattern: set `process.env` vars BEFORE `jest.resetModules()` + dynamic imports (CONFIG caches at import time) - WordPress API endpoint in nock: `/?rest_route=/wp/v2/wpmcp` (not `/wp/v2/wpmcp`) diff --git a/CLAUDE.md b/CLAUDE.md index e1be0dd..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,32 +1 @@ -# mcp-wordpress-remote - -MCP proxy server between Claude Code and a WordPress backend. - -## Commit discipline - -**Every line in a commit must trace to the stated goal.** No drive-by cleanups, no unrelated "improvements." The 0.2.20 race condition was caused by a harmless-looking capabilities change (`tools: {}` → `tools: { listChanged: false }`) bundled with an unrelated SOCKS proxy fix. Review every changed line — if it isn't required for the task, remove it before committing. - -## Pre-publish release gate - -"Works in repo" is not enough. Gate on "works from packed artifact in clean environment." - -1. Build and pack: `npm ci && npm run build && npm pack` -2. Install tarball in a clean temp dir, run `npx mcp-wordpress-remote --help` -3. Test against a healthy WordPress endpoint (normal init + tools/list flow) -4. Test against a broken endpoint (fallback init, no malformed forwarding) -5. Debug logs: verify no forwarded requests fire before init settles -6. Publish canary first (`x.y.z-canary.1`), soak in real clients, then promote to latest -7. Know the last good version — be ready for immediate dist-tag rollback - -## Testing - -- Run all tests: `npx jest tests/unit/ --no-coverage` -- Build: `npm run build` -- ESM mocking pattern: set `process.env` vars BEFORE `jest.resetModules()` + dynamic imports (CONFIG caches at import time) -- WordPress API endpoint in nock: `/?rest_route=/wp/v2/wpmcp` (not `/wp/v2/wpmcp`) - -## Architecture notes - -- Transport detection (JSON-RPC vs simple) runs during the `initialize` handler -- `sessionContext.transportType` starts null — the init-ready gate (`waitForInit`) blocks all handlers until detection settles -- `waitForInit` returns `InitResult` (`{ ready: true } | { ready: false; reason: 'failed' | 'timeout' }`) +@AGENTS.md