Add Web local version using File System API

[phildenhoff]

Using the File System API & sql.js, the Webapp version of Citadel can read a local, client-side library (including the SQLite metadata.db file) to list books & authors.

This branch is missing a lot of features compared to the Desktop version of the app:

• List books titles & authors
• Display book cover art
• Add books
• List book files / file formats
• Open files in default app (how, without downloading the file again?)
• Edit existing book metadata

On top of that, it also needs some cleanup:

• Extract the logic for reading & writing Calibre data to a typescript package
• Provide a better way, in src/App.tsx, to select which library client kind to use
• Better UX when loading the app on the web
  • Each web app load requires the user to re-select their library, because the File System API doesn't provide any way (AFAIK) to save handles across page loads.
  • The minimum here is saving some info to localstorage that a library exists at some file path, and, if that is set, showing a "Welcome Back" screen instead of a "First-time setup" screen.

The other piece I want to very strongly consider is if this semi-domain-driven-design pattern (which is adapted from the existing libcalibre design) is what I really want to do. I think so? I kinda came back to this, not sure if there is something better here.

[phildenhoff]

@greptileai

[greptile-apps]

Greptile Overview

Summary

This PR introduces web browser support to the Citadel library management application by implementing a File System API-based adapter that works alongside the existing desktop (Tauri) version. The changes enable users to access local Calibre libraries directly in web browsers without requiring server infrastructure.

The implementation follows a dual-provider architecture where the application detects the platform (isDesktop()) and conditionally uses either LocalCalibreLibraryProvider (desktop) or WebCalibreLibraryProvider (web). The web version uses sql.js to read Calibre's metadata.db SQLite file and the File System API to access book covers and files locally in the browser.

Key architectural changes include:

• Provider Pattern Extension: The existing LibraryProvider was renamed to LocalCalibreLibraryProvider and a new WebCalibreLibraryProvider was added, maintaining the same Library interface contract
• Web Adapter Implementation: A complete web adapter layer with repositories, services, and entities that mirror the existing Rust-based libcalibre architecture
• Platform Detection: New utility functions to distinguish between desktop and web environments at runtime
• Dual Settings Management: Web version uses localStorage as a fallback to Tauri's settings system
• Entity Transformation: New TypeScript entities (Book, Author, LibraryBook, LibraryAuthor) with transformation methods to bridge sql.js results and the application's domain model

The web implementation supports basic functionality like listing books with titles, authors, and cover images. The File System API integration allows users to select their Calibre library directory, which is then accessed client-side without server communication. The architecture maintains consistency with the existing domain-driven design pattern while adapting to browser constraints.

Changed Files

Filename	Score	Overview
src/lib/contexts/library/index.ts	5/5	Renamed LibraryProvider to LocalCalibreLibraryProvider and added WebCalibreLibraryProvider export
src/lib/services/library/_internal/adapters/web/db.ts	4/5	Added loadDb function for File System API access to Calibre's metadata.db using sql.js
src/lib/services/library/_internal/adapters/calibre.ts	4/5	Extended initCalibreClient to support 'web' connection type by importing web client generator
src/lib/services/library/_internal/adapters/web/repositories/Repository.ts	5/5	Defined TypeScript interfaces for repository pattern implementations in web adapter
src/stores/settings.ts	4/5	Replaced direct __TAURI__ check with isDesktop() function and added localStorage fallback
src/lib/services/library/_internal/adapters/web/entities/LibraryAuthor.ts	4/5	Added entity mapper for converting Author objects to LibraryAuthor format
src/lib/platform.ts	4/5	Introduced platform detection utility to distinguish desktop vs web environments
src/lib/isDefined.ts	5/5	Added type guard utilities for handling undefined/null values in TypeScript
package.json	5/5	Added sql.js dependency and TypeScript types for client-side SQLite operations
src/components/pages/firstTimeSetup.tsx	4/5	Added File System API integration for web directory selection alongside desktop functionality
src/lib/services/library/_internal/adapters/web/services/author.ts	4/5	Created author service for web adapter using dependency injection pattern
src/lib/services/library/_internal/adapters/web/entities/Author.ts	4/5	Introduced Author entity with interface and factory method for database row transformation
src/App.tsx	3/5	Added dual provider logic switching between desktop and web library providers
src/lib/contexts/library/Provider.tsx	5/5	Renamed LibraryProvider to LocalCalibreLibraryProvider for better specificity
src/lib/services/library/_internal/adapters/web/entities/LibraryBook.ts	3/5	Added LibraryBook entity adapter with incomplete fromRow implementation
src/lib/services/library/_internal/adapters/web/types.ts	5/5	Introduced branded type definitions for AuthorId and BookId using TypeScript patterns
src/lib/services/library/_internal/adapters/web/entities/Book.ts	2/5	Defined Book entity with critical field mapping mismatch between fromRow/toRow methods
src/lib/services/library/_internal/_types.ts	5/5	Added WebConnectionOptions interface for File System API-based web connections
src/lib/services/library/_internal/adapters/web/repositories/sqljs.ts	1/5	Implemented SQL.js repositories with critical SQL injection vulnerability in getAuthorsForBook
src/lib/services/library/_internal/adapters/web.ts	3/5	Implemented web-based Calibre client with File System API and sql.js integration
src/lib/services/library/_internal/adapters/web/services/catalog.ts	4/5	Created catalog service combining books and authors with performance considerations
src/lib/services/library/_internal/adapters/web/client.ts	1/5	Empty file missing critical genWebCalibreClient implementation causing runtime errors

Confidence score: 2/5

