Skip to content

task_plan.md

Latest commit

 

History

History
139 lines (116 loc) · 10.5 KB

task_plan.md

File metadata and controls

139 lines (116 loc) · 10.5 KB
Raw

Task Plan: HD Optimizer Detective v2 Enhancements & Integrity Verification

Goal Statement

Enhance HD Optimizer Detective v2 UI and backend drill-down features according to user specifications without breaking any existing functionality, verifying zero regressions across all core features (Scan, Duplicate Locker, Treemap, Category Inspector, Terminal Script Generation, and System Protection Shield).

Architecture & Requirements Baseline

  • Tech Stack: Vanilla JS + CSS3 HTML5 frontend (app.js, styles.css, index.html), zero-dependency multi-threaded Python 3 backend (scanner_backend.py).
  • Core Requirements:
    1. Semi-transparent dark mode glow borders across all treemap categories (rgba(R, G, B, 0.35)).
    2. Enhanced Category Inspector modal drill-down supporting all 7 categories with real/scanned file aggregation and interactive ⚡ Flag buttons.
    3. Strict zero-regression guarantee across existing scan, duplicate selection, script export, and HTTP APIs.

Phases & Tasks

Phase 1: Planning & Baseline Verification

  • Create persistent planning files (task_plan.md, findings.md, progress.md).
  • Audit current codebase structure and active endpoints (/api/health, /api/scan, /api/drives, /api/system_hud).

Phase 2: Feature & UX Implementation Verification

  • Validate semi-transparent glowing borders styling in app.js and styles.css.
  • Validate Category Inspector file aggregator in app.js and table header in index.html.
  • Ensure hover effects and flag action handlers are fully functional without JS syntax errors.

Phase 3: Comprehensive Regression & Integration Testing

  • Verify backend HTTP server compilation (python3 -m py_compile scanner_backend.py).
  • Verify API endpoints return valid JSON response formats.
  • Verify frontend script generation (clean_junk.sh) produces valid bash syntax.

Phase 4: Final Reporting & Closure

  • Summarize plan execution in progress.md and findings.md.
  • Report completion back to user with clickable file references.

Phase 5: UI/UX Visual Polish (Soft Glows, Gradients & Micro-Animations)

  • Add subtle linear gradients and top-highlight strokes to Bento tiles and cards.
  • Add soft ambient glow effects to buttons, dial gauges, and status chips.
  • Add micro-animations (active press scale, hover sheen pass, soft breathing pulse on indicators).
  • Fixed grid span regression (.bento-span-8, .bento-span-4, etc.) to restore 12-column Bento layout.
  • Verified visual layout via live browser subagent screenshot.

Phase 6: Mouseleave Motion Calibration

  • Remove reverse sheen sweep on mouseleave (transition: none on exit).
  • Remove trailing transform ease-back shift on treemap/bento cards on cursor leave.
  • Verify instant crisp exit feedback in browser.

Phase 7: Apple-Style Interactive Storage Bar Component

  • Build multi-segmented Apple Storage Bar component with 2026 dark glass visual styling.
  • Add color-coded legend tags with live size calculation (Dev, AI Models, Media, PyCache, VMs, Archives, System).
  • Implement filterByStorageCategory() click handler to filter view & trigger Category Inspector drill-down.
  • Add ✕ Clear Filter state to restore unfiltered treemap dashboard view.
  • Verify interactivity and layout in browser.

Phase 8: Pure Real Disk Data Integrity (Purge Fake Mock Fallbacks)

  • Remove hardcoded mock path fallback arrays (Windows11_23H2_x64.iso, Ubuntu_24.04_LTS.vmdk) from app.js.
  • Update scanner_backend.py to aggregate real file sizes and scannedItems array across all categories.
  • Update openCategoryInspector() to query strictly real disk audit items or render clean empty state.
  • Verify backend compilation and API health.

Phase 9: Blazing-Fast APFS Spotlight & Parallel Multi-Threaded Indexing Engine

  • Implement Engine A: APFS Native Spotlight (mdfind) B-Tree Indexer for 0.05s instant querying on macOS.
  • Implement Engine B: Multi-Threaded Parallel os.scandir Worker Pool (ThreadPoolExecutor(max_workers=16)).
  • Implement Live File Verification & True Byte Audit (verifying file size & os.path.exists() before returning).
  • Verify execution speed and 100% data truthfulness.

Phase 10: Express Reclaim Deletion Audit Data Sync

  • Auto-flag duplicate copies and active strategies when opening Deletion Audit Preview modal from Reclaimable Space tile.
  • Sync total reclaimable capacity label in modal (e.g. 40.55 GB) with individual breakdown rows.
  • Support 1-click execution of both duplicate copy deletion and tactical junk strategy commands.
  • Verify modal data sync in browser.

Phase 11: Dynamic Path-Connected Apple Storage Bar (Premium Space Saver Engine)

  • Connect Storage Bar title & capacity header to current selected drive/path (scanPathInput.value).
  • Implement renderAppleStorageBar(data, targetPath) in app.js to compute dynamic proportional segment widths.
  • Dynamically update legend chips (.legend-chip) with exact real byte counts (formatBytes).
  • Hide/mute 0-byte categories in the current path so the bar represents 100% true active clutter.
  • Verify dynamic bar re-rendering across path selection in browser.

