@turmind/halo 0.1.9 → 0.2.0

package/bundled-docs/dev/desktop-packaging.md

@@ -1,9 +1,12 @@
 # Desktop Packaging (Electron / DMG)
 
-How to build the macOS desktop app (`Halo-0.1.5-arm64.dmg`). The desktop
-build is a thin Electron shell (`packages/desktop`) that bundles a self-
-contained server runtime + a private `node` binary + the admin static export,
-then spawns the server as a child process and points a `BrowserWindow` at it.
+How to build the desktop app. We ship two artifacts: **Windows x64**
+(`Halo Setup <ver>.exe`, built on a Linux host) and **macOS arm64**
+(`Halo-<ver>-arm64.dmg`, built on Apple Silicon) — see the target matrix
+below. The desktop build is a thin Electron shell (`packages/desktop`) that
+bundles a self-contained server runtime + a private `node` binary + the admin
+static export, then spawns the server as a child process and points a
+`BrowserWindow` at it.
 
 See [design](../design/) for the server itself; this doc is only about the
 packaging pipeline.
@@ -36,6 +39,13 @@ one.
 
 ```bash
 cd packages/halo   # repo root
+# 0. VERSION GATE — confirm every package is on the release version BEFORE
+#    building or tagging. The five packages must move in lockstep; a single
+#    lagging one ships a mismatched build and a wrong `halo --version`.
+for f in packages/{core,server,admin,cli,desktop}/package.json; do
+  printf "%-32s " "$f:"; grep -m1 '"version"' "$f"
+done   # all five must read the same x.y.z, and match the tag you're about to cut
+
 # 1. build the upstream artifacts the stage script consumes, IN ORDER.
 #    - core MUST build before server: server imports @turmind/halo-core
 #      (e.g. GitManager in routes/git.ts). A stale/missing core/dist makes
@@ -58,8 +68,47 @@ Output: `packages/desktop/dist/Halo-0.1.5-arm64.dmg` (~143 MB).
 `gen-icon` → `prepack-dmg` (`scripts/stage-runtime.mjs`) → `electron-builder
 --mac --arm64`.
 
-Other targets: `pnpm dist:x64` (Intel mac), `pnpm dist:win` (Windows nsis,
-cross-staged from mac).
+## Release target matrix (current policy)
+
+Two shipped artifacts per release, each built on its native-ish host:
+
+| Target | Host we build on | Command | Notes |
+|--------|------------------|---------|-------|
+| **Windows x64** (`Halo Setup <ver>.exe`, nsis) | **Linux x86_64** | `HALO_STAGE_FULL=1 CI=true pnpm dist:win` | host arch == target arch (x64), so native fixups are low-risk. This is now the standard path — *not* cross-staged from mac. |
+| **macOS arm64** (`Halo-<ver>-arm64.dmg`) | macOS (Apple Silicon) | `CI=true pnpm dist:arm64` | Apple Silicon only. |
+
+**`pnpm dist:x64` (Intel mac) is retired — we no longer ship an Intel build.**
+The `dist:x64` script still exists in `package.json` but is not part of any
+release; don't cut one.
+
+### Building the Windows exe on Linux (the standard path)
+
+```bash
+# from repo root — build upstream artifacts in order (see step 1 below), then:
+cd packages/desktop
+HALO_STAGE_FULL=1 CI=true pnpm dist:win
+```
+
+`HALO_STAGE_FULL=1` is **mandatory** here: a cross-stage must re-run the
+per-target native fixups (`@parcel/watcher-win32-x64` swap, `better-sqlite3`
+win prebuild), which the fast path skips. `wine` must be installed (electron-
+builder runs the nsis maker through it).
+
+Verified on the v0.1.9 build (Linux x86_64 host → win-x64):
+- **No poisoned arm64 dmg to discard.** Unlike a mac host, a Linux `--win` run
+  never triggers the yml's mac target — `dist/` contains only `Halo Setup
+  <ver>.exe` + `.exe.blockmap` + `win-unpacked/`. The "discard the stray
+  arm64 dmg" gotcha below is mac-host-only.
+- **Native arch check** — every staged `.node` must be PE32+ x86-64, no ELF:
+  `find dist/win-unpacked -path '*watcher-*' -name '*.node' | xargs file` and
+  `file dist/win-unpacked/resources/node.exe` (should read `PE32+ ... x86-64`).
+- **Two benign warnings**, both expected: `file source doesn't exist
+  from=.../resources/node` (win bundles `node.exe`, not the Unix `node` — the
+  yml lists both, electron-builder skips the absent one) and `signing is
+  skipped` (no Windows code-sign cert). Neither fails the build.
+
+> A `desktop-packaging.local.md` (gitignored, per-host) may carry extra
+> machine-specific setup — read it first if present.
 
 ## Faster rebuilds
 
@@ -138,8 +187,10 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
 2. **Copy `templates/`** — `pnpm deploy` doesn't pick these up; copied
    explicitly. This is what carries the built-in skills (incl. `send-file`),
    agents, prompts, models into the dmg.
-3. **Cross-arch native fixup** — when target arch/platform ≠ host, re-fetch
-   `better-sqlite3` prebuilds via `prebuild-install`.
+3. **Native fixup** — re-fetch `better-sqlite3` prebuilds via `prebuild-install
+   --target=22.11.0` **unconditionally** (pins the ABI to the bundled node
+   regardless of the build host's node — see the ABI gotcha below);
+   `@parcel/watcher`'s per-platform binary is swapped only when cross-staging.
 4. **Trim bloat** — drop non-target `node-pty` prebuilds, `better-sqlite3`'s
    C source, and the server's `src/`/`tests/`.
 5. **Copy `admin-out/`** — the Next.js static export.
@@ -147,6 +198,9 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
    nodejs.org, extract the `node` binary into `resources/`.
 7. **codesign (ad-hoc)** — `codesign --force --sign -` on the node binary for
    Gatekeeper. **We deliberately do NOT `strip`** — see gotcha below.
+8. **Native-addon smoke test** — load the staged better-sqlite3 with the
+   bundled node binary; abort the build if it can't `dlopen` (the ABI backstop,
+   runs on full and fast paths). See the ABI gotcha below.
 
 ## Gotchas (learned the hard way)
 
@@ -178,6 +232,28 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   looks fine but won't boot. Keep the full ~114 MB binary; the ~30 MB saved
   isn't worth a dead app. (`stage-runtime.mjs` has the strip step removed.)
 
+- **better-sqlite3's ABI must match the BUNDLED node (22.11.0 / ABI 127), not
+  the build host's node.** `pnpm deploy` / `npm install` hard-link whatever
+  `.node` the build host's *active* node produced. If a homebrew/nvm node 23
+  (ABI 131) shadows the pinned 22 on the build machine, the staged
+  `better_sqlite3.node` is ABI 131 — but the app runs it on the bundled node 22,
+  so it dies at launch with `NODE_MODULE_VERSION 131 ... requires 127`
+  (`ERR_DLOPEN_FAILED`, server `code=1`). The dmg packages fine and runs on the
+  builder's own machine (whose node happens to match), so it ships broken to
+  everyone else. Three guards now prevent this, all in `stage-runtime.mjs`:
+  1. `fetchTargetArchNatives()` runs `prebuild-install --target=22.11.0` for
+     better-sqlite3 **unconditionally** (not just when cross-staging), so the
+     ABI is always re-pinned to the bundled node regardless of the host node.
+  2. An early gate aborts if the build host's node major ≠ the bundled major
+     (`nvm use 22` then rebuild; override with `HALO_SKIP_NODE_CHECK=1`).
+  3. `smokeTestNativeAddons()` loads the staged better-sqlite3 with the bundled
+     node binary at the end of every stage (full AND fast) and aborts the build
+     if it can't `dlopen` — the final backstop no matter how a bad ABI crept in
+     (wrong host node, a fast path reusing a stale tree, a future native dep).
+  Verify a built dmg manually: `"<app>/Contents/Resources/node" -e
+  "new (require('<app>/Contents/Resources/server-runtime/node_modules/better-sqlite3'))(':memory:')"`
+  should exit 0.
+
 - **Desktop port is sequential from 9527 (NOT random), and that's load-bearing
   for persistence.** `main.cjs` `findFreePort()` tries 9527 first, then scans
   upward for the first free one, and passes it to the server child. It used to
@@ -236,6 +312,16 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   with `&& node scripts/copy-monaco.mjs`. If you must run `next build`
   directly, append the copy step yourself.
 
+- **All five package versions must move in lockstep — check before building or
+  tagging.** `core` / `server` / `admin` / `cli` / `desktop` each carry their own
+  `version` in `package.json`, and nothing auto-syncs them. When cutting 0.1.9,
+  `cli` + `desktop` were already bumped by hand but `server` sat at 0.1.8 and
+  `core` / `admin` at 0.1.0 — a `git tag` then would have shipped a build whose
+  `halo --version` (stamped from `package.json`) disagreed with the tag. The
+  step-0 version gate in "One-shot build" loops over all five so a lagging one is
+  caught before the tag is cut. (npm only publishes `cli` as `@turmind/halo`, but
+  the others feed `halo --version` / the admin sidebar, so they still matter.)
+
 - **Changing anything under `templates/` requires bumping `TEMPLATE_VERSION`
   (`packages/server/src/init.ts`) — otherwise the change never reaches existing
   installs.** Server startup only re-runs `ensureHaloHome` (the template

package/bundled-docs/guide/getting-started.md

@@ -6,8 +6,9 @@ What to do the first time you open Halo.
 
 Open `http://localhost:9527` (or your deployment URL) in a browser and enter the password.
 
