Metadata-Version: 2.4
Name: smartedit-explorer
Version: 3.0.0
Summary: Map SmartEdit Writer projects to the filesystem — find which file is which scene, note, or attachment.
Author-email: "Ivan K." <ivan.kzv@protonmail.com>
Maintainer-email: "Ivan K." <ivan.kzv@protonmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bkuz114/smartedit-explorer
Project-URL: Bug Reports, https://github.com/bkuz114/smartedit-explorer/issues
Project-URL: Source, https://github.com/bkuz114/smartedit-explorer
Keywords: smartedit,writer,novel,writing,explorer,sqlite,html,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Russian
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.13.3
Requires-Dist: mammoth>=1.12.0
Requires-Dist: striprtf>=0.0.32
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Dynamic: license-file

# SmartEdit Writer Explorer

[![PyPI version](https://img.shields.io/pypi/v/smartedit-explorer)](https://pypi.org/project/smartedit-explorer/)
[![Python versions](https://img.shields.io/pypi/pyversions/smartedit-explorer.svg)](https://pypi.org/project/smartedit-explorer/)

A Python utility that maps SmartEdit Writer projects to a navigable tree of scenes, notes, and files — with terminal output or interactive HTML reports.

## Overview

- **About SmartEdit Writer**: [SmartEdit Writer](https://smart-edit.com/) is a novel writing software; text in SmartEdit Writer is broken down into "scenes" and "notes."
- **How SmartEdit Writer stores files**: When you create a scene or note in the SmartEdit Writer interface, the program saves it to disk behind the scenes — scenes become `.docx` files, notes become `.rtf` files, both in the project's `Documents/` folder. When you attach an image, PDF, or other file to your project, a copy of it lands in the project's `Files/` folder. In both cases, the files get generic integer names — `1.docx`, `2.rtf`, `50.jpg`, `56.pdf` — with no obvious connection to what you named them in the program.
- **The problem**: SmartEdit Writer doesn't expose the mapping between what you see in the program and what's on disk. If you're looking at a scene called "The Big Fight" in the interface, there's no way to know which integer file (`47.docx`? `82.docx`?) actually contains your writing.
- **The solution this tool provides**: This utility finds that mapping: it opens a SmartEdit Writer project's SQLite database, determines the mapping between all project items (scenes, notes, and file attachments) and their source files, across all three sections (Manuscript, Fragments, and Research), and displays this info — either on stdout as a formatted tree, or in a generated HTML report with collapsible folders and direct links to source files.

## Dependencies

- Windows OS
- Python 3.8+ (if installed via `pip install`) or Python 3.7+ (if running from source, without `--convert`)

When installed via pip, all required packages are included automatically.
When running from source, install dependencies with `pip install -r requirements.txt`:

- BeautifulSoup 4.13.3
- mammoth>=1.12.0
- striprtf>=0.0.32
- tomli>=2.0.0 (only required on Python < 3.11; Python 3.11+ uses stdlib tomllib)

**Note:** mammoth (used by `--convert`) requires Python 3.8+. Source users on Python 3.7 can run the tool without `--convert`.

## Quickstart

**Option 1: Install via pip (recommended)**

```
pip install smartedit-explorer
smartedit-explorer
```

**Option 2: Run from source**

```
git clone https://github.com/bkuz114/smartedit-explorer.git && cd smartedit-explorer
pip install -r requirements.txt
python src/smartedit_explorer/explorer.py
```

This is the most basic usage; it will search for all SmartEdit Writer projects rooted in your `Documents` folder and prompt you to select one. Then it will determine the scene / source file mapping and display it for you on stdout. (Note: to change the search root, supply `--search-root`. Alternatively, to specify a specific SmartEdit project, use `--project`.)

![stdout example](https://raw.githubusercontent.com/bkuz114/smartedit-explorer/main/src/smartedit_explorer/assets/images/explorer_stdout_example.png)

## HTML Reports

A static HTML report can be created instead of displaying the mapping on stdout. Use `--html` to generate a report with collapsible folders, source file links, and optional inline document viewing (`--convert`). (See usage options below for full list of options around HTML reports.)

![HTML report example](https://raw.githubusercontent.com/bkuz114/smartedit-explorer/main/src/smartedit_explorer/assets/images/html_report_example.png)

## `explorer.py` Options

Usage:

`python explorer.py [--project PROJECT...] [--search-root PATH] [--norecursive] [--short] [--sort KEY] [--sort-order ORDER] [--html] [--merge] [--browser] [--json] [--json-indent N] [--json-file PATH] [--json-out] [--console] [--output DIR] [--convert] [--style STYLE] [--reuse] [--html-output PATH] [--force-html] [--force] [--force-assets] [--nuclear] [--config-file PATH] [--help] [--version]`

Options:

`--project PROJECT`, `-p PROJECT`

_Optional_. Absolute or relative path to one or more SmartEdit Writer projects. Can be supplied multiple times (e.g. `-p proj1 -p proj2`). If not given, the tool will search for all SmartEdit Writer projects rooted in the user's Documents folder (or `--search-root` if supplied) and prompt you to select one or more.

`--search-root PATH`

_Optional_. Directory to search for SmartEdit Writer projects when `--project` is not supplied. Defaults to the user's Documents folder. Ignored if `--project` is given.

`--norecursive`

_Optional, defaults to False_. When searching for SmartEdit Writer projects (i.e. `--project` is not supplied), limit the search to the top-level directory only. Speeds up the search but may miss projects nested in subdirectories.

`--short`, `-s`

_Optional, defaults to False_. When displaying the scene / source file mapping, only display the filenames of the source files — not their absolute paths.

`--sort KEY`

_Optional, defaults to `position`_. Sort the project tree by a Node attribute. Valid keys: `name`, `date_modified`, `type`, `id`, `position`. Sorting is performed within each folder, preserving the tree hierarchy.

`--sort-order ORDER`

_Optional, defaults to `asc`_. Sort direction: `asc` (ascending) or `desc` (descending). Requires `--sort`.

`--html`

_Optional, defaults to False_. Generate an HTML report with the scene / source file mapping. Without this flag, the mapping displays on stdout. By default, a separate report is generated for each project in the current working directory, named after the project (e.g. `My Novel.html`). Use `--merge` to combine all projects into a single report, written to `./report.html` unless `--output` is supplied.

`--merge`

_Optional, defaults to False_. Combine all selected projects into a single HTML report. Without this flag, each project generates its own report file. Requires `--html`.

`--browser`

_Optional, defaults to False_. Open the generated HTML report(s) in the default browser upon completion. Requires `--html`.

`--convert`

_Optional, defaults to False_. Convert .docx and .rtf source files to HTML for inline viewing in the report. Each scene gets a view icon (👁) next to its source link, opening the content in a new browser tab. Requires `--html`. Dependencies: `mammoth` (for .docx) and `striprtf` (for .rtf), installable via `pip install mammoth striprtf`.

`--style STYLE`

_Optional, defaults to `default`_. CSS theme for converted HTML files when using `--convert`. Available styles are discovered from `assets/css/converted/`. Use `--style none` for no styling. Requires `--convert`.

`--reuse`

_Optional, defaults to False_. Skip conversion of source files whose converted HTML output already exists on disk. Significantly speeds up repeated report generation for large projects. Files that haven't been converted yet are still processed. Requires `--convert`.

`--json`

_Optional, defaults to False_. Print the project tree as JSON to stdout. (Use `--json-out` to write to a file instead.) Can coexist with `--html` and `--json-out`.

`--json-indent N`

_Optional, defaults to 2_. Number of spaces for JSON indentation. Use 0 for compact output. Requires `--json`.

`--json-file PATH`

_Optional_. File path for JSON output when `--json-out` is supplied. Defaults to `./reports/out.json`, or nests in `--output` if supplied. Requires `--json-out`.

`--json-out`

_Optional, defaults to False_. Write JSON output to a file. The file path is determined by `--json-file`, or defaults to `./reports/out.json` (or nested in `--output` if supplied). Can coexist with `--json` (one prints, one saves).

`--console`

_Optional, defaults to True_. Print project tree(s) to stdout. Defaults to False when `--html`, `--json`, or `--json-out` is active, unless explicitly supplied. Use `--console` to force tree-to-stdout output alongside other output modes.

`--output DIR`

_Optional, defaults to `./reports/`_. Directory to write HTML report(s) to. For merged reports, the file is named `report.html`. For individual reports, files are named `<project>.html`.

`--html-output PATH`

_Optional_. Directory for converted HTML files when using `--convert`. Defaults to `<output-dir>/html/`. Requires `--html` and `--convert`.

`--force`

_Optional, defaults to False_. Overwrite the HTML report file if it already exists. If the report exists and `--force` is not supplied, the script will exit with an error.

`--force-assets`

_Optional, defaults to False_. Overwrite the assets/ directory (CSS, JS, favicon) at the output location if it already exists. If the assets/ directory exists and `--force-assets` is not supplied, the copy is skipped and existing assets are used as-is — this preserves any user customizations. Separate from `--force` so you can refresh the report without nuking custom CSS or JS.

`--force-html`

_Optional, defaults to False_. Overwrite existing converted HTML files when using `--convert`.

`--nuclear`

_Optional, defaults to False_. USE AT YOUR OWN RISK. Force-deletes the assets/ directory at the output location by stripping read-only permissions before retrying. Only needed on Windows when `--force-assets` fails with "Access is denied" errors (caused by antivirus, search indexer, or Explorer holding transient file locks).

`--config-file PATH`

_Optional_. Path to a TOML config file. Defaults to `./smartedit_explorer.toml`.

`--help`, `-h`

Show the help message and exit.

`--version`, `-v`

Print the version number and exit.

### Interactive Project Selection

When `--project` is not supplied, the script searches for SmartEdit Writer projects and presents a numbered list. You can select projects by:

  - A single number: `3`
  - A comma-separated list: `1,3,4`
  - A range (inclusive): `4-7`
  - Mixed: `2,4-7,9`
  - `all` to select every discovered project
  - `0` to exit without selecting a project

### Configuration File

A TOML config file provides persistent defaults for any CLI flag. By default, the script looks for `smartedit_explorer.toml` in the current working directory. Use `--config-file` to specify a different path.

Config keys use the same names as the long CLI flags with leading `--` removed and hyphens converted to underscores. For example:

```toml
# smartedit_explorer.toml
search_root = "C:\\Users\\Ivan\\Documents"
style = "novel"
sort = "date_modified"
sort_order = "desc"
json_out = true
json_file = "out.json"
```

Precedence: CLI flags > config file > built-in defaults.

### HTML Report Assets

The generated HTML report is fully self-contained. When `--html` is used, the script automatically copies the required assets (CSS, JavaScript, favicon) alongside the report. No manual setup is required.

For reference, the asset directory structure:

    assets/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── scripts.js
    └── images/
        └── favicon.ico