Phase 12: Comprehensive macOS Storage Bar Engine (Zero Empty State)

  • Integrate shutil.disk_usage(root_dir) in scanner_backend.py to retrieve total, used, and free disk bytes.
  • Catch all scanned files under robust categories (Dev, AI Models, Media, VMs, Archives, Apps & System Data, Free Space).
  • Render real multi-colored storage bar matching native macOS System Settings across all drives (~, /, custom).
  • Verify bar rendering in browser.

Phase 13: Modal Layout & Horizontal Scroll Elimination

  • Expand .modal-card width from 780px to 1050px (max-width: 1050px; width: 92vw;).
  • Set table-layout: fixed; width: 100%; on modal tables with explicit column width allocations.
  • Set word-break: break-all; on path columns to wrap long file paths cleanly without horizontal scrollbars.
  • Verify zero horizontal scrollbars across Category Inspector and Deletion Audit modals.

Phase 14: The Digital Archaeologist & 20-Signal Safety Engine

  • Build 20-Signal Confidence Weighting Engine in scanner_backend.py (0–100% confidence score + "Explain WHY" reasons array).
  • Group scanned disk clutter into Narrative Cleanup Stories (AI Workspace Debris, Installation Relics, Project Graveyard, Forgotten Downloads, Version Graveyard, Forgotten Relics).
  • Add tabArchaeologist ("Digital Archaeologist") view to index.html with liquid glass Story Cards and 3-Action Safety Buttons (Delete 🟢 | Compress 🟡 | Archive 🔵).
  • Add Story Inspector Modal (modalStoryInspector) displaying item confidence scores and "Future Probability" metrics.
  • Verify Digital Archaeologist functionality and UI in browser.

Phase 15: Error Isolation & Defensive Null-Safe Rendering (Fix Misleading Toast Bug)

  • Separate API fetch error handling from UI rendering error handling in runRealSystemDriveScan().
  • Wrap all array iterations (duplicates, strategies, treemapNodes, scannedItems, archaeologistStories) in defensive Array.isArray() checks.
  • Log exact UI stack trace to console when rendering exceptions occur instead of masking as "Backend connection offline".
  • Verify error isolation and clean scan handling in browser.

Phase 29: Immediate Skeleton Hydration (Eliminate Empty Black Container State)

  • Add renderScanningSkeletons() invoked instantly at second 0.0 when scan starts.
  • Render glowing glassmorphic skeleton tiles (.skeleton-tile with @keyframes skeletonShimmer) & live Radar Pulse indicator.
  • Eliminate the pitch-black empty container state during backend fetch.
  • Execute test_suite.py and commit 100% passing codebase to Git.

Phase 30: AAA Readiness, Safety & Professional Hardening

  • Audit API trust boundaries, destructive operations, validation, documentation, and accessibility.
  • Enforce localhost Host/origin checks, bounded JSON payloads, action allowlisting, and security headers.
  • Extend Protection Shield coverage to descendants of sensitive user directories.
  • Preserve originals during non-APFS archive fallback and stop reporting estimated savings as facts.
  • Prevent destination overwrites and honor configured launch ports.
  • Remove toast HTML injection and add skip navigation, focus visibility, live status, reduced motion, and stronger muted-text contrast.
  • Repair the Homebrew formula so it no longer advertises a placeholder URL/checksum; support --HEAD installs.
  • Run syntax, static diff, and live localhost security checks.

Phase 31: Agent-Workspace Product Pivot

  • Reposition ZeroSpace as an experimental local developer tool for agent-heavy workspaces.
  • Remove simulated startup scan results, hard-coded personal paths, and misleading banner placement.
  • Make the current repository workspace the initial suggested scan scope.
  • Replace AI/probability/safety guarantees with transparent rule-based review scores.
  • Default duplicate candidates to unselected and removal actions to Trash.
  • Disable permanent deletion and advanced mutation actions unless explicitly unlocked by environment variables.
  • Hide unrelated hardware, strategy, script, forecasting, and settings surfaces from primary navigation.
  • Rewrite the README around the agent-workspace problem, local trust model, and developer-grade distribution.

Phase 32: Snapshot Loading & Scan Interaction Reliability

  • Automatically load the selected workspace after drive discovery, never the unresolved placeholder path.
  • Cache up to four recent scan snapshots in server memory with a 10-minute default freshness window.
  • Make page reload reuse a fresh snapshot and make both scan buttons explicitly bypass the cache.
  • Show elapsed scan time, snapshot timestamp/age, timeout errors, and completion state in the UI.
  • Restore missing duplicates and strategies response fields that caused post-scan rendering to abort.
  • Prevent stale concurrent responses and duplicate button handlers from corrupting UI state.
  • Verify automatic load, cached reload, and forced refresh in the real browser.

Key Decisions & Constraints

  • Zero External Dependencies: Keep Python backend and JS frontend free of external library bloat.
  • Backward Compatibility: Preserve existing API contracts (/api/scan, /api/execute, /api/drives, /api/system_hud).