feat: refactor tx API + add backing functions

- Consolidated transaction API to address a design flaw
  - Calling BEGIN and then ceding the write conn could
     leave an open transaction dangling
- Added backing functions to wrapper.rs
- Added decoder and tests
- Added tests for error types
- Remove the idea that an error will throw when
  attempting a RO query with the writer. It's obvious
  from the return type you'll get no query results
- NOTE: Integration tests coming in a future PR

Author: pmorris-dev

Cargo.lock

@@ -23,6 +23,7 @@ futures-core = "0.3.31"
 time = "0.3.44"
 tokio = { version = "1.48.0", features = ["sync"] }
 indexmap = { version = "2.12.1", features = ["serde"] }
+base64 = "0.22.1"
 
 # SQLx for types and queries (time feature enables datetime type decoding)
 sqlx = { version = "0.8.6", features = ["sqlite", "json", "time", "runtime-tokio"] }

Cargo.toml

@@ -0,0 +1,355 @@
+# Plugin Code Migration Plan
+
+This document outlines the phased approach for migrating the working
+prototype from `../plugins-workspace/plugins/sqlite` into this project.
+
+## Overview
+
+The migration is organized into 5 phases, each designed to be a reviewable
+PR that builds upon the previous phase. The goal is to make reviews
+manageable while ensuring each phase leaves the code in a working state.
+
+## Phase 1: Foundation - README, Types, and Build Configuration
+
+**Goal:** Establish the public API surface and documentation without
+implementation details.
+
+**Changes:**
+
+1. **README.md** - Merge and enhance:
+   * Preserve existing project structure documentation and standards info
+   * Add comprehensive usage examples from prototype
+   * Add API reference documentation
+   * Add migration guide from tauri-plugin-sql
+   * Keep CI badge and project metadata from current README
+   * Add feature list and architecture overview
+
+2. **Cargo.toml** - Update dependencies:
+   * Add `serde_json`, `thiserror`, `log`, `futures-core`, `time`,
+     `tokio`, `indexmap`
+   * Add `sqlx` with features: `["sqlite", "json", "time",
+     "runtime-tokio"]`
+   * Update `sqlx-sqlite-conn-mgr` path from workspace member to local
+     crate
+   * Keep workspace structure intact
+
+3. **package.json** - Update for proper publishing:
+   * Update package name to `@tauri-apps/plugin-sqlite` (or keep
+     `@silvermine/tauri-plugin-sqlite`)
+   * Add proper exports configuration (types, import, require)
+   * Update build script to use rollup instead of raw tsc
+   * Add dual licensing if using @tauri-apps namespace
+
+4. **TypeScript interfaces** (`guest-js/index.ts`):
+   * Add `QueryResult` interface
+   * Add `CustomConfig` interface
+   * Add `Database` class skeleton with method signatures only (no
+     implementation)
+   * Keep all JSDoc comments for API documentation
+   * Replace hello() function with Database class structure
+
+5. **Build configuration**:
+   * Add `rollup.config.js` for JS bundling
+   * Add `api-iife.js` for IIFE builds
+   * Update `tsconfig.json` if needed
+
+6. **Licensing**:
+   * Add `LICENSE_APACHE-2.0` and `LICENSE_MIT` files
+   * Update headers in files to dual license format
+
+**Verification:**
+
+* README is comprehensive and accurate
+* TypeScript types compile successfully
+* `npm run build` succeeds
+* Documentation is complete (even though implementation is pending)
+
+**Files Modified:**
+
+* `README.md`
+* `Cargo.toml`
+* `package.json`
+* `guest-js/index.ts`
+* `rollup.config.js` (new)
+* `api-iife.js` (new)
+* `LICENSE_APACHE-2.0` (new)
+* `LICENSE_MIT` (new)
+
+**Estimated Size:** ~300 lines changed (mostly docs and config)
+
+---
+
+## Phase 2: Core Error Handling and Models
+
+**Goal:** Add error types and data models needed by the plugin commands.
+
+**Changes:**
+
+1. **src/error.rs** - Replace with comprehensive error handling:
+   * Add `Error` enum with variants for:
+      * `Sqlx(sqlx::Error)`
+      * `Io(std::io::Error)`
+      * `Tauri(tauri::Error)`
+      * `Migration(String)`
+      * `InvalidQuery(String)`
+      * `Connection(String)`
+   * Implement `From` conversions for each error type
+   * Implement `Serialize` for Tauri command responses
+   * Keep `Result<T>` type alias
+
+2. **src/lib.rs** - Add type definitions only:
+   * Add `DbInstances` struct
+   * Add `PluginConfig` struct with `preload` field
+   * Add `Migration` struct
+   * Add `MigrationKind` enum
+   * Add `MigrationList` struct implementing `MigrationSource`
+   * Add `Builder` struct skeleton (no implementation yet)
+   * Add `run_async_command` helper function
+   * Keep existing module declarations
+
+3. **Documentation:**
+   * Add inline documentation for all public types
+   * Add module-level documentation with examples
+
+4. **Update README.md:**
+   * Update the "Project Structure" section to reflect any new files added
+
+**Verification:**
+
+* Rust code compiles (`cargo build`)
+* No warnings
+* Error types properly implement required traits
+
+**Files Modified:**
+
+* `src/error.rs`
+* `src/lib.rs` (types only, no builder implementation)
+
+**Estimated Size:** ~200 lines
+
+---
+
+## Phase 3: Database Wrapper and Decode Logic
+
+**Goal:** Add the database wrapper that manages connections and the decode
+logic for query results.
+
+**Changes:**
+
+1. **src/wrapper.rs** (new file):
+   * `DatabaseWrapper` struct
+   * Connection initialization logic
+   * Migration support
+   * Pool management (read/write pools)
+   * Close and remove operations
+   * All methods fully implemented
+
+2. **src/decode.rs** (new file):
+   * `decode_query_result` function
+   * Row conversion logic
+   * Type mapping from SQLite to Serde JSON
+   * Null handling
+   * Time type support
+
+3. **Update src/lib.rs**:
+   * Add `pub use wrapper::DatabaseWrapper;`
+   * Add `pub use decode::decode_query_result;` if needed
+
+4. **Update README.md:**
+   * Update the "Project Structure" section to reflect new wrapper.rs and decode.rs files
+
+**Verification:**
+
+* Rust code compiles
+* Unit tests pass for decode logic (if we add them)
+* No warnings
+
+**Files Modified:**
+
+* `src/wrapper.rs` (new)
+* `src/decode.rs` (new)
+* `src/lib.rs` (add module declarations and exports)
+
+**Estimated Size:** ~400 lines
+
+---
+
+## Phase 4: Commands Implementation
+
+**Goal:** Implement the actual Tauri command handlers that the frontend
+calls.
+
+**Changes:**
+
+1. **src/commands.rs** - Replace hello with real commands:
+   * `load` - Load/connect to database
+   * `execute_write` - Execute write queries
+   * `select` - Execute select queries
+   * `close` - Close specific database
+   * `close_all` - Close all databases
+   * `remove` - Delete database files
+   * Add proper error handling
+   * Add parameter validation
+
+2. **guest-js/index.ts** - Add actual invoke calls:
+   * Implement all Database class methods
+   * Wire up to `plugin:sqlite|*` commands
+   * Keep all existing type definitions and documentation
+
+3. **Update src/lib.rs**:
+   * Update `generate_handler!` macro to include all commands
+   * Keep command list updated
+
+4. **Update README.md:**
+   * Update the "Project Structure" section if commands.rs changes significantly
+
+**Verification:**
+
+* Rust code compiles
+* TypeScript compiles and generates proper types
+* Commands are properly registered
+* JSDoc comments match implementation
+
+**Files Modified:**
+
+* `src/commands.rs`
+* `guest-js/index.ts`
+* `src/lib.rs` (update handler registration)
+
+**Estimated Size:** ~250 lines
+
+---
+
+## Phase 5: Plugin Builder and Lifecycle
+
+**Goal:** Complete the plugin initialization, migration system, and
+lifecycle management.
+
+**Changes:**
+
+1. **src/lib.rs** - Implement Builder:
+   * Implement `Builder::new()`
+   * Implement `Builder::add_migrations()`
+   * Implement `Builder::build()` with full setup logic:
+      * Database preloading
+      * Migration execution
+      * State management
+      * Cleanup on app exit
+   * Wire up all lifecycle hooks
+
+2. **permissions/default.toml** - Update permissions:
+   * Replace `allow-hello` with actual command permissions
+   * Add descriptive documentation
+   * Follow prototype's permission structure
+
+3. **permissions/autogenerated/** - Regenerate:
+   * Run Tauri's permission generation
+   * Ensure all commands have permission definitions
+   * Update schemas
+
+4. **build.rs** - Update if needed:
+   * Ensure it properly generates permissions
+   * Add any additional build steps
+
+5. **CHANGELOG.md** (new):
+   * Add initial version entry
+   * Document features
+
+6. **Update README.md:**
+   * Update the "Project Structure" section to reflect completed implementation
+   * Remove "Phase 2" notation from commands.rs description
+
+**Verification:**
+
+* Full plugin lifecycle works
+* Migrations run correctly
+* Preload functionality works
+* Database cleanup on exit works
+* Permissions are properly enforced
+* All npm scripts work
+* All cargo commands work
+
+**Files Modified:**
+
+* `src/lib.rs` (complete Builder implementation)
+* `permissions/default.toml`
+* `permissions/autogenerated/*` (regenerated)
+* `build.rs` (if needed)
+* `CHANGELOG.md` (new)
+
+**Estimated Size:** ~200 lines
+
+---
+
+## Phase 6 (Optional): Testing and Examples
+
+**Goal:** Add comprehensive tests and example application.
+
+**Changes:**
+
+1. **Add integration tests:**
+   * Test database loading
+   * Test migrations
+   * Test CRUD operations
+   * Test concurrent reads
+   * Test cleanup
+
+2. **Add example application:**
+   * Simple Tauri app demonstrating plugin usage
+   * Example migrations
+   * Example frontend code
+
+3. **Add CI improvements:**
+   * Test workflows
+   * Documentation generation
+
+4. **Update README.md:**
+   * Update the "Project Structure" section to include tests/ and examples/ directories
+
+**Verification:**
+
+* All tests pass
+* Example app runs
+* CI pipeline succeeds
+
+**Estimated Size:** ~500+ lines (tests and examples)
+
+---
+
+## Summary
+
+| Phase | Focus | PR Size | Risk |
+|-------|-------|---------|------|
+| 1 | Foundation | Medium | Low |
+| 2 | Types & Errors | Small | Low |
+| 3 | Wrapper & Decode | Large | Medium |
+| 4 | Commands | Medium | Medium |
+| 5 | Builder & Lifecycle | Medium | High |
+| 6 | Testing (Optional) | Large | Low |
+
+**Key Principles:**
+
+* Each phase compiles successfully
+* Incremental functionality additions
+* Clear separation of concerns
+* Easy to review diffs
+* Logical progression from types → implementation → integration
+
+**Dependencies:**
+
+* Phase 2 depends on Phase 1 (needs types from updated Cargo.toml)
+* Phase 3 depends on Phase 2 (needs error types)
+* Phase 4 depends on Phase 3 (needs DatabaseWrapper)
+* Phase 5 depends on Phase 4 (needs commands)
+* Phase 6 depends on Phase 5 (needs complete implementation)
+
+## Next Steps
+
+1. Review this plan
+2. Approve or suggest modifications
+3. Execute Phase 1
+4. Review PR for Phase 1
+5. Proceed to next phase
+
+Would you like to proceed with Phase 1, or would you like any adjustments
+to this plan?