From a7a4abdfdefb204f6918779eaeafdcfb773dbf5d Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Mon, 4 May 2026 11:25:31 +0800 Subject: [PATCH] docs(25-02): complete plugin dashboard direct JSON read + doctor/repair Quick Actions --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 19 +-- .../25-02-SUMMARY.md | 116 ++++++++++++++++++ 4 files changed, 131 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/25-surface-convergence-doctor-repair/25-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 8ed7c2e6..f655163d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -32,7 +32,7 @@ Requirements for milestone v1.6: AI-Ready Literature Asset Foundation. - [ ] **SURF-01**: User sees the same lifecycle and health meaning in `paperforge status`, plugin dashboard, and generated Base views. - [ ] **SURF-02**: User can run repair and doctor flows that fix source artifacts first and then rebuild derived state, instead of patching the canonical index directly. -- [ ] **SURF-03**: User can use plugin dashboard actions as a thin shell over CLI commands, without JS re-implementing lifecycle or health rules. +- [x] **SURF-03**: User can use plugin dashboard actions as a thin shell over CLI commands, without JS re-implementing lifecycle or health rules. - [ ] **SURF-04**: User can open library queues and health views that are derived from the canonical index rather than duplicated filtering logic spread across the system. ### Maturity And AI Context @@ -96,7 +96,7 @@ Which phases cover which requirements. Updated during roadmap creation. | STATE-04 | Phase 24 | Complete | | SURF-01 | Phase 25 | Pending | | SURF-02 | Phase 25 | Pending | -| SURF-03 | Phase 25 | Pending | +| SURF-03 | Phase 25 | Complete | | SURF-04 | Phase 25 | Pending | | AIC-01 | Phase 24 | Complete | | AIC-02 | Phase 26 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e53b2f0d..f0e67598 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -102,7 +102,7 @@ Plans: Plans: - [ ] 25-01-PLAN.md — status --json source migration + doctor Index Health + brownfield detection -- [ ] 25-02-PLAN.md — Plugin dashboard direct JSON read + doctor/repair Quick Actions +- [x] 25-02-PLAN.md — Plugin dashboard direct JSON read + doctor/repair Quick Actions - [ ] 25-03-PLAN.md — Base views lifecycle columns + repair source-first rebuild pattern ### Phase 26: Traceable AI Context Packs diff --git a/.planning/STATE.md b/.planning/STATE.md index 6ecc5bab..8c382d6d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,13 +3,13 @@ gsd_state_version: 1.0 milestone: v1.6 milestone_name: AI-Ready Literature Asset Foundation status: Phase complete — ready for verification -stopped_at: Completed 24-01-PLAN.md -last_updated: "2026-05-04T02:38:22.553Z" +stopped_at: Completed 25-02-PLAN.md +last_updated: "2026-05-04T03:25:20.939Z" progress: total_phases: 5 - completed_phases: 2 - total_plans: 9 - completed_plans: 7 + completed_phases: 3 + total_plans: 12 + completed_plans: 9 --- # Project State @@ -53,6 +53,8 @@ Plan: 3 of 3 | Phase 23-canonical-asset-index-safe-rebuilds P01 | 7 min | 3 tasks | 3 files | | Phase 23-canonical-asset-index-safe-rebuilds P02 | 5 min | 3 tasks | 4 files | | Phase 23-canonical-asset-index-safe-rebuilds P03 | 8 min | 4 tasks | 5 files | +| Phase 24-derived-lifecycle-health-maturity P02 | 25min | 3 tasks | 2 files | +| Phase 25-surface-convergence-doctor-repair P02 | 2min | 2 tasks | 1 files | ## Accumulated Context @@ -70,6 +72,9 @@ Recent decisions affecting current work: - [Phase 23-canonical-asset-index-safe-rebuilds]: Lazy imports inside build_index avoid circular import between sync.py and asset_index.py - [Phase 23-canonical-asset-index-safe-rebuilds]: Orphaned-record cleanup stays in sync.py; only the core build loop moves to asset_index - [Phase 23-canonical-asset-index-safe-rebuilds]: OCR captures done keys before queue filter to pass to incremental refresh; deep-reading refreshes ALL records; repair triggers refresh for path and divergence fixes; run_index_refresh keeps full-rebuild default; incremental is opt-in from single-paper workers +- [Phase 24-derived-lifecycle-health-maturity]: Lazy import of asset_state functions inside _build_entry() follows existing pattern — avoids circular dependency risk with sync.py — Same pattern already used for ocr.py and sync.py imports in _build_entry() +- [Phase 24-derived-lifecycle-health-maturity]: Derived fields inserted after entry dict construction but before formal note write — keeps machine-only fields out of user-visible Obsidian note frontmatter — Lifecycle/health/maturity/next_step are machine-derived and should not appear in user-editable markdown frontmatter +- [Phase 25-surface-convergence-doctor-repair]: Plugin dashboard reads formal-library.json directly via readFileSync instead of spawning Python CLI — SURF-03 per D-05, D-06, D-07: plugin consumes same canonical semantics from canonical index ### Pending Todos @@ -82,6 +87,6 @@ None yet. ## Session Continuity -Last session: 2026-05-04T02:38:22.550Z -Stopped at: Completed 24-01-PLAN.md +Last session: 2026-05-04T03:25:20.936Z +Stopped at: Completed 25-02-PLAN.md Resume file: None diff --git a/.planning/phases/25-surface-convergence-doctor-repair/25-02-SUMMARY.md b/.planning/phases/25-surface-convergence-doctor-repair/25-02-SUMMARY.md new file mode 100644 index 00000000..465153a1 --- /dev/null +++ b/.planning/phases/25-surface-convergence-doctor-repair/25-02-SUMMARY.md @@ -0,0 +1,116 @@ +--- +phase: 25-surface-convergence-doctor-repair +plan: 02 +subsystem: plugin +tags: plugin, dashboard, formal-library, direct-json-read, quick-actions + +# Dependency graph +requires: + - phase: 23-canonical-asset-index-safe-rebuilds + provides: canonical formal-library.json with envelope format + - phase: 24-derived-lifecycle-health-maturity + provides: lifecycle, health, maturity, next_step fields in index +provides: + - Plugin dashboard reads formal-library.json directly via readFileSync + - Dashboard falls back to CLI spawn when index file is missing + - Doctor and repair as one-click Quick Action buttons +affects: [] + +# Tech tracking +tech-stack: + added: [] + patterns: + - Plugin reads canonical index JSON instead of spawning Python CLI + - Actions remain thin CLI shells (sync, ocr, doctor, repair) + +key-files: + created: [] + modified: + - paperforge/plugin/main.js + +key-decisions: + - "Use this.app.plugins.plugins['paperforge'].settings for system_dir instead of re-reading paperforge.json" + - "Keep version badge from cached CLI stats (index has schema_version, not package version)" + - "Single-pass aggregation loop computes all counts within one iteration (D-06)" + - "Actions grid CSS already handles 4 cards via auto-fit minmax(160px, 1fr) -- no CSS changes needed" + +patterns-established: + - "Plugin reads canonical index JSON directly via readFileSync for dashboard stats" + - "Plugin actions remain thin CLI shells: spawn python -m paperforge {cmd}" + - "CLI spawn fallback when canonical index file is missing or corrupt" + +requirements-completed: + - SURF-03 + +# Metrics +duration: 2min +completed: 2026-05-04 +--- + +# Phase 25: Surface Convergence Plan 02 — Plugin Dashboard Direct JSON Read + Doctor/Repair Quick Actions + +**Plugin dashboard reads formal-library.json directly via readFileSync instead of spawning Python CLI, with doctor and repair as one-click Quick Action buttons** + +## Performance + +- **Duration:** 2 min +- **Started:** 2026-05-04T11:22:28Z +- **Completed:** 2026-05-04T11:24:24Z +- **Tasks:** 2 +- **Files modified:** 1 + +## Accomplishments + +- Refactored `_fetchStats()` to read `formal-library.json` from `{vault}/{system_dir}/PaperForge/indexes/` via `fs.readFileSync` instead of spawning `python -m paperforge status --json` +- Single-pass aggregation loop computes paper count, lifecycle distribution, health aggregates, and OCR counts without holding references beyond loop scope (D-06) +- CLI spawn preserved as fallback when index file is missing or corrupt (D-07) +- Added `paperforge-doctor` Quick Action: runs `python -m paperforge doctor` +- Added `paperforge-repair` Quick Action: runs `python -m paperforge repair` +- ACTIONS array now has 4 entries (sync, ocr, doctor, repair) +- Existing `_runAction()` method handles new commands unchanged (thin CLI shell per SURF-03 / D-05) + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Refactor _fetchStats() to read canonical index JSON directly** - `86d142e` (feat) +2. **Task 2: Add doctor and repair as plugin Quick Action buttons** - `d143c2e` (feat) + +**Plan metadata:** `pending` (will be committed after state updates) + +## Files Created/Modified + +- `paperforge/plugin/main.js` — Refactored `_fetchStats()` for direct JSON read; added doctor/repair to ACTIONS + +## Decisions Made + +- Used `this.app.plugins.plugins['paperforge'].settings.system_dir` to access plugin settings from the view (standard Obsidian pattern — avoids changing view constructor or registration) +- Version badge shown from cached CLI stats (`this._cachedStats?.version`) since the index only carries `schema_version` (internal schema number, not package version) +- Single-pass loop computes all aggregates per D-06 (no item references retained after loop scope) +- No CSS changes needed — the actions grid already uses `grid-template-columns: repeat(auto-fit, minmax(160px, 1fr))` which auto-adapts to 4 cards + +## Deviations from Plan + +None — plan executed exactly as written. + +## Issues Encountered + +None + +## Next Phase Readiness + +- Ready for 25-03-PLAN.md: Base views lifecycle columns + repair source-first rebuild pattern +- Plugin dashboard now reads canonical index directly — no CLI spawn needed for normal operation +- Doctor and repair available as one-click dashboard actions + +## Self-Check: PASSED + +- [x] `paperforge/plugin/main.js` exists +- [x] Commit `86d142e` exists (feat: refactor _fetchStats) +- [x] Commit `d143c2e` exists (feat: add doctor and repair Quick Actions) +- [x] `25-02-SUMMARY.md` exists + +--- + +*Phase: 25-surface-convergence-doctor-repair* +*Completed: 2026-05-04*