Metadata-Version: 2.4
Name: shamela-kit
Version: 0.1.0
Summary: CLI and GUI toolkit for maintaining Shamela data directories
Author: yshalsager
Author-email: yshalsager <contact@yshalsager.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Dist: access-parser==0.0.4
Requires-Dist: orjson>=3.11.9
Requires-Dist: typer>=0.25.1
Requires-Dist: toga>=0.5.4 ; extra == 'gui'
Requires-Python: >=3.12
Provides-Extra: gui
Description-Content-Type: text/markdown

# Shamela Kit

> A CLI and native desktop GUI toolkit for maintaining local [Shamela](https://shamela.ws) data directories.

[![en](https://img.shields.io/badge/README-English-AB8B64.svg)](README.md)
[![ara](https://img.shields.io/badge/README-Arabic-AB8B64.svg)](README.ar.md)
[![PyPI version](https://img.shields.io/pypi/v/shamela-kit.svg)](https://pypi.org/project/shamela-kit/)
[![GitHub release](https://img.shields.io/github/release/yshalsager/shamela-kit.svg)](https://github.com/yshalsager/shamela-kit/releases/)
[![License](https://img.shields.io/github/license/yshalsager/shamela-kit.svg)](LICENSE)
[![Made with Python](https://img.shields.io/badge/Made%20with-Python%203.14-3776AB?style=flat&labelColor=3776AB&logo=python&logoColor=white)](https://www.python.org/)

<img src="assets/logo.svg" alt="Shamela Kit logo" width="120" />

Shamela Kit helps you manage custom books in your local Shamela installation without editing the official app code. It can inspect your data directory, import books from JSON/BOK/EPUB, export books to JSON, edit custom book metadata, attach online PDF links, remove custom books, and create explicit backups when you want them.

**Disclaimer:** This software is free and open source. It is intended for personal, educational, and archival workflows. Close Shamela before making write changes.

**Development note:** Shamela Kit was developed with AI-assisted coding. Changes are reviewed, tested, and maintained by the project author.

## Screenshots

<table>
  <tr>
    <td><img src="assets/en-import.png" alt="Import tab" /></td>
    <td><img src="assets/en-custom-books.png" alt="Custom Books tab" /></td>
  </tr>
  <tr>
    <td><img src="assets/en-backup.png" alt="Backup tab" /></td>
    <td><img src="assets/en-inspect.png" alt="Inspect tab" /></td>
  </tr>
</table>

## Features

- Native desktop GUI in Arabic by default, with English available from the Language menu.
- CLI for repeatable and scripted workflows.
- Works with Shamela's current Windows, macOS, and Linux data layout.
- Inspects a Shamela data directory and runs health checks for SQLite, Lucene, Java, and process safety.
- Lists and manages custom books in the reserved `900000000+` ID range.
- Imports books from Shamela `.bok`, EPUB, or Shamela Kit JSON.
- Exports installed books to a JSON format that can be edited, backed up, or re-imported.
- Changes custom book category and author metadata.
- Links custom books to online PDFs, including Shamela-style multi-file PDF mappings.
- Optionally preserves sanitized EPUB formatting for headings, lists, emphasis, links, and tables.
- Removes custom books from SQLite and Lucene, with optional orphan-author cleanup.
- Creates and restores backups on demand. Backups are opt-in because fully downloaded Shamela libraries can be large.

## Installation

### Desktop app

Download the latest desktop build from [GitHub Releases](https://github.com/yshalsager/shamela-kit/releases/latest) when packaged builds are available.

### CLI package

For the CLI:

```bash
uv tool install shamela-kit
```

Requirements for Python installs:

- Python 3.14+
- Java 21 runtime for Lucene operations
- Java 21 compiler the first time the bundled Lucene bridge is compiled

Shamela Kit first tries Shamela's bundled Java runtime. If that is not available, set `JAVA_HOME`, `SHAMELA_MANUAL_JAVA`, or install Java 21 with your system package manager or `mise`.

## Quick Start

1. Close Shamela.
2. Open Shamela Kit.
3. Confirm the data root points to your Shamela folder.
4. Run **Doctor** before making changes.
5. Import a book, edit metadata, link a PDF, or manage existing custom books.

Default Shamela roots:

- macOS: `~/Library/Application Support/Shamela`
- Windows and Linux: the Shamela program folder when it contains `database`

You can also set custom paths with `SHAMELA_DATA_ROOT`, `SHAMELA_RUNTIME_ROOT`, `--data-root`, and `--runtime-root`.

## CLI Examples

```bash
shamela-kit doctor
shamela-kit inspect
shamela-kit list
shamela-kit info 900000001
```

Import books:

```bash
shamela-kit import-bok ./book.bok --category-id 1
shamela-kit import-epub ./book.epub --category-id 1
shamela-kit import-epub ./book.epub --category-id 1 --preserve-formatting
shamela-kit add-json ./book.json
```

Manage custom books:

```bash
shamela-kit set-category 900000001 2
shamela-kit set-author 900000001 "Author name"
shamela-kit export-json 900000001 -o book.json
shamela-kit remove-book 900000001 --backup
```

Attach PDF metadata:

```bash
shamela-kit set-pdf 900000001 https://archive.org/download/item/book.pdf
shamela-kit pdf-info 900000001
shamela-kit clear-pdf 900000001
```

Back up and restore explicitly:

```bash
shamela-kit backup --book-id 900000001
shamela-kit restore ./shamela-backup-YYYYMMDD-HHMMSS-ffffff --dry-run
```

Run `shamela-kit --help` for the full command list.

## Safety Notes

- Write commands refuse to run while Shamela appears to be open. Use `--force` only when you know the detected process is unrelated.
- Backups are not automatic unless you pass `--backup`, because copying a complete Shamela library can be heavy.
- Deleting a custom book removes Shamela Kit's SQLite/Lucene records. Cached local PDF files are not deleted.
- Custom books should use IDs starting at `900000000`.

## Known Limitations

- EPUB import can preserve sanitized semantic HTML, but it does not import EPUB CSS or embedded images.
- Some BOK files do not contain a category that can be mapped automatically; pass `--category-id`.
- PDF links store metadata used by Shamela. They do not download PDF files by themselves.

## Documentation

More detailed documentation lives in [docs](docs/index.md):

- [CLI](docs/cli.md)
- [GUI](docs/gui.md)
- [EPUB formatting](docs/epub-formatting.md)
- [Data layout](docs/data-layout.md)
- [JSON format](docs/json-format.md)
- [Development](docs/development.md)

## Development

This project uses [mise](https://mise.jdx.dev/) and [uv](https://docs.astral.sh/uv/).

```bash
mise install
mise run sync
mise run check
```

Useful tasks:

```bash
mise run cli -- doctor
mise run gui
mise run i18n
mise run build
mise run briefcase-build
```

The `gui` optional dependency is used for source/development environments and Briefcase packaging:

```bash
uv sync --extra gui
```

The project is intentionally independent from Shamela's bundled Python code. It writes the documented SQLite files directly and uses a small Java bridge for Lucene indexes because Shamela's current desktop data uses Lucene stores.

## Acknowledgements

- [BeeWare](https://beeware.org/) and [Toga](https://toga.readthedocs.io/) for the native GUI toolkit.
- [Typer](https://typer.tiangolo.com/) for the CLI.
- [Phosphor Icons](https://phosphoricons.com/) for inspiring the tool/book icon direction in earlier iterations.

## License

GPL-3.0-only. See [LICENSE](LICENSE).
