Skip to content

Commit b209334

Browse files
claudeclaude
committed
feat(windows): native Windows support + double-click launchers; drop WSL guidance
Make Fables run natively on Windows (no WSL) and add a one-double-click way to start it on every OS — for non-technical users this is the difference between "works" and "gives up". - Cross-platform scripts: the dev/CLI scripts used a POSIX-only `VAR=… cmd` prefix that breaks in PowerShell/cmd. Wrap them with `cross-env` so `pnpm dev`, `pnpm seed:demo`, `pnpm forge:run`, etc. work on Windows too. (Production `pnpm start` was already cross-platform; better-sqlite3 ships Windows prebuilds, so there's nothing to compile.) - Double-click launchers at the repo root: `start-fables.cmd` (Windows), `start-fables.command` (macOS), `start-fables.sh` (Linux). First run does install + build, then starts the server and opens the browser; each has a clearly-marked block to drop in optional power-up env vars. - README: replace the WSL detour with native-Windows steps (PowerShell, env-var syntax), lead with the double-click launcher, and answer "is there an installer?" honestly (launcher + PWA install today; a signed .msi needs a build/sign pipeline — future). Also soften the cloud-AI consent wording to not promise an exact UI screen, and tidy the demo-seed instructions. Full suite green (4,091); production `pnpm start` boots and serves v2.0.0.
1 parent f7814a7 commit b209334

6 files changed

Lines changed: 183 additions & 32 deletions

File tree

‎README.md‎

Lines changed: 64 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -111,10 +111,12 @@ keep going, but every claim is backed by a passing test and an unflinching `FEAT
111111
- **It's free software you run on _your own_ computer.** There's no App Store, no
112112
website to sign up for, no subscription, and nothing of yours ever leaves your
113113
machine.
114-
- **It's not a double-click `.exe` (yet).** You'll copy-and-paste a few commands
115-
into a plain text window called a **Terminal**. That's the only unfamiliar part —
116-
everything is copy-paste, and we explain each line. Budget about **20–30 minutes**
117-
the first time. After that, starting Fables is **one command**.
114+
- **There's no App-Store/installer package (yet), but it's friendly.** A
115+
**double-click launcher** handles first-time setup and starting for you, and if
116+
you prefer, every step is plain copy-and-paste into a **Terminal** — we explain
117+
each line. The only one-time chore is installing two free tools (Step 1). Budget
118+
about **20–30 minutes** the first time; after that, opening Fables is one
119+
double-click.
118120
- **Where it lives:** put it in **any** folder you like — your home folder or
119121
Documents is perfect, and it doesn't need to be anywhere special. **One nuance:**
120122
if you plan to keep tinkering with Fables itself using **Claude Code** (e.g.
@@ -132,15 +134,31 @@ keep going, but every claim is backed by a passing test and an unflinching `FEAT
132134
[Step 7](#step-7-optional--add-power-ups-ai-art-and-voices). **None are required**,
133135
and any cloud option stays off until you explicitly opt in.
134136

137+
### The easiest way (any computer): the double-click launcher
138+
139+
After you've done the one-time setup in **Step 1** below (install Node.js + pnpm)
140+
and downloaded Fables (**Step 2**), you can skip the typing entirely and just
141+
**double-click the launcher** in the `Fables` folder:
142+
143+
- **Windows:** `start-fables.cmd`
144+
- **Mac:** `start-fables.command` _(first time: right-click → **Open** to get past the
145+
"unidentified developer" prompt)_
146+
- **Linux:** `start-fables.sh`
147+
148+
The first time, it sets itself up (downloads components and builds — a few minutes);
149+
after that it just starts Fables and opens it in your browser. Keep the little
150+
window it opens running while you use Fables; close it to stop. If you'd rather
151+
type the commands yourself (or something goes wrong), the manual steps below do
152+
exactly the same thing.
153+
135154
### Which computer are you on?
136155

137-
- **Mac** — the smoothest path. Follow the steps as written.
138-
- **Linux** — also smooth. Follow the steps as written.
139-
- **Windows** — Fables runs best inside **WSL** (Windows Subsystem for Linux), a
140-
free, official Microsoft feature that gives you a tidy Linux environment where
141-
these tools "just work." One-time setup: open **PowerShell as Administrator**, run
142-
`wsl --install`, restart, and pick a username/password when prompted. Then open
143-
the new **Ubuntu** app from your Start menu and follow the steps below inside it.
156+
- **Mac** and **Linux** — follow the steps as written.
157+
- **Windows** — works natively, **no WSL or Linux needed.** Use **PowerShell**
158+
(search "PowerShell" in the Start menu) wherever the steps say "Terminal." The
159+
database component ships a ready-made Windows build, so there's nothing to
160+
compile. The only Windows-specific detail is how you set optional settings like
161+
AI keys — noted in [Step 7](#step-7-optional--add-power-ups-ai-art-and-voices).
144162

145163
---
146164

@@ -199,8 +217,11 @@ When it's running you'll see log lines and it will **keep running** — that's g
199217
**Leave this Terminal window open**; closing it stops Fables. (To stop it on
200218
purpose, click the window and press **Ctrl + C**.)
201219

202-
> Want a few example notes and a sample story to explore? In a **second** Terminal
203-
> window (same `Fables` folder), run `pnpm seed:demo` once before starting.
220+
> _(Tip: instead of these three commands you can just double-click the launcher —
221+
> see [the easiest way](#the-easiest-way-any-computer-the-double-click-launcher) above.)_
222+
>
223+
> Want a few example notes and a sample story to explore first? Run
224+
> `pnpm seed:demo` once, then `pnpm start`.
204225
205226
### Step 4 — Open it on your laptop
206227

@@ -258,6 +279,18 @@ App Store needed.
258279
**Install**. You'll get a Fables icon you can pin to your **dock / taskbar / Start
259280
menu** and launch like any app. (Safari on Mac: **File → Add to Dock**.)
260281

282+
> **"Is there a one-click `.exe`/`.msi` installer?"** Not yet — and here's the
283+
> honest state of it. Two pieces already give you the app-like experience: the
284+
> **double-click launcher** (`start-fables.cmd`) starts the engine without typing,
285+
> and the **PWA install** above gives you a real Start-menu/taskbar icon. What's
286+
> _not_ here yet is a single signed installer that bundles everything and
287+
> auto-starts on boot — that needs a Windows build-and-code-signing pipeline
288+
> (otherwise Windows SmartScreen warns users), so it's a deliberate future
289+
> enhancement rather than something half-built. If you'd like Fables to **start
290+
> automatically when Windows boots** in the meantime, that's a small one-time
291+
> setup (a shortcut to `start-fables.cmd` in the Startup folder, or a Task
292+
> Scheduler entry) — ask and we'll add the exact steps.
293+
261294
### Step 7 (optional) — Add power-ups: AI, art, and voices
262295

263296
**You don't need any of these to use Fables.** Everything except these specific
@@ -268,21 +301,27 @@ your own machine, fully private) or **cloud** (a hosted service, faster/stronger
268301
but data leaves your machine — so it's always **opt-in and consent-gated**).
269302

270303
> **How to give Fables a setting:** these are turned on with **environment
271-
> variables** at start time. The easy way is to put them in front of the start
272-
> command, e.g.
273-
> `ANTHROPIC_API_KEY="sk-ant-…" FABLES_COMFY_URL="http://127.0.0.1:8188" pnpm start`.
274-
> You can combine as many as you like on one line.
304+
> variables** at start time.
305+
>
306+
> - **Mac / Linux:** put them in front of the start command —
307+
> `ANTHROPIC_API_KEY="sk-ant-…" FABLES_COMFY_URL="http://127.0.0.1:8188" pnpm start`
308+
> - **Windows (PowerShell):** set them first, then start —
309+
> `$env:ANTHROPIC_API_KEY="sk-ant-…"`, then `pnpm start` (they last for that
310+
> window; use `setx ANTHROPIC_API_KEY "sk-ant-…"` to remember them permanently).
311+
>
312+
> Using the double-click launcher? Open it in a text editor and add your settings
313+
> near the top — there's a comment showing where.
275314
276315
#### 🤖 AI writing help (RAG "ask your vault", summaries, tags, the story/character co-writer)
277316

278317
Pick **either** a local model **or** Claude (or both — Fables prefers whichever is
279318
available, and you can route per-feature):
280319

281-
| Option | Private? | How to set it up |
282-
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
283-
| **Ollama** (local, easiest) | ✅ 100% on-device | Install [Ollama](https://ollama.com), run `ollama pull llama3.1` (or any model). Fables **auto-detects** it on the default port. Override with `FABLES_OLLAMA_URL`. |
284-
| **llama.cpp** (local) | ✅ 100% on-device | Run `llama-server`. Set `FABLES_LLAMACPP_URL` if it's not on `http://127.0.0.1:8080`. |
285-
| **Claude API** (cloud) | ⚠️ Opt-in | Get a key at [console.anthropic.com](https://console.anthropic.com), set `ANTHROPIC_API_KEY="sk-ant-…"`. **Two locks:** the key enables the adapter, **and** you must turn cloud AI on + accept the egress-consent prompt inside Fables (Settings → AI). Nothing is sent until you do. A global **kill switch** turns all AI off instantly, and secret/encrypted notes are filtered out before any prompt is built. |
320+
| Option | Private? | How to set it up |
321+
| --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
322+
| **Ollama** (local, easiest) | ✅ 100% on-device | Install [Ollama](https://ollama.com), run `ollama pull llama3.1` (or any model). Fables **auto-detects** it on the default port. Override with `FABLES_OLLAMA_URL`. |
323+
| **llama.cpp** (local) | ✅ 100% on-device | Run `llama-server`. Set `FABLES_LLAMACPP_URL` if it's not on `http://127.0.0.1:8080`. |
324+
| **Claude API** (cloud) | ⚠️ Opt-in | Get a key at [console.anthropic.com](https://console.anthropic.com), set `ANTHROPIC_API_KEY="sk-ant-…"`. **Two locks:** the key enables the adapter, **and** the cloud path stays off until you explicitly enable it and grant egress consent (via Fables' AI settings, or the `/api/v1/ai/settings` endpoint). Nothing is sent until you do. A global **kill switch** turns all AI off instantly, and secret/encrypted notes are filtered out before any prompt is built. |
286325

287326
#### 🎨 Generated art (cover & scene illustrations for your stories, via Stable Diffusion / Flux, etc.)
288327

@@ -325,8 +364,9 @@ and accept its consent prompt.**
325364

326365
- **`command not found` for `pnpm` or `node`** — Step 1 didn't finish; reinstall
327366
Node.js, close and reopen the Terminal, and try again.
328-
- **"port already in use"** — something else is on port 4870. Start on another port:
329-
`PORT=4871 pnpm start` (and then `tailscale serve --bg 4871`).
367+
- **"port already in use"** — something else is on port 4870. Start on another port
368+
(Mac/Linux: `PORT=4871 pnpm start`; Windows PowerShell: `$env:PORT="4871"; pnpm start`),
369+
then `tailscale serve --bg 4871`.
330370
- **The phone can't reach it** — make sure (a) Fables is still running on the
331371
laptop, (b) `tailscale serve` is running, and (c) both devices are signed into the
332372
**same** Tailscale account. Run `pnpm doctor` on the laptop for a quick health

‎apps/server/package.json‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,17 @@
44
"private": true,
55
"type": "module",
66
"scripts": {
7-
"dev": "NODE_OPTIONS=--conditions=development tsx watch src/server.ts",
7+
"dev": "cross-env NODE_OPTIONS=--conditions=development tsx watch src/server.ts",
88
"build": "tsc -p tsconfig.json",
99
"typecheck": "tsc -p tsconfig.json --noEmit",
1010
"start": "node dist/server.js",
11-
"db:backup": "NODE_OPTIONS=--conditions=development tsx src/db/cli.ts backup",
12-
"db:check": "NODE_OPTIONS=--conditions=development tsx src/db/cli.ts check",
13-
"db:seed": "NODE_OPTIONS=--conditions=development tsx src/db/cli.ts seed",
14-
"seed:demo": "NODE_OPTIONS=--conditions=development tsx src/db/cli.ts seed:demo",
15-
"forge:run": "NODE_OPTIONS=--conditions=development tsx src/cli/forge-run.ts",
16-
"import:vault": "NODE_OPTIONS=--conditions=development tsx src/cli/import.ts",
17-
"import": "NODE_OPTIONS=--conditions=development tsx src/cli/import-source.ts"
11+
"db:backup": "cross-env NODE_OPTIONS=--conditions=development tsx src/db/cli.ts backup",
12+
"db:check": "cross-env NODE_OPTIONS=--conditions=development tsx src/db/cli.ts check",
13+
"db:seed": "cross-env NODE_OPTIONS=--conditions=development tsx src/db/cli.ts seed",
14+
"seed:demo": "cross-env NODE_OPTIONS=--conditions=development tsx src/db/cli.ts seed:demo",
15+
"forge:run": "cross-env NODE_OPTIONS=--conditions=development tsx src/cli/forge-run.ts",
16+
"import:vault": "cross-env NODE_OPTIONS=--conditions=development tsx src/cli/import.ts",
17+
"import": "cross-env NODE_OPTIONS=--conditions=development tsx src/cli/import-source.ts"
1818
},
1919
"dependencies": {
2020
"@fables/core": "workspace:*",
@@ -41,6 +41,7 @@
4141
"devDependencies": {
4242
"@types/better-sqlite3": "^7.6.13",
4343
"@types/node": "^22.19.21",
44+
"cross-env": "^7.0.3",
4445
"pino-pretty": "^13.0.0",
4546
"tsx": "^4.20.0"
4647
}

‎pnpm-lock.yaml‎

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎start-fables.cmd‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
@echo off
2+
setlocal
3+
cd /d "%~dp0"
4+
5+
rem ===== Optional power-ups: remove the "rem " and fill in to enable =====
6+
rem set "ANTHROPIC_API_KEY=sk-ant-..."
7+
rem set "FABLES_COMFY_URL=http://127.0.0.1:8188"
8+
rem set "FABLES_OLLAMA_URL=http://127.0.0.1:11434"
9+
rem (see the "Add power-ups" section of README.md for the full list)
10+
rem ======================================================================
11+
12+
where pnpm >/dev/null 2>/dev/null
13+
if errorlevel 1 (
14+
echo.
15+
echo Fables needs two free tools first: Node.js and pnpm.
16+
echo Open README.md and follow "Install Fables - the gentle, step-by-step guide".
17+
echo.
18+
pause
19+
exit /b 1
20+
)
21+
22+
if not exist "node_modules" (
23+
echo First-time setup: downloading components ^(a few minutes, one time^)...
24+
call pnpm install || ( echo Setup failed. & pause & exit /b 1 )
25+
)
26+
27+
if not exist "apps\server\dist\server.js" (
28+
echo First-time setup: building Fables ^(a few minutes, one time^)...
29+
call pnpm build || ( echo Build failed. & pause & exit /b 1 )
30+
)
31+
32+
echo.
33+
echo Starting Fables. Keep this window open while you use it.
34+
echo Opening http://localhost:4870 in your browser...
35+
start "" "http://localhost:4870"
36+
call pnpm start
37+
pause

‎start-fables.command‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
#!/bin/bash
2+
# Double-clickable launcher for macOS. First time: right-click -> Open if macOS
3+
# warns about an unidentified developer.
4+
cd "$(dirname "$0")" || exit 1
5+
6+
# ===== Optional power-ups: remove the "#" and fill in to enable =====
7+
# export ANTHROPIC_API_KEY="sk-ant-..."
8+
# export FABLES_COMFY_URL="http://127.0.0.1:8188"
9+
# export FABLES_OLLAMA_URL="http://127.0.0.1:11434"
10+
# (see the "Add power-ups" section of README.md for the full list)
11+
# ===================================================================
12+
13+
if ! command -v pnpm >/dev/null 2>&1; then
14+
echo
15+
echo " Fables needs two free tools first: Node.js and pnpm."
16+
echo " Open README.md and follow \"Install Fables - the gentle, step-by-step guide\"."
17+
echo
18+
read -n 1 -s -r -p " Press any key to close..."
19+
exit 1
20+
fi
21+
22+
if [ ! -d node_modules ]; then
23+
echo " First-time setup: downloading components (a few minutes, one time)..."
24+
pnpm install || { read -n 1 -s -r -p " Setup failed. Press any key..."; exit 1; }
25+
fi
26+
if [ ! -f apps/server/dist/server.js ]; then
27+
echo " First-time setup: building Fables (a few minutes, one time)..."
28+
pnpm build || { read -n 1 -s -r -p " Build failed. Press any key..."; exit 1; }
29+
fi
30+
31+
echo
32+
echo " Starting Fables. Keep this window open while you use it."
33+
( sleep 2; open "http://localhost:4870" ) >/dev/null 2>&1 &
34+
pnpm start

‎start-fables.sh‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#!/bin/bash
2+
# Runnable / double-clickable launcher for Linux.
3+
cd "$(dirname "$0")" || exit 1
4+
5+
# ===== Optional power-ups: remove the "#" and fill in to enable =====
6+
# export ANTHROPIC_API_KEY="sk-ant-..."
7+
# export FABLES_COMFY_URL="http://127.0.0.1:8188"
8+
# export FABLES_OLLAMA_URL="http://127.0.0.1:11434"
9+
# (see the "Add power-ups" section of README.md for the full list)
10+
# ===================================================================
11+
12+
if ! command -v pnpm >/dev/null 2>&1; then
13+
echo
14+
echo " Fables needs two free tools first: Node.js and pnpm."
15+
echo " Open README.md and follow \"Install Fables - the gentle, step-by-step guide\"."
16+
echo
17+
read -n 1 -s -r -p " Press any key to close..."
18+
exit 1
19+
fi
20+
21+
[ -d node_modules ] || { echo " First-time setup: downloading components..."; pnpm install || exit 1; }
22+
[ -f apps/server/dist/server.js ] || { echo " First-time setup: building Fables..."; pnpm build || exit 1; }
23+
24+
echo
25+
echo " Starting Fables. Keep this window open while you use it."
26+
( sleep 2; xdg-open "http://localhost:4870" >/dev/null 2>&1 ) &
27+
pnpm start

0 commit comments

Comments
 (0)