ttrpg-convert-cli-ui - GitLite

KO | EN

gitlite — search

#data-science #api #kotlin #markdown #c #database #animation #cross-platform #react-native #typescript

ttrpg-convert-cli-ui

(★ 9)

Cross-platform Tauri rewrite of TTRPG_CLI_UI

File Explorer

ZIP Download

- - release.yml
- dependabot.yml
- - cli.ts
  - config.ts
  - guidance.ts
  - homebrew.ts
  - index.ts
  - platform.ts
  - settings.ts
  - sources.ts
  - template-creator.ts
  - update-check.ts
- main.ts
- style.css
- - default.json
- - 128x128.png
  - [email protected]
  - 32x32.png
  - icon.icns
  - icon.ico
- - basic-test-config.json
  - README.md
- - lib.rs
  - main.rs
- build.rs
- Cargo.lock
- Cargo.toml
- icon-source.png
- tauri.conf.json
.gitattributes
.gitignore
CHANGELOG.md
index.html
LICENSE
package-lock.json
package.json
README.md
tsconfig.json
vite.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A cross-platform (Windows · macOS · Linux) rewrite of the original Windows-only
WinForms UI for [ttrpg-convert-cli](https://github.com/ebullient/ttrpg-convert-cli),
built on **Tauri 2** (Rust core + TypeScript frontend).

## Install

Grab the installer for your OS from the [Releases](../../releases) page:

- **Windows** — `.msi` or `.exe`. Unsigned, so SmartScreen warns on first run —
  see [Windows: "protected your PC"](#windows-protected-your-pc) below.
- **macOS** — `.dmg` (Apple Silicon or Intel — pick yours). The app isn't
  signed with an Apple Developer certificate, so macOS may block it on first
  launch — see [macOS: "app is damaged"](#macos-app-is-damaged) below.
- **Linux** — `.AppImage` or `.deb`

No Java needed — on first launch the app downloads the `ttrpg-convert-cli`
binary for your OS, and you point it at your 5etools data from the Setup tab.

> 🚀 Respect copyrights — only convert sources you own.

## Workflow: download once, run many

Everything lives under one **CLI home** folder and is fetched a single time:

```
<home>/…/bin/ttrpg-convert(.exe)     the converter        (Install, Setup tab)
<home>/5etools-src/data              source data          (Get data — git clone)
<home>/examples/templates/tools5e/   templates            (Get templates — examples.zip)
<home>/5etools-img                   images (optional)    (Get images — git clone)
<home>/homebrew                      homebrew (optional)  (Get homebrew — git clone)
<home>/<name>.json                   your config files    (Build & Save, Configure tab)
<home>/<output>/                     generated notes      (Run tab)
```

The **Setup** tab shows a persistent library status (✓ when something is present
on disk), so reopening the app shows what's already downloaded. **Configure**
builds and saves named config files, with a **Template guide**, a one-click
**Recommended** template preset, and a **Template Creator** for authoring Qute
templates against the variables your installed templates expose. **Run** picks a
saved config and invokes the converter with the working directory set to home —
so the config name, data folder, and output folder all resolve relative to it,
exactly like the original — then shows a guided **"after it finishes"** checklist
of the Obsidian plugins, CSS and admonition files to set up.

## Architecture

The Rust layer (`src-tauri/src/lib.rs`) owns the jobs JS handles poorly or is
sandbox-blocked from. Crucially, file I/O runs through Rust (`write_text_file`,
`read_text_file`, `list_files`, `path_exists`) because Rust's `std::fs` is not
subject to the JS filesystem plugin's path scope — that scope was why saving a
config to a `D:\` folder silently failed in the first cut.

| Concern | Where |
| --- | --- |
| OS/arch detection, asset selection | `detect_host` + `src/lib/platform.ts` (**tested**) |
| Download + extract (converter & templates) | `install_cli`, `download_extract` |
| Run the converter, stream output | `run_converter` |
| Write/read/list config files, check paths | `write_text_file`, `read_text_file`, `list_files`, `path_exists` |
| `git clone` | shell plugin (`src/lib/cli.ts`) |
| Build `config.json` | `src/lib/config.ts` (**tested**, 1:1 with the VB `BuildConfigFile`) |
| Persisted settings | store plugin (`src/lib/settings.ts`) |

## Tested

- ✅ Core logic — **39 passing vitest tests** across the config builder + reverse
  parser, platform/asset matching, and the index and source parsers.
- ✅ Whole frontend typechecks (`npx tsc --noEmit`).
- ⚙️ Rust backend + Tauri wiring compiled and iterated on Windows during
  development; the release workflow builds all four targets.

## Build & run

Prereqs: Node 20+, Rust (stable) with the MSVC toolchain on Windows, and the
[Tauri system deps](https://tauri.app/start/prerequisites/). Icons are bundled
under `src-tauri/icons/`.

```bash
npm install
npm test            # verified logic tests
npm run tauri dev   # live dev window
npm run tauri build # installers in src-tauri/target/release/bundle/
```

Releasing: push a `vX.Y.Z` tag; the matrix workflow builds all four targets and
attaches them to a GitHub release with auto-generated notes. See `CHANGELOG.md`.

## Notes & limitations

- **macOS builds are unsigned** (no Apple Developer cert). They're ad-hoc signed
  in CI so the OS shows the normal "unidentified developer" gate rather than a
  hard error, but quarantine can still block first launch — see below.
- **Windows builds are unsigned** (no code-signing certificate) — SmartScreen
  warns on first run; see below. A certificate (paid) is the only thing that
  removes it; not currently set up.

### macOS: "app is damaged"

If macOS says the app *"is damaged and can't be opened"* (most common on Apple
Silicon) or *"can't be opened because it is from an unidentified developer"*,
that's Gatekeeper quarantining an unsigned download — the app is fine. Clear the
quarantine flag from Terminal (adjust the path to wherever the app is):

```sh
xattr -cr "/Applications/TTRPG Convert CLI UI.app"
```

Then open it normally. Proper Apple notarisation (which removes this entirely)
needs a paid Apple Developer account and is a possible future addition.

### Windows: "protected your PC"

Because the app isn't signed with a code-signing certificate, Windows SmartScreen
shows a blue *"Windows protected your PC"* dialog the first time you run the
installer. The app is fine — click **More info**, then **Run anyway**. Your
browser may also flag the download as uncommon; choose **Keep**. A code-signing
certificate (paid, and reputation builds over time) is the only thing that
removes this, and isn't currently set up.
- **PF2e is not supported** — the tool currently targets the 5etools data
  source and `tools5e` templates. Pathfinder support is not planned at this time. PF2e methods are documented [HERE](https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Community+Supported+Games/Pathfinder+2e/Pathfinder+2e).