feat: implement official repository queries and index fetching (Task 3.3)

- feat: add search_official() function with substring and optional fuzzy matching
- feat: add all_official() function to return all packages from index
- feat: add fetch_official_index() sync function using pacman -Sl
- feat: add fetch_official_index_async() with pacman-first, API-fallback strategy
- feat: add fetch_via_pacman() internal function for local package fetching
- feat: add fetch_via_api() internal function for Arch Packages API fetching
- feat: add fuzzy-search feature flag with fuzzy-matcher optional dependency
- change: update index module exports to include query and fetch functions
- change: update index module documentation with usage examples
- test: add unit tests for search_official() with various matching modes
- test: add unit tests for all_official() function
- test: add unit tests for fetch functions with graceful degradation
- docs: update INDEX_MODULE_PHASE.md to mark Task 3.3 as complete
- docs: update AUR_TOOLKIT_CRATE_PREPARATION.md with progress notes

Author: Firstp1ck

Cargo.lock

@@ -13,6 +13,7 @@ default = ["aur"]
 aur = ["dep:reqwest", "dep:tokio", "dep:scraper", "dep:chrono", "dep:rand", "dep:lru", "dep:async-trait"]
 deps = []  # No additional dependencies for types only
 index = ["dep:tokio"]  # For async operations with spawn_blocking
+fuzzy-search = ["dep:fuzzy-matcher"]  # Optional fuzzy matching for search
 cache-disk = ["dep:dirs"]
 
 [dependencies]
@@ -44,6 +45,9 @@ async-trait = { version = "0.1", optional = true }
 # Directory utilities (for cache-disk feature)
 dirs = { version = "5.0", optional = true }
 
+# Fuzzy matching (for fuzzy-search feature)
+fuzzy-matcher = { version = "0.3", optional = true }
+
 [dev-dependencies]
 tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 wiremock = "0.6"

Cargo.toml