• This PR contains serious implementation issues that will cause runtime failures and security vulnerabilities
• Score reflects critical missing implementations, SQL injection vulnerabilities, and data mapping errors that would break core functionality
• Pay close attention to src/lib/services/library/_internal/adapters/web/client.ts (empty file), web/repositories/sqljs.ts (SQL injection), and web/entities/Book.ts (field mapping errors)

Sequence Diagram

sequenceDiagram
    participant User
    participant App as "App.tsx"
    participant FirstTimeSetup as "FirstTimeSetup"
    participant WebProvider as "WebCalibreLibraryProvider"
    participant WebClient as "genWebCalibreClient"
    participant FileSystemAPI as "File System API"
    participant SQLjs as "sql.js"
    participant Database as "metadata.db"

    User->>App: "Opens web application"
    App->>App: "Check libraryPath from settings"
    alt No library configured
        App->>FirstTimeSetup: "Render first-time setup"
        FirstTimeSetup->>User: "Show 'Choose Calibre library folder' button"
        User->>FirstTimeSetup: "Clicks choose folder button"
        FirstTimeSetup->>FileSystemAPI: "showDirectoryPicker()"
        FileSystemAPI->>FirstTimeSetup: "Returns FileSystemDirectoryHandle"
        FirstTimeSetup->>App: "onLibraryFSDirectoryHandlePicked(handle)"
        App->>App: "Set libraryFSDirectoryHandle state"
    end
    
    App->>WebProvider: "Initialize with directoryHandle"
    WebProvider->>WebClient: "initClient(webLibraryFromHandle(directoryHandle))"
    
    WebClient->>SQLjs: "Initialize sql.js library"
    SQLjs->>WebClient: "Return SQL instance"
    
    WebClient->>FileSystemAPI: "directoryHandle.getFileHandle('metadata.db')"
    FileSystemAPI->>Database: "Access metadata.db file"
    Database->>WebClient: "Return file buffer"
    WebClient->>SQLjs: "new Database(fileBuffer)"
    SQLjs->>WebClient: "Return database instance"
    
    WebProvider->>WebProvider: "dispatch init action with client"
    WebProvider->>App: "Render children (RouterProvider)"
    
    User->>App: "Navigate to books page"
    App->>WebClient: "listBooks()"
    WebClient->>SQLjs: "Execute SELECT * FROM 'books'"
    SQLjs->>WebClient: "Return book data"
    
    loop For each book with cover
        WebClient->>FileSystemAPI: "Navigate to book directory"
        WebClient->>FileSystemAPI: "getFileHandle('cover.jpg')"
        FileSystemAPI->>WebClient: "Return cover image file"
        WebClient->>WebClient: "Create object URL for cover"
    end
    
    WebClient->>App: "Return books with cover URLs"
    App->>User: "Display books in UI"

Loading

_{22 files reviewed, 17 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

style: The nested await chain could be flattened using intermediate variables for better readability and easier debugging

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/db.ts
Line: 8:14

Comment:
**style:** The nested await chain could be flattened using intermediate variables for better readability and easier debugging

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: The await is unnecessary since you're already returning the Promise directly. Consider removing it for cleaner code.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/services/author.ts
Line: 6:8

Comment:
**style:** The `await` is unnecessary since you're already returning the Promise directly. Consider removing it for cleaner code.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Missing space after opening brace in import statement

Suggested change

	import {WebCalibreLibraryProvider} from "./WebProvider";
	import { WebCalibreLibraryProvider } from "./WebProvider";

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/contexts/library/index.ts
Line: 2:2

Comment:
**style:** Missing space after opening brace in import statement

```suggestion
import { WebCalibreLibraryProvider } from "./WebProvider";
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

logic: The fromRow method has incomplete implementation - it ignores most row data and hardcodes empty author information. This will result in books without proper author data being displayed.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/entities/LibraryBook.ts
Line: 5:23

Comment:
**logic:** The `fromRow` method has incomplete implementation - it ignores most row data and hardcodes empty author information. This will result in books without proper author data being displayed.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Inconsistent indentation - uses spaces instead of tabs like the rest of the properties

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/entities/Author.ts
Line: 6:6

Comment:
**style:** Inconsistent indentation - uses spaces instead of tabs like the rest of the properties

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

logic: author_sort field is defined in interface but missing from toRow output, creating inconsistency

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/entities/Book.ts
Line: 43:43

Comment:
**logic:** author_sort field is defined in interface but missing from toRow output, creating inconsistency

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

logic: SQL injection vulnerability: bookId is directly interpolated into the query string. Use parameterized queries instead.

Suggested change

	const res = db.exec(
	`SELECT author FROM 'books_authors_link' WHERE book = ${bookId}`,
	);
	const res = db.exec(
	"SELECT author FROM 'books_authors_link' WHERE book = ?",
	[bookId]
	);

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/repositories/sqljs.ts
Line: 17:19

Comment:
**logic:** SQL injection vulnerability: bookId is directly interpolated into the query string. Use parameterized queries instead.

```suggestion
const res = db.exec(
	"SELECT author FROM 'books_authors_link' WHERE book = ?",
	[bookId]
);
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Inconsistent error handling: this method throws on null db while others return empty arrays

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web/repositories/sqljs.ts
Line: 14:15

Comment:
**style:** Inconsistent error handling: this method throws on null db while others return empty arrays

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Magic number row[9] for accessing cover path column is brittle and unclear. Consider using named constants or a mapping function.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web.ts
Line: 51:51

Comment:
**style:** Magic number `row[9]` for accessing cover path column is brittle and unclear. Consider using named constants or a mapping function.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Console.log in production code should be replaced with proper error handling or logging system.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/services/library/_internal/adapters/web.ts
Line: 129:129

Comment:
**style:** Console.log in production code should be replaced with proper error handling or logging system.

How can I resolve this? If you propose a fix, please make it concise.