feat: add SQLite local cache for wiki structure

- Add Database class with PDO for lightweight SQLite operations
- Add bookstack:sync command to sync wiki structure from API
- Add bookstack:db command to query and manage local cache
- Add content_hash tracking for change detection (xxh3)
- Add local_path mapping for file-to-page relationships
- Integrate with SyncService for automatic cache updates
- Add database configuration options (enabled, path)
- Add comprehensive test coverage for Database class

Author: abkrim

CHANGELOG.md

@@ -2,7 +2,34 @@
 
 All notable changes to `bookstack-sync` will be documented in this file.
 
-## [Unreleased]
+## [1.0.0] - 2025-12-25
+
+### Added
+
+- **SQLite Local Cache**: New local database for caching wiki structure
+  - Reduces API calls by storing shelves, books, chapters, and pages locally
+  - Tracks sync state with `synced_at` and `is_deleted` flags
+  - Maps local files to remote pages with `local_path`
+  - Detects content changes efficiently with `content_hash` (xxh3)
+- New Artisan commands for database management:
+  - `bookstack:sync` - Sync wiki structure from BookStack API to local SQLite cache
+  - `bookstack:db stats` - Show database statistics
+  - `bookstack:db shelves|books|chapters|pages` - List cached entities
+  - `bookstack:db path` - Show database file path and size
+  - `bookstack:db delete` - Delete the local database
+- Configuration options for local database:
+  - `BOOKSTACK_LOCAL_DB` - Enable/disable local database (default: true)
+  - `BOOKSTACK_DB_PATH` - Custom database path (default: storage/bookstack-sync.sqlite)
+- Database class with PDO for lightweight SQLite operations
+- Content hash generation using xxh3 algorithm for change detection
+- Integration with SyncService for automatic local_path and content_hash tracking
+
+### Changed
+
+- SyncService now uses local cache to skip unchanged files during sync
+- BookStackSync facade includes database access via `database()` method
+
+## [0.1.0] - 2025-12-14
 
 ### Added
 

README.md