-- The default password is printed to the **server console** (auto-generated if you haven't set `HALO_PASSWORD`)
-- You can also pin a password via `server.password` in `~/.halo/secrets/config.yaml`
+- Set the password during `halo setup` (interactive) — it's stored as a scrypt hash in `~/.halo/secrets/config.yaml`
+- Or supply it via the `HALO_PASSWORD` env var (handy for CI / Docker), which takes precedence over the stored hash
+- If neither is set, the server refuses to start (it prints `admin password not configured` and exits)
 
 ## Open a workspace
 

package/bundled-docs/requirements/explorer.md

@@ -12,6 +12,16 @@ VS Code-style file tree sidebar with multi-select, drag-drop, right-click menu.
 ### Path input
 - Explorer top bar has a path input + 📁🔍 picker button
 - Pressing Enter calls `GET /api/fs/exists?path=...` first — a miss shows an alert, no switch
+- **Recent-workspaces dropdown**: focusing the input shows the most-recently-used list; typing filters it by substring. Each row shows the folder name + full path; clicking one switches to it; a hover "×" removes a single entry. Entries are recorded only after a switch validates the path (so invalid paths never land), in canonical resolved form, MRU-ordered and deduped, capped at 8. Persisted in localStorage (`halo_recent_workspaces`)
+
+### Desktop windows (multi-window)
+Desktop app only — the browser has one tab per window natively.
+- **New window**: `Cmd+N` (macOS, via the File menu) / `Ctrl+N` (Windows/Linux, bound at the webContents level since those platforms have no app menu). Each window is a fresh view onto the **one shared local server** — no second server process spawns.
+- **Per-window workspace**: windows share the server origin, hence one localStorage, so a window tracks its own workspace via its URL `?folder=` (not localStorage, which would clobber across windows). Different windows can sit on different workspaces; the same workspace can be open in two windows.
+- **Quit semantics** (platform split): on macOS, closing every window keeps the app in the Dock (only `Cmd+Q` truly exits) and clicking the Dock icon reopens a window; on Windows/Linux there's no Dock to resummon from, so closing the last window quits.
+- **Pin (always-on-top)** acts per-window — each window pins independently.
+- **Activity awareness**: while the agent streams a reply the sidebar's workspace name carries an amber pulsing dot (emerald when idle) and the window title gains a `●` prefix (`● Halo — <name>` busy vs `Halo — <name>` idle) — both are plain web behaviour that Electron mirrors to the native title bar.
+- **Finish notification** (works in both the desktop app and a plain browser): an opt-in bell toggle sits in the activity bar next to the pin, **off by default**, persisted per-machine in localStorage (`halo_notify_on_finish`). It's shown whenever a notification can be raised — the desktop shell (`window.haloNotify` bridge) or a browser with the Web Notification API; turning it on in a browser requests Notification permission from within the toggle click (the required user gesture). When on, the busy→idle edge of the *same* still-open session triggers two decoupled cues: a **self-synthesized WebAudio chime** that always plays (regardless of focus — an audible "it's done" even while you're watching the tab, and not subject to the OS per-site notification-sound setting), plus — **only when the window is unfocused** — a banner (desktop: native notification + Dock bounce / taskbar flash; browser: a Web Notification whose click refocuses the tab). Focused → chime only, no banner.
 
 ### Directory picker (FolderPicker modal)
 Visual directory browser opened by the 📁🔍 button:
@@ -54,6 +64,7 @@ Items shown depend on the click target:
 |---|---|---|
 | New File / New Folder | Always | `POST /api/files/new` · `mkdir`; auto-expands the parent folder so the inline input is visible |
 | Open in Integrated Terminal | Always | Spawns a terminal at the target dir (or file's parent) |
+| Reveal in File Manager | Desktop app only | Opens the OS file manager (Finder / Explorer / Linux FM) at the target — a folder opens itself, a file is highlighted in its parent dir. Hidden in a plain browser (gated on the `window.haloReveal` IPC bridge exposed by the desktop preload) |
 | Open to the Side | File only | Splits the editor and opens the file in the right pane |
 | Download | File only | `GET /api/files/download?path=...` |
 | Rename | Single file/folder | `POST /api/files/rename` |