@@ -48,13 +48,15 @@ This document analyzes framework-agnostic modules in Pacsea (`src/sources/`, `sr
   - ⏳ AUR dependency queries (async .SRCINFO fetching limitation noted - future enhancement)
   - **Detailed Plan**: [DEPENDENCIES_MODULE_PHASE.md](./DEPENDENCIES_MODULE_PHASE.md)
 
-**Phase 3 - Index Module: ⏳ PLANNED**
+**Phase 3 - Index Module: 🚧 IN PROGRESS**
 
 - Index module (package database queries)
-  - Installed package queries
-  - Official repository queries
-  - Mirror management
-  - Index persistence
+  - ✅ Installed package queries (Task 3.2.1 - complete)
+  - ✅ Explicit package tracking (Task 3.2.2 - complete)
+  - ✅ Index types (Task 3.1.1 - complete)
+  - ✅ Official repository queries (Task 3.3 - complete)
+  - ⏳ Mirror management (Task 3.5 - optional, pending)
+  - ⏳ Index persistence (Task 3.4 - pending)
 
 **Phase 4+ - Remaining Modules: ⏳ PLANNED**
 
@@ -682,11 +684,13 @@ arch-toolkit/
 - [ ] **Port AUR dependency queries** - From `src/logic/deps/aur.rs`
 
 #### Index Module (`feature = "index"`)
-- [ ] **Port installed package queries** - From `src/index/installed.rs`
-- [ ] **Port official repo queries** - From `src/index/query.rs`
-- [ ] **Port mirror management** - From `src/index/mirrors.rs` (optional, Windows-specific)
-- [ ] **Port index persistence** - From `src/index/persist.rs`
-- [ ] **Remove Pacsea-specific caching** - Let callers handle persistence
+- [x] **Create index types** - `OfficialPackage`, `OfficialIndex`, `IndexQueryResult`, `InstalledPackagesMode` (Task 3.1.1)
+- [x] **Port installed package queries** - From `src/index/installed.rs` (Task 3.2.1 - complete)
+- [x] **Port explicit package tracking** - From `src/index/explicit.rs` (Task 3.2.2 - complete)
+- [x] **Port official repo queries** - From `src/index/query.rs` (Task 3.3 - complete)
+- [ ] **Port index persistence** - From `src/index/persist.rs` (Task 3.4 - pending)
+- [ ] **Port mirror management** - From `src/index/mirrors.rs` (Task 3.5 - optional, Windows-specific, pending)
+- [x] **Remove Pacsea-specific caching** - Let callers handle persistence (for completed tasks)
 - **Detailed Plan**: [INDEX_MODULE_PHASE.md](./INDEX_MODULE_PHASE.md)
 
 #### Install Module (`feature = "install"`)
@@ -985,15 +989,18 @@ The Dependencies Module is complete in v0.1.2:
    - ✅ Module entry point
    - **Plan Document**: [DEPENDENCIES_MODULE_PHASE.md](./DEPENDENCIES_MODULE_PHASE.md)
 
-### Phase 3 Status: ⏳ PLANNED
+### Phase 3 Status: 🚧 IN PROGRESS
 
-The Index Module is planned but not yet started:
+The Index Module is partially complete:
 
-1. **Index Module** - ⏳ Planned
-   - ⏳ Installed package queries
-   - ⏳ Official repo queries
-   - ⏳ Mirror management (optional)
-   - ⏳ Index persistence
+1. **Index Module** - 🚧 In Progress
+   - ✅ Index types (`OfficialPackage`, `OfficialIndex`, `IndexQueryResult`, `InstalledPackagesMode`) - Task 3.1.1 complete
+   - ✅ Installed package queries (`refresh_installed_cache`, `is_installed`, `get_installed_packages`) - Task 3.2.1 complete
+   - ✅ Explicit package tracking (`refresh_explicit_cache`, `is_explicit`) - Task 3.2.2 complete
+   - ✅ Official repo queries (`search_official`, `all_official`, `fetch_official_index`, `fetch_official_index_async`) - Task 3.3 complete
+   - ✅ Module entry point updated with query/fetch modules - Task 3.7 partial
+   - ⏳ Index persistence (Task 3.4 - pending)
+   - ⏳ Mirror management (Task 3.5 - optional, pending)
    - **Plan Document**: [INDEX_MODULE_PHASE.md](./INDEX_MODULE_PHASE.md)
 
 ### Phase 4+ Status: ⏳ PLANNED
@@ -1024,11 +1031,14 @@ These modules may still have blockers similar to what the AUR module had:
    - **Remaining**: AUR dependency queries (async .SRCINFO fetching limitation noted - future enhancement)
    - **Plan Document**: [DEPENDENCIES_MODULE_PHASE.md](./DEPENDENCIES_MODULE_PHASE.md)
 
-3. **Phase 3**: Add index module (~20-30 hours) ⏳ **PLANNED**
-   - Package database queries (installed, official repos)
-   - Mirror management
-   - Index persistence
-   - **Status**: Not yet started
+3. **Phase 3**: Add index module (~20-30 hours) 🚧 **IN PROGRESS**
+   - ✅ Index types (Task 3.1.1 - complete)
+   - ✅ Installed package queries (Task 3.2.1 - complete)
+   - ✅ Explicit package tracking (Task 3.2.2 - complete)
+   - ✅ Official repository queries (Task 3.3 - complete)
+   - ⏳ Index persistence (Task 3.4 - pending)
+   - ⏳ Mirror management (Task 3.5 - optional, pending)
+   - **Status**: Tasks 3.1, 3.2, and 3.3 complete, remaining tasks pending
    - **Plan Document**: [INDEX_MODULE_PHASE.md](./INDEX_MODULE_PHASE.md)
 
 4. **Phase 4+**: Add remaining modules incrementally ⏳ **PLANNED**

dev/AUR_TOOLKIT_CRATE_PREPARATION.md

@@ -13,7 +13,7 @@ This document provides a detailed structured plan for implementing the Index Mod
 | **Estimated Effort** | 20-30 hours |
 | **Complexity** | Medium (system command execution, data persistence, async operations) |
 | **Dependencies** | `types` module, optional `aur` module for enrichment |
-| **Status** | ⏳ Planned - Not yet started |
+| **Status** | 🚧 In Progress - Tasks 3.1, 3.2, and 3.3 complete |
 
 ## Overview
 
@@ -78,7 +78,7 @@ This module is foundational and used by other modules (deps, install) for packag
 - `OfficialIndex` - Collection of official packages with name lookup
   ```rust
   pub struct OfficialIndex {
-      pub packages: Vec<OfficialPackage>,
+      pub pkgs: Vec<OfficialPackage>,
       // Internal: name_to_idx for O(1) lookups
   }
   ```
@@ -89,15 +89,23 @@ This module is foundational and used by other modules (deps, install) for packag
       pub fuzzy_score: Option<i64>,
   }
   ```
+- `InstalledPackagesMode` - Filter mode for explicit package queries (added in Task 3.2)
+  ```rust
+  pub enum InstalledPackagesMode {
+      LeafOnly,      // pacman -Qetq
+      AllExplicit,   // pacman -Qeq
+  }
+  ```
 
 **Estimated Effort**: 2-3 hours
 
 **Acceptance Criteria**:
-- [ ] All types have rustdoc comments (What/Inputs/Output/Details)
-- [ ] Types are serializable with serde
-- [ ] `OfficialIndex` has `rebuild_name_index()` method
-- [ ] Unit tests for type operations
-- [ ] Code passes `cargo fmt`, `cargo clippy`, `cargo check`
+- [x] All types have rustdoc comments (What/Inputs/Output/Details)
+- [x] Types are serializable with serde
+- [x] `OfficialIndex` has `rebuild_name_index()` method
+- [x] `OfficialIndex` has `find_package_by_name()` method
+- [x] Unit tests for type operations
+- [x] Code passes `cargo fmt`, `cargo clippy`, `cargo check`
 
 ---
 
@@ -123,12 +131,12 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 3-4 hours
 
 **Acceptance Criteria**:
-- [ ] Functions work without global state
-- [ ] Graceful degradation when pacman unavailable
-- [ ] Async operations use `spawn_blocking` correctly
-- [ ] Unit tests for installed package queries
-- [ ] Integration tests with mock pacman
-- [ ] Code passes quality checks
+- [x] Functions work without global state
+- [x] Graceful degradation when pacman unavailable
+- [x] Async operations use `spawn_blocking` correctly
+- [x] Unit tests for installed package queries
+- [x] Integration tests with mock pacman
+- [x] Code passes quality checks
 
 #### Task 3.2.2: Port Explicit Package Tracking
 
@@ -141,10 +149,10 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 1-2 hours
 
 **Acceptance Criteria**:
-- [ ] Functions work without global state
-- [ ] Graceful degradation when pacman unavailable
-- [ ] Unit tests
-- [ ] Code passes quality checks
+- [x] Functions work without global state
+- [x] Graceful degradation when pacman unavailable
+- [x] Unit tests
+- [x] Code passes quality checks
 
 ---
 
@@ -171,11 +179,11 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 4-5 hours
 
 **Acceptance Criteria**:
-- [ ] Functions accept `&OfficialIndex` parameter (no global state)
-- [ ] Fuzzy matching works correctly
-- [ ] Case-insensitive substring matching works
-- [ ] Unit tests for search functionality
-- [ ] Code passes quality checks
+- [x] Functions accept `&OfficialIndex` parameter (no global state)
+- [x] Fuzzy matching works correctly
+- [x] Case-insensitive substring matching works
+- [x] Unit tests for search functionality
+- [x] Code passes quality checks
 
 #### Task 3.3.2: Port Official Index Fetching
 
@@ -194,12 +202,12 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 3-4 hours
 
 **Acceptance Criteria**:
-- [ ] Uses `reqwest` via arch-toolkit client
-- [ ] Respects rate limiting
-- [ ] Handles errors gracefully
-- [ ] Unit tests with mock HTTP responses
-- [ ] Integration tests (optional, requires network)
-- [ ] Code passes quality checks
+- [x] Uses `reqwest` via arch-toolkit client
+- [x] Respects rate limiting
+- [x] Handles errors gracefully
+- [x] Unit tests with mock HTTP responses
+- [x] Integration tests (optional, requires network)
+- [x] Code passes quality checks
 
 ---
 
@@ -306,11 +314,12 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 1-2 hours
 
 **Acceptance Criteria**:
-- [ ] All public APIs exported
-- [ ] Comprehensive module documentation
-- [ ] Usage examples in rustdoc
-- [ ] Feature flags documented
-- [ ] Code passes quality checks
+- [x] All public APIs exported (for installed/explicit/query/fetch modules)
+- [x] Comprehensive module documentation
+- [x] Usage examples in rustdoc
+- [x] Feature flags documented
+- [x] Code passes quality checks
+- [ ] Additional exports for persist module (pending)
 
 ---
 
@@ -329,10 +338,11 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 3-4 hours
 
 **Acceptance Criteria**:
-- [ ] All functions have unit tests
-- [ ] Error cases covered
-- [ ] Edge cases covered
-- [ ] Tests pass with `cargo test -- --test-threads=1`
+- [x] All functions have unit tests (for installed/explicit/query/fetch modules)
+- [x] Error cases covered (for installed/explicit/query/fetch modules)
+- [x] Edge cases covered (for installed/explicit/query/fetch modules)
+- [x] Tests pass with `cargo test -- --test-threads=1` (for completed modules)
+- [ ] Additional tests for persist module (pending)
 
 #### Task 3.8.2: Integration Tests
 
@@ -347,9 +357,10 @@ This module is foundational and used by other modules (deps, install) for packag
 **Estimated Effort**: 2-3 hours
 
 **Acceptance Criteria**:
-- [ ] Integration tests cover main workflows
-- [ ] Tests use mock commands where possible
-- [ ] Tests pass with `cargo test -- --test-threads=1`
+- [x] Integration tests cover main workflows (for installed/explicit modules)
+- [x] Tests use mock commands where possible (mock pacman scripts)
+- [x] Tests pass with `cargo test -- --test-threads=1` (for completed modules)
+- [ ] Additional integration tests for persist module (pending)
 
 #### Task 3.8.3: Documentation and Examples
 
@@ -376,7 +387,7 @@ This module is foundational and used by other modules (deps, install) for packag
 ```toml
 [features]
 default = ["aur"]
-index = []  # No additional dependencies, uses std and serde
+index = ["dep:tokio"]  # For async operations with spawn_blocking
 
 [dependencies]
 # Index module dependencies (always included)
@@ -388,7 +399,7 @@ fuzzy-matcher = { version = "0.3", optional = true }  # For fuzzy search
 tokio = { version = "1", features = ["rt", "time"], optional = true }  # For async operations
 ```
 
-**Note**: The index module should work without async by default, but async operations are available when `tokio` feature is enabled.
+**Note**: The index module includes tokio as a dependency for async operations. Async functions are available when the `index` feature is enabled.
 
 ---
 
@@ -466,30 +477,33 @@ Once the index module is complete, Pacsea can:
 
 The Index Module is complete when:
 
-- [ ] All core functionality ported (installed queries, official queries, persistence)
-- [ ] No dependencies on Pacsea internals
-- [ ] All functions have rustdoc documentation
-- [ ] Unit tests pass
-- [ ] Integration tests pass
+- [x] Installed package queries ported (Task 3.2)
+- [x] Explicit package tracking ported (Task 3.2)
+- [x] Official repository queries ported (Task 3.3)
+- [ ] Index persistence ported (Task 3.4)
+- [x] No dependencies on Pacsea internals (for completed tasks)
+- [x] All functions have rustdoc documentation (for completed tasks)
+- [x] Unit tests pass (for completed tasks)
+- [x] Integration tests pass (for completed tasks)
 - [ ] Example program works
-- [ ] Code passes `cargo fmt`, `cargo clippy`, `cargo check`
+- [x] Code passes `cargo fmt`, `cargo clippy`, `cargo check` (for completed tasks)
 - [ ] README updated with index module documentation
-- [ ] Module entry point complete
+- [x] Module entry point created (Task 3.7 - partial, installed/explicit modules complete)
 
 ---
 
 ## Timeline
 
-| Task | Estimated Hours | Priority |
-|------|----------------|----------|
-| 3.1: Define Types | 2-3 | High |
-| 3.2: Installed Queries | 4-6 | High |
-| 3.3: Official Queries | 7-9 | High |
+| Task | Estimated Hours | Priority | Status |
+|------|----------------|----------|--------|
+| 3.1: Define Types | 2-3 | High | ✅ Complete |
+| 3.2: Installed Queries | 4-6 | High | ✅ Complete |
+| 3.3: Official Queries | 7-9 | High | ✅ Complete |
 | 3.4: Persistence | 2-3 | High |
 | 3.5: Mirror Management | 2-3 | Medium (Optional) |
 | 3.6: Background Updates | 2-3 | Low (Optional) |
-| 3.7: Module Entry Point | 1-2 | High |
-| 3.8: Testing & Docs | 7-10 | High |
+| 3.7: Module Entry Point | 1-2 | High | ✅ Partial (installed/explicit/query/fetch complete) |
+| 3.8: Testing & Docs | 7-10 | High | ✅ Partial (installed/explicit/query/fetch complete) |
 | **Total** | **27-39 hours** | |
 
 **Recommended Approach**: Start with high-priority tasks (3.1-3.4, 3.7-3.8), then add optional features (3.5-3.6) as needed.