refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan)

[kiki830621]

Refactor Opportunity

Source: surfaced during /idd-plan #28 tangential sweep (Step 2.5)

#28 將寫一個 scripts/check-ralph-loop.sh POSIX-portable detector,#27 (Source Type Adapter fail-fast) 也需要類似的「detect MCP plugin 存在」邏輯。兩處共用 abstraction 候選:

scripts/check-plugin-presence.sh <plugin-name> [marketplace]
  → exit 0 if installed, exit 1 if missing
  → 印出 detect path 讓 user debug
  → 認 IDD_SKIP_PLUGIN_CHECK env var escape hatch

#27 detect 4 個 source-type MCP plugins (che-word-mcp / che-telegram-mcp / che-apple-mail-mcp / che-apple-notes-mcp),#28 detect 1 個 ralph-loop。共 5 個 caller。

When to do

#28 implement 完成、#27 進 implement 之前。不在 #28 內做(避免 scope creep + #28 自己只用 1 次,還沒到該抽 abstraction 的訊號)。

#27 implement 第一步:看 #28 的 helper,若可平移為 generic version 就 refactor;若不能(detect logic 本質不同)則 #27 寫獨立 helper,本 issue close 為「natural emergence didn't materialize」。

Type

refactor

Priority: P3 (Code quality, not blocker)

Related

• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (helper origin)
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (potential reuser)

---

Current Status

Phase: closed
Last updated: 2026-05-07 by idd-close

Resolution

• PR cluster: #27 source-type adapter fail-fast + #34 generic plugin-presence helper (Plan tier) #39 merged → main
• cluster with bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — refactored to generic check-plugin-presence.sh + ralph-loop wrapper (backward compat)

[kiki830621]