@@ -15,6 +15,7 @@ A Laravel package for synchronizing Markdown documentation with [BookStack](http
 ## Features
 
 - **Bidirectional Sync**: Push local Markdown files to BookStack or pull BookStack content to local files
+- **Local SQLite Cache**: Reduces API calls by caching wiki structure locally with change detection
 - **Bookmark Conversion**: Automatically converts AI-generated bookmarks (Claude, Cursor, etc.) to BookStack's URL-encoded format
 - **Spanish Character Support**: Full support for UTF-8 characters (á, é, í, ó, ú, ñ, ç, ü, etc.)
 - **Artisan Commands**: Easy-to-use CLI commands for all operations
@@ -115,6 +116,41 @@ php artisan bookstack:search "configuration"
 php artisan bookstack:search "instalación" --limit=50
 ```
 
+#### Sync Wiki Structure to Local Cache
+
+```bash
+# Sync all wiki structure to local SQLite database
+php artisan bookstack:sync
+
+# Fresh sync (deletes existing database first)
+php artisan bookstack:sync --fresh
+
+# Sync only specific entities
+php artisan bookstack:sync --no-shelves --no-chapters
+```
+
+#### Query Local Cache
+
+```bash
+# Show database statistics
+php artisan bookstack:db stats
+
+# List cached entities
+php artisan bookstack:db shelves
+php artisan bookstack:db books
+php artisan bookstack:db chapters --book=5
+php artisan bookstack:db pages --book=5 --chapter=10
+
+# Include deleted items
+php artisan bookstack:db pages --deleted
+
+# Show database path and size
+php artisan bookstack:db path
+
+# Delete local database
+php artisan bookstack:db delete --force
+```
+
 ### Programmatic Usage
 
 ```php
@@ -216,6 +252,37 @@ Configure sync behavior in `config/bookstack-sync.php`:
 ],
 ```
 
+## Local Database Configuration
+
+The package includes a local SQLite cache to reduce API calls and enable change detection:
+
+```php
+'database' => [
+    // Enable/disable local database caching
+    'enabled' => env('BOOKSTACK_LOCAL_DB', true),
+
+    // Database path (relative to storage/ or absolute path)
+    'path' => env('BOOKSTACK_DB_PATH', 'bookstack-sync.sqlite'),
+],
+```
+
+### Environment Variables
+
+```env
+# Enable local SQLite cache (default: true)
+BOOKSTACK_LOCAL_DB=true
+
+# Custom database path (default: storage/bookstack-sync.sqlite)
+BOOKSTACK_DB_PATH=bookstack-sync.sqlite
+```
+
+### How It Works
+
+1. Run `php artisan bookstack:sync` to populate the local cache
+2. The cache stores all shelves, books, chapters, and pages with their metadata
+3. During push/pull operations, the package uses content hashes to skip unchanged files
+4. Deleted items in BookStack are marked with `is_deleted` flag for tracking
+
 ## Spanish Character Encoding Reference
 
 | Character | URL Encoded |

config/bookstack-sync.php

@@ -103,4 +103,28 @@
         'enabled' => env('BOOKSTACK_LOGGING', true),
         'channel' => env('BOOKSTACK_LOG_CHANNEL', 'stack'),
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Local Database Configuration
+    |--------------------------------------------------------------------------
+    |
+    | SQLite database for caching wiki structure locally.
+    | This reduces API calls and enables offline querying of wiki structure.
+    |
+    | Features:
+    | - Cache shelves, books, chapters, pages structure
+    | - Track synchronization state (synced_at, is_deleted)
+    | - Map local files to remote pages (local_path)
+    | - Detect content changes efficiently (content_hash)
+    |
+    */
+
+    'database' => [
+        // Enable local SQLite cache
+        'enabled' => env('BOOKSTACK_LOCAL_DB', true),
+
+        // Path to SQLite database file (relative to storage_path or absolute)
+        'path' => env('BOOKSTACK_DB_PATH', 'bookstack-sync.sqlite'),
+    ],
 ];

src/BookStackSync.php

@@ -6,6 +6,7 @@
 
 use AichaDigital\BookStackSync\Api\BookStackClient;
 use AichaDigital\BookStackSync\Contracts\BookStackClientInterface;
+use AichaDigital\BookStackSync\Database\Database;
 use AichaDigital\BookStackSync\DTOs\BookDTO;
 use AichaDigital\BookStackSync\DTOs\ChapterDTO;
 use AichaDigital\BookStackSync\DTOs\PageDTO;
@@ -33,9 +34,12 @@ class BookStackSync
 
     private ?SyncService $syncService = null;
 
-    public function __construct(?BookStackClientInterface $client = null)
+    private ?Database $database = null;
+
+    public function __construct(?BookStackClientInterface $client = null, ?Database $database = null)
     {
         $this->client = $client ?? $this->createDefaultClient();
+        $this->database = $database;
         $this->parser = new MarkdownParser(
             config('bookstack-sync.markdown.convert_bookmarks', true),
             config('bookstack-sync.markdown.encoding', 'UTF-8')
@@ -45,6 +49,29 @@ public function __construct(?BookStackClientInterface $client = null)
         );
     }
 
+    /**
+     * Get the database instance.
+     */
+    public function database(): ?Database
+    {
+        return $this->database;
+    }
+
+    /**
+     * Set the database instance.
+     */
+    public function setDatabase(?Database $database): self
+    {
+        $this->database = $database;
+
+        // Update sync service if already created
+        if ($this->syncService !== null) {
+            $this->syncService->setDatabase($database);
+        }
+
+        return $this;
+    }
+
     /**
      * Get the API client instance.
      */
@@ -240,6 +267,11 @@ public function sync(): SyncService
             if (config('bookstack-sync.sync.dry_run', false)) {
                 $this->syncService->setDryRun(true);
             }
+
+            // Inject database if available
+            if ($this->database !== null) {
+                $this->syncService->setDatabase($this->database);
+            }
         }
 
         return $this->syncService;

src/BookStackSyncServiceProvider.php

@@ -5,12 +5,15 @@
 namespace AichaDigital\BookStackSync;
 
 use AichaDigital\BookStackSync\Api\BookStackClient;
+use AichaDigital\BookStackSync\Commands\BookStackDbCommand;
 use AichaDigital\BookStackSync\Commands\BookStackExportCommand;
 use AichaDigital\BookStackSync\Commands\BookStackPullCommand;
 use AichaDigital\BookStackSync\Commands\BookStackPushCommand;
 use AichaDigital\BookStackSync\Commands\BookStackSearchCommand;
 use AichaDigital\BookStackSync\Commands\BookStackStatusCommand;
+use AichaDigital\BookStackSync\Commands\BookStackSyncCommand;
 use AichaDigital\BookStackSync\Contracts\BookStackClientInterface;
+use AichaDigital\BookStackSync\Database\Database;
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
@@ -27,6 +30,8 @@ public function configurePackage(Package $package): void
                 BookStackPullCommand::class,
                 BookStackExportCommand::class,
                 BookStackSearchCommand::class,
+                BookStackSyncCommand::class,
+                BookStackDbCommand::class,
             ]);
     }
 
@@ -43,12 +48,41 @@ public function packageRegistered(): void
             );
         });
 
+        // Register the Database class as singleton (if enabled)
+        $this->app->singleton(Database::class, function () {
+            if (! config('bookstack-sync.database.enabled', true)) {
+                return null;
+            }
+
+            $path = config('bookstack-sync.database.path', 'bookstack-sync.sqlite');
+
+            // If path is relative, prepend storage_path
+            if (! str_starts_with($path, '/')) {
+                $path = storage_path($path);
+            }
+
+            return new Database($path);
+        });
+
         // Register the main BookStackSync class as singleton
         $this->app->singleton(BookStackSync::class, function ($app) {
-            return new BookStackSync($app->make(BookStackClientInterface::class));
+            $database = null;
+            if (config('bookstack-sync.database.enabled', true)) {
+                try {
+                    $database = $app->make(Database::class);
+                } catch (\Throwable) {
+                    // Database not available, continue without it
+                }
+            }
+
+            return new BookStackSync(
+                $app->make(BookStackClientInterface::class),
+                $database
+            );
         });
 
         // Alias for convenience
         $this->app->alias(BookStackSync::class, 'bookstack-sync');
+        $this->app->alias(Database::class, 'bookstack-db');
     }
 }