Document macdoc HTML to PDF route#31
Open
kiki830621 wants to merge 1 commit into
Open
Conversation
kiki830621
added a commit
that referenced
this pull request
May 21, 2026
Two findings independently flagged by Codex (gpt-5.5) and the Devil's Advocate reviewer in /idd-verify ensemble. Both are in-scope per idd-verify Step 5a (本 issue 範圍但非阻擋性), so fixing within this PR-1 rather than spawning follow-ups. 1. recoveryCommand `&&` semantics bug (Codex P2 / DA Challenge #5): `pkill X && rm -rf <lock>` short-circuits when no X process exists. But that's exactly the orphan-lock case (crashed wrapper) — where the user most needs the lock cleanup to run. Changed `&&` to `; ` so both steps run regardless. Also extended `rm -rf` target to include `.lock.flock` (Linux flock-mode lock file) so the same recovery works on macOS and Linux. Fix appears in: - wrapper.sh:121 (recoveryCommand JSON field) - README.md:201-212 (recovery cookbook bash block) 2. README ## Version section drift (Codex P2): README line 234 still said `Plugin version: 1.3.0` after the v1.3.2 plugin.json/marketplace.json/CHANGELOG.md bump. Internal contradiction caught by Codex but missed by all 5 Claude reviewers (they checked the three-way sync between plugin.json / marketplace.json / CHANGELOG.md but didn't notice README has a fourth version reference). Updated to 1.3.2 and added v1.3.2 + v1.3.1 entries to README's inline changelog section. Tests still 4/4 GREEN after fix (test #4 just asserts `recoveryCommand starts with 'pkill'` which both `&&` and `; ` forms satisfy). Refs #31
Merged
5 tasks
kiki830621
added a commit
that referenced
this pull request
May 21, 2026
Empirical 2-session test in Claude Code (2026-05-22) confirmed Codex P1 + Devil's Advocate Challenge #1 prediction: Claude Code's MCP transport drops `id: null` JSON-RPC error responses as unmatched-id transport noise, even when the wrapper writes a perfectly-valid envelope to stdout. Result: user still sees generic `-32000`, not the human-readable error.message. Empirical test methodology (preserved for future reference): 1. cp plugin v1.3.2 wrapper into ~/.claude/plugins/cache/.../1.3.1/bin/ (override cached v1.3.1 wrapper in-place, no marketplace merge needed) 2. Open fresh Claude Code session; run /mcp 3. Observe: still `-32000`. ps shows fresh wrapper.sh processes were spawned (sub-100ms lifecycle), but Claude Code rendered the cached transport failure, not our envelope. 4. Manually invoke the swapped wrapper: it correctly emits valid JSON envelope to stdout — proving the issue is client-side rendering, not server-side emission. Fix (this commit): - New helper `read_initialize_id()`: reads first line of stdin with 2s timeout, extracts the initialize request's id field. Prefers jq for parsing; falls back to bash regex for environments without jq. Returns "null" literal on timeout / parse failure / missing id, so downstream behavior degrades to v1.3.2 fallback (better than -32000 baseline; same as before this commit). - Extended `emit_mcp_error_response(owner_pid, request_id)` to take request_id as second arg, substituted into JSON envelope `"id":<x>`. Numeric id printed unquoted, string id with JSON quotes, null literal. - Both lock-refused branches (flock + mkdir) now call read_initialize_id before emit_mcp_error_response, so the response id matches the request Claude Code's MCP client has pending. Tests: - Updated fake wrapper template to source both helpers + new call sequence - New test #5: feed `{"id":42, ...}` initialize to stdin → response.id == 42 - New test #6: empty stdin → falls back to null (preserves v1.3.2 behavior) - Existing tests #1-4 still GREEN (timeout fallback covers the no-stdin path identically to v1.3.2's hardcoded null) - Regression: test-wrapper-pid.sh 10/10 GREEN (unaffected — different lock state focus) - Manual canary: string id "abc-init-99" round-trips correctly Why 2-second stdin timeout: - Claude Code MCP transport sends initialize within ms of process spawn - Longer timeout (>5s) risks Claude Code's own transport timeout firing first and giving up on the wrapper - Shorter timeout (<1s) risks race with slow shell init on busy hosts - 2s = sweet spot per JSON-RPC over stdio convention Why jq + bash-regex fallback: - jq isn't a guaranteed plugin-runtime dependency - bash regex covers integer ids and quoted-string ids — the only forms MCP 1.0 + JSON-RPC 2.0 specs allow for `id` - Pre-PR-1b plan acknowledged this 2-step empirical approach explicitly: ship simple null-id first, observe Claude Code behavior, escalate to read-stdin only if needed. The escalation triggered today, as predicted. Refs #31
kiki830621
added a commit
that referenced
this pull request
May 22, 2026
…cal findings (#31) Updates the v1.3.2 entry to capture: - Full envelope schema (code / message / data fields) - PR-1b read_initialize_id() rationale: empirical 2-session test in Claude Code v2.1.148 showed id:null responses don't surface; matching id required + verified via --debug mcp log capture - Stdin id extraction strategy (jq + bash regex fallback for portability) - Test coverage expanded 4→6 cases - Known UX gap explicitly documented: /mcp short-list still shows truncated -32000, but the full error.message reaches Claude Code's internal MCP error state (proven via debug log line 1295) - Bumped date 2026-05-21 → 2026-05-22 to reflect PR-1b ship date This commit only touches CHANGELOG.md, no code changes. Refs #31
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
macdoc convert --to pdffor HTML/HTM input as a playwright Chromium route.Verification
jq empty plugins/macdoc/.claude-plugin/plugin.json .claude-plugin/marketplace.jsonrg "HTML→PDF|playwright Chromium|playwright install chromium" plugins/macdoc/skills/macdoc/SKILL.md plugins/macdoc/.claude-plugin/plugin.json .claude-plugin/marketplace.jsongit diff --checkRefs PsychQuant/macdoc#85