Diagnosis (cluster with #34)

Type

bug (UX / error-reporting) — refactored from #28 helper pattern via #34

Analysis

#27 提出 idd-issue Step 1 Source Type Adapter 在 MCP plugin 缺失時應 fail-fast + 提示 install 指令。#32 已 absorb 入 #27 提供具體 error format spec (3-option block, structured stderr message)。#34 提議從 #28 抽 generic helper。

Cluster decision (#27 + #34 一起做): refactor 是自然 emergence 而非預先 abstraction —#28 已寫了 1 個 detect helper, #27 implement 即將寫第 2 個 detect helper (4 source-type MCP plugins),滿足 IDD「3 instance 才抽 abstraction」邊界(2 instance 足夠看出 pattern,且 #34 已 file 為 explicit refactor candidate)。

Strategy (cluster-PR, single branch)

• Refactor (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34) — abstract scripts/check-plugin-presence.sh
  • Generic 版本接受 <marketplace> <plugin-name> 參數
  • 維持 nullglob + bash array pattern (F3 fix from feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 verify)
  • IDD_SKIP_PLUGIN_CHECK env var (取代 IDD_SKIP_RALPH_CHECK)
  • 同樣的 stderr warning + install hint format
• Migrate (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34) — scripts/check-ralph-loop.sh 變成 wrapper
  • 1-line wrapper: exec "$(dirname "$0")/check-plugin-presence.sh" claude-plugins-official ralph-loop "$@"
  • 保留 backward compat (idd-verify Step 0a + idd-all Phase 0.6 不需改)
• Implement (bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27) — idd-issue Step 1 Source Type Adapter fail-fast
  • 在 4 source type case (.docx / Telegram / Apple Mail / Apple Notes) 入口 invoke check-plugin-presence.sh <marketplace> <plugin>
  • Missing → print structured error (per docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 spec):明確 cause + 3 options + abort
  • 4 messages 結構一致,只差 plugin name + marketplace
  • 直接貼純文字 / .md 不 trigger detect (no plugin needed)

Files to change

File	Change	Issue
plugins/issue-driven-dev/scripts/check-plugin-presence.sh (NEW)	generic helper	#34
plugins/issue-driven-dev/scripts/check-ralph-loop.sh	refactor to wrapper	#34
plugins/issue-driven-dev/skills/idd-issue/SKILL.md	Step 1 Source Type Adapter 加 detect calls + structured error	#27

Complexity

Plan

• ✅ 2+ files 順序依賴 (helper 先 / wrapper 後 / idd-issue 用 helper)
• ✅ Decision-heavy:keep check-ralph-loop.sh as wrapper vs delete + 改 idd-verify/idd-all → 選 wrapper(backward compat,已 merged 6aec214)
• ✅ Risk-sensitive:Bundle 共用 helper,helper 改錯會同時 break feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (idd-verify --loop) 和 bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (idd-issue 4 source types)
• ✅ Cross-file refactor with no external API change (helper 是 internal)

但本 diagnose 已明確 strategy + decisions,可以借 user trust skip /idd-plan EnterPlanMode(同 #11 模式)— Plan tier deliberation 已在 diagnose 完成。

Risks

• High: helper 改錯會 cascade break feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 paths。Mitigation:test 4 cases — generic helper installed/missing × env-var bypass yes/no
• Medium: idd-issue Step 1 加 detect logic 太重 — 4 source type 各加 detect call,maintenance load。Mitigation:單 helper file,Step 1 prose 用 inline 1-liner per type
• Low: check-ralph-loop.sh wrapper 增加 1 layer indirection,bash invocation 開銷 negligible

Related

• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (parent — provides the original check-ralph-loop.sh pattern)
• docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 (absorbed into bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — provides error format spec)
• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 (great-parent — surfaced this concern)

[kiki830621]

Implementation Complete (cluster-PR for #27 + #34)

Checklist (synced)

• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 refactor: scripts/check-plugin-presence.sh (NEW generic) → commit b6d97bc
• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 backward-compat: scripts/check-ralph-loop.sh 變 wrapper(舊 IDD_SKIP_RALPH_CHECK=1 仍 honored) → commit b6d97bc
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 fail-fast: idd-issue/SKILL.md Step 1 加 MCP plugin presence pre-flight + structured error (per docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed acceptance criteria) → commit c7f23bf

Legend: - [x] done

Self-verify

• ✓ generic helper 4-case smoke test PASS:installed (exit 0) / missing (exit 1) / IDD_SKIP_PLUGIN_CHECK=1 + missing (exit 0 + warning) / usage error (exit 2)
• ✓ wrapper backward-compat:bash check-ralph-loop.sh 仍 work,legacy IDD_SKIP_RALPH_CHECK=1 env var 透過 wrapper export 為 IDD_SKIP_PLUGIN_CHECK=1
• ✓ idd-issue Step 1 4-row case statement 涵蓋 .docx / Telegram / Apple Mail / Apple Notes
• ✓ structured error message format 對齊 docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed spec
• ✓ README marketplace 對照表 row (psychquant-claude-plugins) 與 helper 引用 marketplace name 一致 (docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 fix prevented mismatch)

Changes (cluster, 3 files)

• b6d97bc refactor: 抽出 check-plugin-presence.sh generic + check-ralph-loop.sh 變 wrapper (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34)
• c7f23bf feat: idd-issue Step 1 MCP plugin presence pre-flight + structured fail-fast (bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27)

Files Changed

 .../scripts/check-plugin-presence.sh               | 72 ++++++++++++++++++++++
 .../issue-driven-dev/scripts/check-ralph-loop.sh   | 58 +++++------------
 plugins/issue-driven-dev/skills/idd-issue/SKILL.md | 50 +++++++++++++++
 3 files changed, 136 insertions(+), 44 deletions(-)

Scope Compliance

• ✅ 3 file change 對齊 cluster diagnose Strategy
• ✅ Backward compat preserved (feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 existing callers unchanged)
• ✅ Marketplace name psychquant-claude-plugins (per docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 verify-fix learning)

Next: verification pending (lightweight self-verify done; full 6-AI not used since refactor is mechanical + reuses #28 verified pattern)

[kiki830621]

Closing Summary (cluster #34 with #27)

Problem

#28 寫了 scripts/check-ralph-loop.sh POSIX-portable detector,#27 implement 即將寫第 2 個 detector(4 source-type MCP plugins fail-fast)。兩處共用 detect logic — 都檢查 ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.claude-plugin/plugin.json 路徑、都需 nullglob bash array、都需 IDD_SKIP_* env var escape hatch、都需 stderr warning + structured install hint。

不抽 generic helper → 兩 caller copy-paste,未來 fix(例如 path schema 升級)要全部 caller 同步改。

Root Cause

check-ralph-loop.sh 設計時(#28)只 1 instance,還不到該抽 abstraction 的訊號(IDD「不在沒見過 N instance 之前抽 abstraction」邊界)。當 #27 implement 觸發第 2 instance 時,該 refactor 為 generic helper。

#34 在 #28 plan tier tangential sweep 階段就 file 為 follow-up issue(預判此情境)。

Solution

Cluster-PR with #27:

#34 part:

• scripts/check-plugin-presence.sh (NEW generic) — 接受 <marketplace> <plugin> 參數
• scripts/check-ralph-loop.sh 變 1-line wrapper:exec "$(dirname "$0")/check-plugin-presence.sh" claude-plugins-official ralph-loop
• Backward compat:legacy IDD_SKIP_RALPH_CHECK=1 env var 仍 honored(wrapper export 為 IDD_SKIP_PLUGIN_CHECK=1)
• All feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 verify findings 攜帶過來:nullglob array (F3) + stderr warning on bypass (F4)

Verification

• Generic helper 4-case smoke test PASS:installed (exit 0) / missing (exit 1) / IDD_SKIP_PLUGIN_CHECK=1 + missing (exit 0 + warning) / usage error (exit 2)
• Wrapper backward compat:bash check-ralph-loop.sh 仍 work,feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 既有 callers (idd-verify Step 0a / idd-all Phase 0.6) 不需改
• Legacy env var:IDD_SKIP_RALPH_CHECK=1 透過 wrapper 仍 take effect

Changes

• b6d97bc refactor: 抽出 check-plugin-presence.sh generic helper + check-ralph-loop.sh 變 wrapper (Refs refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34)
• 77d7efe (squash on main) cluster PR cluster: #27 source-type adapter fail-fast + #34 generic plugin-presence helper (Plan tier) #39 merged

Validated emergence pattern

This refactor proves IDD's「不預先 abstract」紀律 — 不在 #28 寫 helper 時試圖把它做 generic,而是 file 為 #34 follow-up,等 #27 真要用第 2 instance 時自然 emerge。Caller 從 1 → 2 是 abstraction 該誕生的 evidence threshold。

Related (cluster)

• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (paired implement — first user of the new generic helper for source-type detect)
• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (great-parent — original 1-instance helper this refactor abstracts from)
• DA verify finding Challenge B (helper export function) — partially addressed: helper now generic + reusable across callers,但仍是 stand-alone script 不是 sourceable function (post-merge follow-up if N>2 callers)