Metadata-Version: 2.4
Name: smartedit-explorer
Version: 4.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)

## 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"
log_level = "info"
verbose = false
quiet = false
stderr = false
```

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

## 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

## Non-Interactive Automation

The script can run fully non-interactively for automation or integration with other tools.

Key ingredients:

- **Config file**: provides all required defaults (search root, output paths)
- **Piped stdin**: supplies the project selection prompt input
- **`--quiet --stderr`**: suppresses all output, routing everything to stderr so stdout stays clean for your own use

Example config file (`smartedit_explorer.toml`):

```toml
search_root = "C:\\Users\\Ivan\\Documents"
output = "C:\\reports"
json_out = true
json_file = "C:\\reports\\out.json"
```

Example invocation:

```bash
echo "all" | smartedit-explorer --quiet --stderr --json-out
```

This selects all discovered projects (via piped stdin), writes JSON to the configured path, prints nothing to stdout, and routes any errors or prompts to stderr. stdout remains empty for the caller's own use.

If `--project` is supplied instead of relying on interactive selection, the piped stdin is unnecessary:

```bash
smartedit-explorer --project "C:\\path\\to\\project" --quiet --stderr --json-out
```

This runs completely non-interactively with no stdin dependency.

## `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] [--tree] [--tree-out] [--tree-file PATH] [--output DIR] [--convert] [--style STYLE] [--reuse] [--html-output PATH] [--force-html] [--force] [--force-assets] [--nuclear] [--config-file PATH] [--log-level LEVEL] [--verbose] [--quiet] [--stderr] [--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).

`--tree`

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

`--tree-out`

_Optional, defaults to False_. Write tree output to a file. The file path is determined by `--tree-file`, or defaults to `./reports/tree.txt` (or nested in `--output` if supplied). Suppresses the default tree-to-stdout output unless `--tree` is also supplied.

`--tree-file PATH`

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

`--output DIR`

_Optional, defaults to `./reports/`_. Directory for output files. Used by `--html` (report files), `--json-out` (JSON file), and `--tree-out` (tree file). For merged HTML 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`.

`--log-level LEVEL`

_Optional, defaults to `info`_. Set the logging threshold. Valid levels: `debug`, `info`, `warn`, `error`.

`--verbose`

_Optional, defaults to False_. Show all debug output. Equivalent to `--log-level debug`. Cannot be combined with `--quiet`.

`--quiet`

_Optional, defaults to False_. Suppress all diagnostic output including errors. Requested console output (e.g. `--tree`, `--json`) and interactive project selection prompts still appear. Cannot be combined with `--verbose`.

`--stderr`

_Optional, defaults to False_. Route all output to stderr, leaving stdout clean for piping or automation. Interactive project selection prompts also respect this flag.

`--help`, `-h`

Show the help message and exit.

`--version`, `-v`

Print the version number and exit.

### 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
