Skip to content
Back to search

https://github.com/NeuroSkill-com/skill

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NeuroSkill-com/skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NeuroSkill-com/skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neuroskill-com--skill/badge.svg)](/listings/neuroskill-com--skill)

HTML

<a href="/listings/neuroskill-com--skill"><img src="/api/listings/neuroskill-com--skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Product version lives in the repo-root [`VERSION`](VERSION) file (`npm run bump` keeps `package.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml` in sync). Release builds enable one daemon OS umbrella (`apple` / `linux` / `windows`). PR CI runs clippy/tests; signed product builds run on release tags or Preview Build. Details: [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

`npm run setup` checks that Rust is installed, offers to install Node.js 22 into `~/.local` if it is missing or older than 22.17, offers to install CMake, protoc and the other native build tools (Homebrew on macOS, the system package manager on Linux), and installs the JavaScript dependencies with `npm ci`, the same way CI does. On Windows, follow [docs/WINDOWS.md](docs/WINDOWS.md) instead.

Install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) (`curl -LsSf https://hf.co/cli/install.sh | bash` on macOS/Linux, `powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"` on Windows), then:

npm run setup -- --yes
hf download Zyphra/ZUNA
npm run tauri dev

Build production app:

npm run tauri:build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 4,351 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # NeuroSkill™ CLI — Complete Reference
  2. NeuroSkill™ exposes a real-time EEG analysis API through a local WebSocket server and an HTTP tunnel.
  3. The `cli.ts` script is the fastest way to query it from a terminal, shell script, or any
  4. automation pipeline.
  5. ---
  6. ## Contents
  7. 1. [Supported Devices](#supported-devices)
  8. 2. [Transport — WebSocket & HTTP](#transport--websocket--http)
  9. 3. [Quick Start](#quick-start)
  10. 4. [Output Modes](#output-modes)
  11. - [Default — summary only](#default-no-flag--human-readable-summary-only)
  12. - [`--json` — raw JSON, pipe-safe](#--json--raw-json-only-pipe-safe)
  13. - [`--full` — summary and JSON](#--full--human-readable-summary-and-colorized-json)
  14. - [What `--full` reveals](#what---full-reveals)
  15. 5. [Global Options](#global-options)
  16. 6. [Polling with `status`](#polling-with-status)
  17. 7. [Commands](#commands)
  18. - [status](#status)
  19. - [session](#session)
  20. - [sessions](#sessions)
  21. - [say](#say)
  22. - [label](#label)
  23. - [hooks](#hooks)
  24. - [search-labels](#search-labels)
  25. - [interactive](#interactive)
  26. - [search](#search)
  27. - [compare](#compare)
  28. - [sleep](#sleep)
  29. - [sleep-schedule](#sleep-schedule)
  30. - [umap](#umap)
  31. - [listen](#listen)
  32. - [notify](#notify)
  33. - [calibrations](#calibrations)
  34. - [calibrate](#calibrate)
  35. - [timer](#timer)
  36. - [health](#health)
  37. - [dnd](#dnd)
  38. - [raw](#raw)
  39. - [search-images](#search-images)
  40. - [screenshots-around](#screenshots-around)
  41. - [screenshots-for-eeg](#screenshots-for-eeg)
  42. - [eeg-for-screenshots](#eeg-for-screenshots)
  43. 8. [Screenshots](#screenshots)
  44. 9. [Data Reference](#data-reference)
  45. - [EEG Band Powers](#eeg-band-powers)
  46. - [EEG Ratios & Indices](#eeg-ratios--indices)
  47. - [Core Scores](#core-scores)
  48. - [Complexity Measures](#complexity-measures)
  49. - [PPG / Heart Rate Variability](#ppg--heart-rate-variability)
  50. - [Motion & Artifacts](#motion--artifacts)
  51. - [Sleep Stages](#sleep-stages)
  52. - [Migraine EEG Correlate](#migraine-eeg-correlate)
  53. - [Consciousness Metrics](#consciousness-metrics)
  54. 10. [Use-Case Recipes](#use-case-recipes)
  55. - [Focus & Productivity](#focus--productivity)
  56. - [Stress & Anxiety](#stress--anxiety)
  57. - [Sleep Quality](#sleep-quality)
  58. - [Cognitive Load](#cognitive-load)
  59. - [Meditation & Relaxation](#meditation--relaxation)
  60. - [Comparing Two Sessions](#comparing-two-sessions)
  61. - [Time-Range Queries](#time-range-queries)
  62. - [Automation & Scripting](#automation--scripting)
  63. ---
  64. ## Supported Devices
  65. NeuroSkill™ supports multiple EEG headsets. The CLI and API work identically
  66. regardless of which device is connected — all commands, scores, and metrics are
  67. device-agnostic.
  68. | Device | Channels | Sample Rate | Connection | Notes |
  69. |---|---|---|---|---|
  70. | **Muse** (S, 2, 2016) | 4 (TP9, AF7, AF8, TP10) | 256 Hz | BLE | Default device. PPG + IMU included. |
  71. | **OpenBCI Ganglion** | 4 | 200 Hz | BLE | Open-source research-grade board. |
  72. | **OpenBCI Cyton / Cyton+Daisy** | 8 / 16 | 250 Hz | Serial / WiFi | Full 10-20 montage capable. |
  73. | **Neurable MW75 Neuro** | 12 (FT7/T7/TP7/CP5/P7/C5, FT8/T8/TP8/CP6/P8/C6) | 500 Hz | BLE + RFCOMM | Noise-cancelling headphones with EEG. Behind `mw75-rfcomm` feature flag. |
  74. | **Vital Neuro** | 3 (ch1–ch3) | 250 Hz | BLE | Headphones with EEG; audio runs over a separate Bluetooth Classic link. Accelerometer + battery. Device reports no electrode montage. |
  75. | **RE-AK Nucleus Hermes** | 8 (Fp1, Fp2, AF3, AF4, F3, F4, FC1, FC2) | 250 Hz | BLE GATT | ADS1299 + 9-DOF IMU. |
  76. | **Emotiv** (EPOC/Insight/Flex/MN8) | 14 / 5 / 32 | 128 Hz | Cortex WebSocket | IMU included. Connected via Emotiv Cortex API. |
  77. | **IDUN Guardian** | 1 (bipolar in-ear) | 250 Hz | BLE | Single-channel earbud EEG + 6-DOF IMU. |
  78. | **Mendi** | — (fNIRS optical) | — | BLE | Frontal fNIRS headband with IMU + battery telemetry. Not traditional EEG. |
  79. | **Cognionics / CGX** (Quick-20/32r/8r, AIM-2, Patch) | 2–30 | up to 500 Hz | USB Serial (FTDI) | Research-grade; full 10-20 montage on Quick-20+. IMU on r/m variants. |
  80. | **AttentivU** | 4 ExG | 250 Hz | BLE | EEG glasses with 9-axis IMU. |
  81. | **BrainBit** (Original, 2, Pro, Flex 4/8) | 4 (O1, O2, T3, T4) | 250 Hz | BLE (NeuroSDK2) | Consumer EEG headband. |
  82. | **g.tec Unicorn Hybrid Black** | 8 | 250 Hz | BLE (Unicorn API) | Research-grade headset with IMU. |
  83. | **NeuroField Q21** | 20 | 256 Hz | PCAN-USB (CAN bus) | Full 10-20 montage. |
  84. | **BrainMaster** (Atlantis/Discovery/Freedom) | 2–24 | 256 Hz | USB Serial | Neurofeedback amplifiers. Discovery/Freedom support up to 24 channels. |
  85. | **NeuroSky MindWave** | 1 (Fp1) | 512 Hz | Serial (ThinkGear) | Single-channel consumer headset. |
  86. | **Neurosity** (Crown / Notion) | 8 (CP3, C3, F5, PO3, PO4, F6, C4, CP4) | 256 Hz | Cloud-streamed | IMU included. |
  87. | **Brain Products BrainVision** | 16 | 500 Hz | TCP/IP (RDA) | Research-grade; full 10-20 montage. |
  88. The DSP pipeline dynamically scales to the active channel count (1–32).
  89. Inactive channels have zero overhead.
  90. ---
  91. ## Transport — WebSocket & HTTP
  92. NeuroSkill™ runs a local server (auto-discovered via mDNS or `lsof`). All commands work over
  93. **both** transports; the CLI picks the best one automatically.
  94. ### WebSocket (`ws://127.0.0.1:<port>`)
  95. - **Full-duplex, low-latency.** Best for live data, event streaming, and polling loops.
  96. - Commands are JSON messages sent over the socket; responses arrive as JSON messages.
  97. - Supports real-time broadcast events (EEG packets, scores, label-created, …).
  98. - Used by default when the server is reachable.
  99. ```
  100. # Force WebSocket:
  101. node cli.ts status --ws
  102. # Direct WebSocket from any language (wscat example):
  103. wscat -c ws://127.0.0.1:8375
  104. > {"command":"status"}
  105. < {"command":"status","ok":true,"device":{...},"scores":{...},...}
  106. ```
  107. ### HTTP (`http://127.0.0.1:<port>/`)
  108. - **Request / response only.** No live streaming, no broadcast events.
  109. - All commands are `POST /` with a JSON body; the response is JSON.
  110. - Useful from `curl`, Python `requests`, Node `fetch`, or any HTTP client.
  111. - Automatic fallback when the WebSocket is unreachable.
  112. ```bash
  113. # Force HTTP:
  114. node cli.ts status --http
  115. # curl equivalent of every CLI command:
  116. curl -s -X POST http://127.0.0.1:8375/ \
  117. -H "Content-Type: application/json" \
  118. -d '{"command":"status"}'
  119. # Extract a single field with jq:
  120. curl -s -X POST http://127.0.0.1:8375/ \
  121. -H "Content-Type: application/json" \
  122. -d '{"command":"status"}' | jq '.scores.relaxation'
  123. ```
  124. ### Auto-transport (default)
  125. When neither `--ws` nor `--http` is given, the CLI probes WebSocket first and silently
  126. falls back to HTTP. Informational lines are written to **stderr** (not stdout), so JSON
  127. piping is never polluted.
  128. ### Port Discovery
  129. The CLI finds the port automatically via:
  130. 1. `--port <n>` flag (explicit, skips all discovery)
  131. 2. mDNS (`_skill._tcp` service advertisement, 5 s timeout)
  132. 3. `lsof` / `pgrep` fallback (probes each TCP LISTEN port)
  133. ```bash
  134. node cli.ts status --port 62853 # skip discovery entirely
  135. ```
  136. ---
  137. ## Quick Start
  138. ```bash
  139. # Prerequisites (run once):
  140. npm install
  141. # Snapshot of everything:
  142. node cli.ts status
  143. # Pipe-friendly JSON output:
  144. node cli.ts status --json | jq '.scores'
  145. # Print full help with examples:
  146. node cli.ts --help
  147. ```
  148. > **Aliases:** `node cli.ts`, `npx tsx cli.ts`, and `./cli.ts` (after `chmod +x`) all work.
  149. ---
  150. ## Output Modes
  151. Every command has three output modes. Choose the one that suits your use case.
  152. ### Default (no flag) — human-readable summary only
  153. The CLI prints a structured, colored, human-readable summary to **stdout**.
  154. The underlying raw JSON response is **not printed** — it is discarded after the
  155. summary is rendered.
  156. ```bash
  157. node cli.ts status # colored summary, no JSON
  158. node cli.ts session 0 # trend table, no JSON
  159. node cli.ts sleep # stage counts, no JSON
  160. ```
  161. This is the fastest way to read results at a glance, but data that the summary
  162. doesn't surface — such as per-epoch arrays, full reference objects, or every
  163. metric field — is silently dropped. See [What `--full` reveals](#what---full-reveals)
  164. for a command-by-command breakdown.
  165. ---
  166. ### `--json` — raw JSON only, pipe-safe
  167. `print()` calls are suppressed entirely; only `printResult()` fires.
  168. Output is plain JSON with no ANSI codes, written to **stdout**.
  169. Informational lines (transport, connection, mDNS discovery) go to **stderr** and
  170. never pollute the JSON stream.
  171. ```bash
  172. node cli.ts status --json # full JSON, no summary
  173. node cli.ts status --json | jq '.scores.relaxation' # pipe to jq
  174. node cli.ts sleep --json | jq '.summary'
  175. node cli.ts search --json | jq '.result.results[0].neighbors'
  176. node cli.ts umap --json | jq '.result.points | length'
  177. ```
  178. Use `--json` whenever you need to pipe output to another tool, parse it in a
  179. script, or feed it into an API.
  180. ---
  181. ### `--full` — human-readable summary **and** colorized JSON
  182. Both `print()` and `printResult()` fire. The human-readable summary prints first,
  183. then the complete colorized JSON response is appended below it.
  184. ```bash
  185. node cli.ts status --full # summary + full colorized JSON
  186. node cli.ts session 0 --full # trend table + raw first/second/trends objects
  187. node cli.ts sleep --full # stage counts + full epochs[] array
  188. node cli.ts umap --full # cluster analysis + full points[] array
  189. node cli.ts search --full # match summary + all neighbors for every query epoch
  190. ```
  191. `--full` is the inspection mode: use it when you want to see which exact fields the
  192. server returned, discover keys the summary omits, or verify data before writing a
  193. `--json` pipeline.
  194. > **Colors:** `--full` uses ANSI-colored JSON (keys in blue, strings in green,
  195. > numbers in cyan). If you need plain text from `--full`, pipe through `sed 's/\x1b\[[0-9;]*m//g'`
  196. > or just switch to `--json`.
  197. ---
  198. ### What `--full` reveals
  199. The following data exists in the server response but is **omitted by the default
  200. summary**. It is only visible with `--full` (colorized) or `--json` (plain).
  201. #### `status`
  202. | Hidden field | Type | Contents |
  203. |---|---|---|
  204. | `scores.faa`, `scores.tar`, `scores.bar` … | numbers | EEG ratios and spectral indices not surfaced in the summary's Scores section |
  205. | `calibration.actions[]` | array | Full ordered list of calibration step objects (name, duration, …) |
  206. | `labels.recent[]` | array | Full label objects; summary only prints text + timestamp |
  207. | `hooks.latest_trigger` | object | Most recent hook trigger across all hooks: `{ hook, triggered_at_utc, distance, label_id, label_text }`. The summary shows hook name, timestamp, and distance; the JSON has the full object. |
  208. | `history.today_vs_avg` | object | Per-metric today-vs-7-day-avg comparison table (metric, today, avg_7d, delta_pct, direction) |
  209. | `apps` | object | Most-used apps by window-switch count. Contains `top_all_time`, `top_24h`, `top_7d` arrays. Each entry: `{ app_name, switches, last_seen }`. |
  210. | `labels.top_all_time` | array | Most frequent label texts (all time). Each: `{ text, count }`. |
  211. | `labels.top_24h` / `labels.top_7d` | array | Most frequent label texts in the last 24 h / 7 d. |
  212. | `labels.embedded` | number | Count of labels with text embeddings computed. |
  213. | `screenshots` | object | Screenshot/OCR summary counts: `total`, `with_embedding`, `with_ocr`, `with_ocr_embedding`. Also `top_apps_all_time` and `top_apps_24h` arrays (each: `{ app_name, count }`). |
  214. ```bash
  215. node cli.ts status --json | jq '.history.today_vs_avg'
  216. node cli.ts status --json | jq '.calibration.actions'
  217. node cli.ts status --json | jq '.labels.recent'
  218. node cli.ts status --json | jq '.hooks.latest_trigger'
  219. node cli.ts status --json | jq '.apps.top_all_time[:5]'
  220. node cli.ts status --json | jq '.apps.top_24h'
  221. node cli.ts status --json | jq '.labels.top_all_time'
  222. node cli.ts status --json | jq '.screenshots'
  223. node cli.ts status --json | jq '.screenshots.top_apps_24h'
  224. ```
  225. #### `session`
  226. | Hidden field | Type | Contents |
  227. |---|---|---|
  228. | `first` | object | Every metric averaged over the **first half** of the session |
  229. | `second` | object | Every metric averaged over the **second half** |
  230. | `trends` | object | Direction string (`"up"` / `"down"` / `"flat"`) for every metric key |
  231. | `metrics` | object | All ~50 metric fields — the summary only prints a curated subset |
  232. ```bash
  233. node cli.ts session 0 --json | jq '.metrics' # all metric averages
  234. node cli.ts session 0 --json | jq '.trends' # all trend directions
  235. node cli.ts session 0 --json | jq '{r1: .first.relaxation, r2: .second.relaxation}'
  236. node cli.ts session 0 --json | jq '[.trends | to_entries[] | select(.value == "up") | .key]'
  237. ```
  238. #### `sessions`
  239. | Hidden field | Type | Contents |
  240. |---|---|---|
  241. | `sessions[]` | array | Raw session objects — the summary formats them into a table but the JSON contains the same data |
  242. ```bash
  243. node cli.ts sessions --json | jq '.sessions[0]'
  244. # → { "day": "20260224", "start_utc": 1740412800, "end_utc": 1740415510, "n_epochs": 541 }
  245. ```
  246. #### `search`
  247. | Hidden field | Type | Contents |
  248. |---|---|---|
  249. | `result.results[]` | array | Full list of query epochs, each with its complete `neighbors[]` array. The summary only shows the 5 closest overall — `--full` shows every neighbor for every query epoch. |
  250. | `result.analysis.temporal_distribution` | object | Hour-of-day match counts (the bar chart in the summary, but as raw numbers) |
  251. | `result.analysis.top_days` | array | `[["YYYYMMDD", count], …]` |
  252. ```bash
  253. node cli.ts search --json | jq '.result.results | length' # query epoch count
  254. node cli.ts search --json | jq '.result.results[0].neighbors' # all neighbors for epoch 0
  255. node cli.ts search --json | jq '[.result.results[].neighbors[]] | sort_by(.distance) | .[0]'
  256. node cli.ts search --json | jq '.result.analysis.temporal_distribution'
  257. ```
  258. #### `compare`
  259. | Hidden field | Type | Contents |
  260. |---|---|---|
  261. | `a` | object | All ~50 averaged metrics for session A |
  262. | `b` | object | All ~50 averaged metrics for session B |
  263. | `sleep_a` / `sleep_b` | objects | Full sleep staging summary for each range |
  264. | `insights.deltas` | object | Full delta table for every metric (not just the key ones shown in the summary) |
  265. | `umap` | object | Enqueued job info: `job_id`, `estimated_secs`, `n_a`, `n_b` |
  266. ```bash
  267. node cli.ts compare --json | jq '.a' # all metrics for A
  268. node cli.ts compare --json | jq '.b' # all metrics for B
  269. node cli.ts compare --json | jq '.insights.deltas' # every metric delta
  270. node cli.ts compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
  271. node cli.ts compare --json | jq '.umap.job_id' # use with umap --json
  272. ```
  273. #### `sleep`
  274. | Hidden field | Type | Contents |
  275. |---|---|---|
  276. | `epochs[]` | array | Per-epoch classification: `{ utc, stage, rel_delta, rel_theta, rel_alpha, rel_beta }` for every 5-second window. Can be thousands of entries for a full night. |
  277. ```bash
  278. node cli.ts sleep --json | jq '.epochs | length' # total epochs
  279. node cli.ts sleep --json | jq '.epochs[0]' # first epoch
  280. node cli.ts sleep --json | jq '[.epochs[] | select(.stage == 3)] | length' # N3 epochs
  281. node cli.ts sleep --json | jq '[.epochs[] | {utc: .utc, stage: .stage}]' # hypnogram data
  282. ```
  283. #### `umap`
  284. | Hidden field | Type | Contents |
  285. |---|---|---|
  286. | `result.points[]` | array | 3D coordinates for every embedding epoch: `{ x, y, z, session, utc, label? }`. Typically 500–2000+ entries. |
  287. ```bash
  288. node cli.ts umap --json | jq '.result.points | length'
  289. node cli.ts umap --json | jq '.result.points[0]'
  290. # → { "x": 1.23, "y": -0.45, "z": 2.01, "session": "A", "utc": 1740380105 }
  291. node cli.ts umap --json | jq '[.result.points[] | select(.session == "B")]'
  292. node cli.ts umap --json | jq '[.result.points[] | select(.label != null)]' # labeled points only
  293. ```
  294. #### `search-labels`
  295. | Hidden field | Type | Contents |
  296. |---|---|---|
  297. | `results[].eeg_metrics` | object | Full EEG metrics object for the label window — the summary shows only 5 fields; the JSON has all available metrics |
  298. | `results[].context` | string | Long-context string (if set) — only a truncated preview is shown in the summary |
  299. ```bash
  300. node cli.ts search-labels "deep focus" --json | jq '.results[0].eeg_metrics'
  301. node cli.ts search-labels "stress" --json | jq '[.results[].eeg_metrics.tbr]'
  302. node cli.ts search-labels "meditation" --json | jq '.results[0].context'
  303. ```
  304. #### `interactive`
  305. | Hidden field | Type | Contents |
  306. |---|---|---|
  307. | `nodes[]` | array | All graph nodes — the summary prints each layer; `--json` gives the raw array with all fields |
  308. | `edges[]` | array | All graph edges with `from_id`, `to_id`, `distance`, `kind` |
  309. | `dot` | string | Complete Graphviz DOT source — only accessible via `--dot` or `--json` (never printed in default or `--full`) |
  310. | `svg` | string | Pre-rendered SVG — PCA-scatter layout for found_labels |
  311. | `svg_col` | string | Pre-rendered SVG — column-per-EEG-parent layout |
  312. | `svg_3d` | string | Pre-rendered SVG — 3-D perspective-projected view of all nodes including screenshots (dark theme with depth cues) |
  313. | `nodes[].eeg_metrics` | object | Full EEG metrics for `text_label` nodes — the summary shows 5 fields; JSON has all |
  314. | `nodes[].proj_x/y/z` | numbers | 3-D PCA coordinates (normalised [-1, 1]) for all nodes with text embeddings |
  315. | `nodes[].filename` | string | Screenshot image path (screenshot nodes only) |
  316. | `nodes[].app_name` | string | Application name at capture time (screenshot nodes only) |
  317. | `nodes[].window_title` | string | Window title at capture time (screenshot nodes only) |
  318. | `nodes[].ocr_text` | string | OCR-extracted text (screenshot nodes only) |
  319. | `nodes[].ocr_similarity` | number | Cosine similarity between query and OCR text (screenshot nodes only) |
  320. ```bash
  321. node cli.ts interactive "deep focus" --json | jq '.nodes | length'
  322. node cli.ts interactive "meditation" --json | jq '.edges | map(.kind) | unique'
  323. node cli.ts interactive "anxiety" --json | jq '[.nodes[] | select(.kind == "text_label") | .text]'
  324. node cli.ts interactive "coding" --json | jq '[.nodes[] | select(.kind == "screenshot") | {file: .filename, app: .app_name}]'
  325. node cli.ts interactive "focus" --dot | dot -Tsvg > graph.svg # visualize with graphviz
  326. node cli.ts interactive "stress" --dot | dot -Tpng > graph.png
  327. node cli.ts interactive "relaxed" --json | jq '.dot' -r | dot -Tsvg > graph.svg # same via --json
  328. node cli.ts interactive "work" --json | jq '.svg_3d' -r > graph_3d.svg # 3D perspective SVG
  329. ```
  330. ---
  331. #### `say`
  332. Like `notify`, `say` produces only a one-line confirmation in default mode.
  333. | Hidden field | Type | Contents |
  334. |---|---|---|
  335. | `ok` | boolean | Confirmation that the utterance was enqueued |
  336. | `spoken` | string | Echo of the text that was sent to TTS |
  337. | `voice` | string | Voice name used (only present when `--voice` was specified) |
  338. ```bash
  339. node cli.ts say "Eyes open" --json
  340. # → { "command": "say", "ok": true, "spoken": "Eyes open" }
  341. ```
  342. ---
  343. #### `calibrations`
  344. The `calibrations` summary formats profiles into a table but the JSON contains
  345. the full profile objects with all actions, durations, and settings.
  346. | Hidden field | Type | Contents |
  347. |---|---|---|
  348. | `profiles[].actions[]` | array | Full ordered list of action objects (name, duration_secs) |
  349. | `profiles[].break_duration_secs` | number | Break between action loops |
  350. | `profiles[].auto_start` | boolean | Whether the profile auto-starts on window open |
  351. ```bash
  352. node cli.ts calibrations --json | jq '.profiles[0].actions'
  353. node cli.ts calibrations get 3 --json | jq '.profile'
  354. ```
  355. ---
  356. #### `dnd`
  357. The `dnd` summary prints a rich visual status (bars, scores, tips) but several
  358. raw fields are only visible via `--json`.
  359. | Hidden field | Type | Contents |
  360. |---|---|---|
  361. | `avg_score` | number | Current rolling average focus score (0–100) |
  362. | `sample_count` | number | How many focus score samples have been collected |
  363. | `window_size` | number | Target number of samples for the rolling window |
  364. | `mode_identifier` | string | DND automation mode identifier |
  365. | `dnd_active` | boolean | Whether this app activated DND |
  366. | `os_active` | boolean | Whether the OS reports DND as active |
  367. ```bash
  368. node cli.ts dnd --json | jq '{avg: .avg_score, threshold: .threshold, active: .dnd_active}'
  369. ```
  370. ---
  371. #### `notify`
  372. `notify` has almost no human-readable summary — only a one-line echo of the title and body.
  373. The entire JSON confirmation from the server is suppressed in default mode.
  374. | Hidden field | Type | Contents |
  375. |---|---|---|
  376. | `ok` | boolean | Confirmation that the OS notification was dispatched |
  377. | `command` | string | Echo of the command name (`"notify"`) |
  378. ```bash
  379. node cli.ts notify "done" --full
  380. # default output: ⚡ notify "done"
  381. # --full appends: { "command": "notify", "ok": true }
  382. node cli.ts notify "done" --json
  383. # → { "command": "notify", "ok": true }
  384. ```
  385. If `ok` is `false` the CLI exits with an error even in default mode, so `--full`
  386. or `--json` is only useful when you need the confirmation in a script:
  387. ```bash
  388. # Verify notification was delivered before continuing a script:
  389. node cli.ts notify "build finished" --json | jq -e '.ok' > /dev/null \
  390. && echo "notification sent" || echo "notification failed"
  391. ```
  392. ---
  393. #### `calibrate`
  394. `calibrate` has two hidden layers:
  395. **Layer 1 — the `list_calibrations` intermediate call.**
  396. When `--profile` is given, the CLI internally calls `list_calibrations` to resolve the
  397. profile name to a UUID. That response — which contains the **full list of all calibration
  398. profiles with their actions, durations, and settings** — is consumed internally and
  399. **never printed, not even with `--full`**. To inspect it, use `raw` or HTTP directly:
  400. ```bash
  401. # See all profiles and their full action sequences:
  402. node cli.ts raw '{"command":"list_calibrations"}' --json
  403. # or:
  404. curl -s -X POST http://127.0.0.1:8375/ \
  405. -H "Content-Type: application/json" \
  406. -d '{"command":"list_calibrations"}' | jq '.'
  407. ```
  408. The `list_calibrations` response shape:
  409. ```jsonc
  410. {
  411. "command": "list_calibrations",
  412. "ok": true,
  413. "profiles": [
  414. {
  415. "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  416. "name": "Eyes Open/Closed",
  417. "loop_count": 3,
  418. "break_duration_secs": 5,
  419. "auto_start": true,
  420. "actions": [
  421. { "name": "Eyes Open", "duration_secs": 20 },
  422. { "name": "Eyes Closed", "duration_secs": 20 }
  423. ]
  424. },
  425. // ... more profiles
  426. ]
  427. }
  428. ```
  429. **Layer 2 — the `run_calibration` confirmation.**
  430. The actual calibration trigger response is suppressed in default mode, just like `notify`.
  431. | Hidden field | Type | Contents |
  432. |---|---|---|
  433. | `ok` | boolean | Confirmation that the calibration window opened and started |
  434. | `command` | string | Echo of the command name (`"run_calibration"`) |
  435. ```bash
  436. node cli.ts calibrate --full
  437. # default output:
  438. # ⚡ calibrate
  439. # profile: Eyes Open/Closed (a1b2c3d4-…)
  440. # --full appends:
  441. # { "command": "run_calibration", "ok": true }
  442. node cli.ts calibrate --json
  443. # → { "command": "run_calibration", "ok": true }
  444. # Check all available profile names without starting calibration:
  445. node cli.ts raw '{"command":"list_calibrations"}' --json | jq '[.profiles[].name]'
  446. # Verify calibration started in a script:
  447. node cli.ts calibrate --profile "Eyes Open" --json | jq -e '.ok' > /dev/null \
  448. && echo "calibration started" || echo "failed — is a Muse connected?"
  449. ```
  450. ---
  451. #### `timer`
  452. Like `notify`, `timer` produces only a one-line header in default mode.
  453. The server confirmation is suppressed.
  454. | Hidden field | Type | Contents |
  455. |---|---|---|
  456. | `ok` | boolean | Confirmation that the focus-timer window opened and started |
  457. | `command` | string | Echo of the command name (`"timer"`) |
  458. ```bash
  459. node cli.ts timer --full
  460. # default output: ⚡ timer
  461. # --full appends: { "command": "timer", "ok": true }
  462. node cli.ts timer --json
  463. # → { "command": "timer", "ok": true }
  464. # Use in a script after a calibration block:
  465. node cli.ts calibrate --json | jq -e '.ok' > /dev/null \
  466. && node cli.ts timer --json | jq -e '.ok' > /dev/null \
  467. && echo "calibration + timer both started"
  468. ```
  469. ---
  470. #### `listen`
  471. | Hidden field | Type | Contents |
  472. |---|---|---|
  473. | events array | array | Full array of every raw broadcast event received. The summary only prints `event_type × count` (plus a dedicated 🪝 section for hook triggers); `--full` appends every packet. |
  474. | hook events | objects | Full `{ event: "hook", payload: { hook, scenario, distance, label_id, label_text, triggered_at_utc, command, text, context } }` for each Proactive Hook trigger — the summary shows hook name, distance, and matched label; `--json` gives the complete payload for scripting. |
  475. ```bash
  476. node cli.ts listen --seconds 10 --json | jq '[.[] | select(.event == "scores")]'
  477. node cli.ts listen --seconds 5 --json | jq '.[0]' # first event in full
  478. node cli.ts listen --seconds 60 --json | jq '[.[] | select(.event == "hook") | .payload]'
  479. ```
  480. ---
  481. ## Global Options
  482. | Flag | Description |
  483. |---|---|
  484. | `--port <n>` | Connect to an explicit port (skips mDNS) |
  485. | `--ws` | Force WebSocket; error if unreachable |
  486. | `--http` | Force HTTP REST; no live-event commands |
  487. | `--json` | Raw JSON only — no summary, no colors, pipe-safe |
  488. | `--full` | Human-readable summary **and** colorized full JSON appended below |
  489. | `--no-color` | Disable ANSI color output (also honoured via `NO_COLOR` env var or non-TTY stdout) |
  490. | `--version`, `-v` | Print CLI version and exit |
  491. | `--help`, `-h` | Show full help and exit |
  492. | `--poll <n>` | (`status` only) Re-poll every N seconds; keeps the socket open |
  493. | `--dot` | (`interactive` only) Graphviz DOT to stdout — pipe to `dot -Tsvg` |
  494. | `--trends` | (`sessions` only) Show first-half → second-half deltas |
  495. | `--mode <m>` | (`search-labels`) `text` \| `context` \| `both`; (`search-images`) `semantic` \| `substring` |
  496. | `--k <n>` | Number of nearest neighbors (`search`, `search-labels`, `search-images`, `eeg-for-screenshots`) |
  497. | `--by-image <path>` | (`search-images`) Search by visual similarity using CLIP embeddings instead of OCR text |
  498. | `--window <n>` | (`screenshots-for-eeg`, `eeg-for-screenshots`) Temporal window in seconds (default 30 / 60) |
  499. | `--k-text <n>` | (`interactive`) k for text-label HNSW search (default 5) |
  500. | `--k-eeg <n>` | (`interactive`) k for EEG-similarity HNSW search (default 5) |
  501. | `--k-labels <n>` | (`interactive`) k for label-proximity step (default 3) |
  502. | `--reach <n>` | (`interactive`) temporal window in minutes around each EEG point (default 10) |
  503. | `--ef <n>` | HNSW ef parameter (`search-labels`; default `max(k×4, 64)`) |
  504. | `--seconds <n>` | Duration for `listen` (default 5) |
  505. | `--profile <p>` | Profile name or UUID for `calibrate` |
  506. | `--context "..."` | (`label`) Long-form annotation body; used by `search-labels --mode context` |
  507. | `--at <utc>` | (`label`) Backdate to a specific unix second (default: now) |
  508. | `--voice <name>` | (`say`) Voice name to use (e.g. `Jasper`); omit for server default |
  509. | `--keywords <csv>` | (`hooks add`/`update`) Comma-separated keywords |
  510. | `--scenario <s>` | (`hooks add`/`update`) `any` \| `cognitive` \| `emotional` \| `physical` |
  511. | `--command <cmd>` | (`hooks add`/`update`) Command to run on trigger |
  512. | `--hook-text <txt>` | (`hooks add`/`update`) Payload text |
  513. | `--threshold <f>` | (`hooks add`/`update`) Distance threshold (0.01–1.0) |
  514. | `--recent <n>` | (`hooks add`/`update`) Recent-refs limit (10–20) |
  515. | `--limit <n>` | (`hooks log`) Page size (default: 20) |
  516. | `--offset <n>` | (`hooks log`) Row offset (default: 0) |
  517. | `--actions "L1:20,L2:20"` | (`calibrations create`/`update`) Actions as `label:secs` pairs |
  518. | `--loops <n>` | (`calibrations create`/`update`) Loop count (default: 3) |
  519. | `--break <n>` | (`calibrations create`/`update`) Break duration in seconds (default: 5) |
  520. | `--auto-start` | (`calibrations create`/`update`) Auto-start when opened |
  521. | `--name "…"` | (`calibrations update`) Rename the profile |
  522. | `--system "..."` | (`llm chat`) Prepend a system prompt |
  523. | `--temperature <f>` | (`llm chat`) Sampling temperature 0–2 (default 0.8) |
  524. | `--max-tokens <n>` | (`llm chat`) Maximum tokens to generate per turn (default 2048) |
  525. | `--image <path>` | (`llm chat`) Attach image file (can repeat: `--image a.jpg --image b.png`) |
  526. | `--mmproj <file>` | (`llm add`) Also download a vision projector from the same repo |
  527. | `--bedtime <HH:MM>` | (`sleep-schedule set`) Bedtime in 24-h format (e.g. `23:00`) |
  528. | `--wake <HH:MM>` | (`sleep-schedule set`) Wake-up time in 24-h format (e.g. `07:00`) |
  529. | `--preset <id>` | (`sleep-schedule set`) Apply a named preset: `default`, `early_bird`, `night_owl`, `short_sleeper`, `long_sleeper` |
  530. | `--metric-type <t>` | (`health metrics`) Metric type to query: `restingHeartRate`, `hrv`, `vo2Max`, `bodyMass`, etc. |
  531. ---
  532. ## Polling with `status`
  533. `status` is the single fastest call to get a complete system snapshot.
  534. Poll it periodically from any script or external tool to react to EEG state changes.
  535. The `--poll <n>` flag keeps the WebSocket connection open and re-polls every N seconds
  536. with a live timestamp header — no need for a shell loop:
  537. ```bash
  538. # Built-in polling (single connection, live updates):
  539. node cli.ts status --poll 5 # refresh every 5 s
  540. node cli.ts status --poll 10 --json # JSON snapshot every 10 s (Ctrl+C to stop)
  541. # One-shot snapshot:
  542. node cli.ts status --json
  543. # Manual shell loop (opens a new connection each time):
  544. while true; do
  545. node cli.ts status --json | jq '.scores.relaxation'
  546. sleep 5
  547. done
  548. # Alert when focus drops below 0.4:
  549. while true; do
  550. RELAX=$(node cli.ts status --json | jq '.scores.relaxation')
  551. if (( $(echo "$FOCUS < 0.4" | bc -l) )); then
  552. node cli.ts notify "Relaxation dropped" "Current: $FOCUS"
  553. fi
  554. sleep 10
  555. done
  556. ```
  557. ### What `status` returns
  558. ```jsonc
  559. {
  560. "command": "status",
  561. "ok": true,
  562. "device": {
  563. "state": "connected", // "connected" | "connecting" | "disconnected"
  564. "name": "Muse-A1B2", // or "MW75-Neuro-XXXX", "Hermes-XXXX", "Ganglion-XXXX"
  565. "battery": 73, // percent
  566. "firmware": "1.3.4",
  567. "eeg_samples": 195840, // cumulative samples this run
  568. "ppg_samples": 30600, // Muse only (PPG sensor)
  569. "imu_samples": 122400,
  570. "eeg_channels": 4 // 4 (Muse/Ganglion), 8 (Hermes), or 12 (MW75)
  571. },
  572. "session": {
  573. "start_utc": 1740412800, // Unix seconds (UTC)
  574. "duration_secs": 1847,
  575. "n_epochs": 369 // 5-second embedding epochs computed so far
  576. },
  577. "signal_quality": {
  578. // Keys vary by device — Muse: tp9/af7/af8/tp10; Hermes: fp1/fp2/af3/af4/f3/f4/fc1/fc2
  579. // MW75: ft7/t7/tp7/cp5/p7/c5/ft8/t8/tp8/cp6/p8/c6
  580. "tp9": 0.95, // 0–1; ≥0.9 = good, ≥0.7 = acceptable
  581. "af7": 0.88,
  582. "af8": 0.91,
  583. "tp10": 0.97
  584. },
  585. "scores": {
  586. // Core scores (0–1 unless noted):
  587. "relaxation": 0.38,
  588. "relaxation": 0.40,
  589. "engagement": 0.60,
  590. "meditation": 0.52,
  591. "mood": 0.55,
  592. "cognitive_load": 0.33,
  593. "drowsiness": 0.10,
  594. "hr": 68.2, // bpm (from PPG)
  595. "snr": 14.3, // signal-to-noise ratio in dB
  596. "stillness": 0.88, // 0–1; 1 = perfectly still
  597. // Band powers (relative, sum ≈ 1):
  598. "bands": {
  599. "rel_delta": 0.28,
  600. "rel_theta": 0.18,
  601. "rel_alpha": 0.32,
  602. "rel_beta": 0.17,
  603. "rel_gamma": 0.05
  604. },
  605. // EEG ratios & spectral indices:
  606. "faa": 0.042, // Frontal Alpha Asymmetry (positive = approach)
  607. "tar": 0.56, // Theta/Alpha Ratio
  608. "bar": 0.53, // Beta/Alpha Ratio
  609. "tbr": 1.06, // Theta/Beta Ratio
  610. "apf": 10.1, // Alpha Peak Frequency (Hz)
  611. "coherence": 0.614,
  612. "mu_suppression": 0.031
  613. },
  614. "embeddings": {
  615. "today": 342,
  616. "total": 14820,
  617. "recording_days": 31
  618. },
  619. "labels": {
  620. "total": 58,
  621. "embedded": 42,
  622. "recent": [
  623. { "id": 42, "text": "meditation start", "created_at": 1740413100 }
  624. ],
  625. "top_all_time": [
  626. { "text": "deep focus", "count": 12 },
  627. { "text": "meditation", "count": 8 }
  628. ],
  629. "top_24h": [ { "text": "deep focus", "count": 3 } ],
  630. "top_7d": [ { "text": "deep focus", "count": 7 } ]
  631. },
  632. "apps": {
  633. "top_all_time": [
  634. { "app_name": "VS Code", "switches": 342, "last_seen": 1740413000 },
  635. { "app_name": "Firefox", "switches": 198, "last_seen": 1740412900 }
  636. ],
  637. "top_24h": [ { "app_name": "VS Code", "switches": 28, "last_seen": 1740413000 } ],
  638. "top_7d": [ { "app_name": "VS Code", "switches": 142, "last_seen": 1740413000 } ]
  639. },
  640. "screenshots": {
  641. "total": 1842,
  642. "with_embedding": 1840,
  643. "with_ocr": 1780,
  644. "with_ocr_embedding": 1756,
  645. "top_apps_all_time": [
  646. { "app_name": "VS Code", "count": 620 },
  647. { "app_name": "Firefox", "count": 310 }
  648. ],
  649. "top_apps_24h": [ { "app_name": "VS Code", "count": 48 } ]
  650. },
  651. "sleep": {
  652. // Last 48 h sleep staging summary:
  653. "total_epochs": 1054,
  654. "wake_epochs": 134,
  655. "n1_epochs": 89,
  656. "n2_epochs": 421,
  657. "n3_epochs": 298,
  658. "rem_epochs": 112,
  659. "epoch_secs": 5
  660. },
  661. "hooks": {
  662. "total": 3, // total configured hooks
  663. "enabled": 2, // how many are enabled
  664. "latest_trigger": { // most recent trigger across all hooks (null if never)
  665. "hook": "Deep Work Guard", // hook name that fired
  666. "triggered_at_utc": 1740413100,
  667. "distance": 0.0892, // cosine distance to matched reference
  668. "label_id": 7,
  669. "label_text": "focused reading session"
  670. }
  671. },
  672. "history": {
  673. "total_sessions": 63,
  674. "recording_days": 31,
  675. "current_streak_days": 7,
  676. "total_recording_hours": 94.2,
  677. "longest_session_min": 187,
  678. "avg_session_min": 89
  679. }
  680. }
  681. ```
  682. ---
  683. ## Commands
  684. ### `status`
  685. Full snapshot: device state, session, signal quality, scores, bands, embeddings, labels
  686. (with most-frequent texts), hooks (with latest trigger), sleep summary, recording history,
  687. app usage analytics, and screenshot/OCR statistics.
  688. Use `--poll <n>` to re-poll every N seconds over the same open connection
  689. (keeps the socket open; press Ctrl+C to stop).
  690. ```bash
  691. node cli.ts status
  692. node cli.ts status --json
  693. node cli.ts status --json | jq '.scores.relaxation'
  694. node cli.ts status --json | jq '.scores.bands'
  695. node cli.ts status --json | jq '.device.battery'
  696. node cli.ts status --json | jq '.signal_quality'
  697. node cli.ts status --json | jq '.sleep'
  698. node cli.ts status --json | jq '.history.current_streak_days'
  699. node cli.ts status --json | jq '.hooks' # hook summary + latest trigger
  700. node cli.ts status --json | jq '.hooks.latest_trigger' # most recent hook trigger
  701. node cli.ts status --json | jq '.hooks.latest_trigger.hook' # which hook fired last
  702. node cli.ts status --json | jq '.apps.top_24h' # most-used apps in last 24h
  703. node cli.ts status --json | jq '.apps.top_all_time[:5]' # top 5 apps all-time
  704. node cli.ts status --json | jq '.labels.top_all_time' # most frequent label texts
  705. node cli.ts status --json | jq '.screenshots' # screenshot/OCR counts
  706. node cli.ts status --json | jq '.screenshots.top_apps_24h' # top screenshot apps (24h)
  707. node cli.ts status --poll 5 # refresh every 5 seconds
  708. node cli.ts status --poll 10 --json # JSON snapshot every 10 seconds
  709. ```
  710. **HTTP:**
  711. ```bash
  712. curl -s -X POST http://127.0.0.1:8375/ \
  713. -H "Content-Type: application/json" \
  714. -d '{"command":"status"}'
  715. ```
  716. ---
  717. ### `session`
  718. Full metric breakdown for a single recording session, with first-half → second-half trend arrows.
  719. Index `0` = most recent, `1` = previous, and so on.
  720. ```bash
  721. node cli.ts session # most recent session (default: 0)
  722. node cli.ts session 0 # same
  723. node cli.ts session 1 # previous session
  724. node cli.ts session 2 # two sessions ago
  725. node cli.ts session --json
  726. node cli.ts session 1 --json | jq '.metrics.relaxation'
  727. node cli.ts session 0 --json | jq '{relaxation: .metrics.relaxation, hr: .metrics.hr, trend: .trends.relaxation}'
  728. ```
  729. **HTTP (two requests):**
  730. ```bash
  731. # Step 1 — get session list to find timestamps:
  732. curl -s -X POST http://127.0.0.1:8375/ \
  733. -H "Content-Type: application/json" \
  734. -d '{"command":"sessions"}' | jq '.sessions[0]'
  735. # Step 2 — fetch full metrics for that session:
  736. curl -s -X POST http://127.0.0.1:8375/ \
  737. -H "Content-Type: application/json" \
  738. -d '{"command":"session_metrics","start_utc":1740412800,"end_utc":1740415510}'
  739. ```
  740. **Example output:**
  741. ```
  742. ⚡ session [0]
  743. 20260224 2/24/2026, 8:00:00 AM → 8:45:10 AM 45m 10s 541 epochs
  744. Core Scores
  745. focus 0.70 ↑ (0.64 → 0.76)
  746. relaxation 0.40 ↓ (0.44 → 0.36)
  747. engagement 0.60 → (0.60 → 0.61)
  748. meditation 0.52 ↑ (0.47 → 0.57)
  749. mood 0.55 → (0.54 → 0.56)
  750. cognitive load 0.33 ↓ (0.38 → 0.28)
  751. drowsiness 0.10 → (0.11 → 0.09)
  752. PPG / Heart
  753. heart rate (bpm) 68.2 ↓ (70.1 → 66.3)
  754. rmssd (ms) 42.1 ↑ (38.4 → 45.8)
  755. ...
  756. EEG Bands
  757. δ delta 28% ↓ (31% → 25%)
  758. θ theta 18% ↓ (21% → 15%)
  759. α alpha 32% ↑ (28% → 36%)
  760. β beta 17% → (17% → 17%)
  761. γ gamma 5% → (5% → 5%)
  762. ```
  763. **JSON response structure:**
  764. ```jsonc
  765. {
  766. "ok": true,
  767. "metrics": {
  768. "relaxation": 0.38,
  769. "relaxation": 0.40,
  770. "n_epochs": 541,
  771. // ... all metrics (see Data Reference)
  772. },
  773. "first": {
  774. "relaxation": 0.38, // first-half average
  775. // ...
  776. },
  777. "second": {
  778. "relaxation": 0.41, // second-half average
  779. // ...
  780. },
  781. "trends": {
  782. "relaxation": "up", // "up" | "down" | "flat"
  783. "relaxation": "down",
  784. // ...
  785. }
  786. }
  787. ```
  788. ---
  789. ### `sessions`
  790. List every recorded session across all days. Sessions are contiguous embedding ranges
  791. (gap threshold: 120 seconds between epochs).
  792. ```bash
  793. node cli.ts sessions
  794. node cli.ts sessions --json
  795. node cli.ts sessions --json | jq '.sessions | length'
  796. node cli.ts sessions --json | jq '.sessions[0]'
  797. node cli.ts sessions --json | jq '[.sessions[] | {day, dur: (.end_utc - .start_utc)}]'
  798. node cli.ts sessions --trends # show per-session metric trends
  799. ```
  800. **HTTP:**
  801. ```bash
  802. curl -s -X POST http://127.0.0.1:8375/ \
  803. -H "Content-Type: application/json" \
  804. -d '{"command":"sessions"}'
  805. ```
  806. **Example output:**
  807. ```
  808. ⚡ sessions
  809. 3 session(s)
  810. 20260223 2/23/2026, 9:15:00 AM → 10:02:33 AM 47m 33s 570 epochs
  811. 20260223 2/23/2026, 2:30:00 PM → 3:12:45 PM 42m 45s 513 epochs
  812. 20260224 2/24/2026, 8:00:00 AM → 8:45:10 AM 45m 10s 541 epochs
  813. ```
  814. **JSON response:**
  815. ```jsonc
  816. {
  817. "command": "sessions",
  818. "ok": true,
  819. "sessions": [
  820. {
  821. "day": "20260224",
  822. "start_utc": 1740412800, // Unix seconds
  823. "end_utc": 1740415510,
  824. "n_epochs": 541 // 5-second embedding windows
  825. },
  826. {
  827. "day": "20260223",
  828. "start_utc": 1740380100,
  829. "end_utc": 1740382665,
  830. "n_epochs": 513
  831. }
  832. // ...newest first
  833. ]
  834. }
  835. ```
  836. > **Getting Unix timestamps for other commands:**
  837. > ```bash
  838. > # Get start/end of the most recent session:
  839. > node cli.ts sessions --json | jq '{start: .sessions[0].start_utc, end: .sessions[0].end_utc}'
  840. > ```
  841. ---
  842. ### `say`
  843. Speak text aloud via the on-device KittenTTS engine (fire-and-forget).
  844. The server enqueues the utterance on a dedicated TTS thread and returns immediately —
  845. the response arrives before audio playback begins.
  846. Requires `espeak-ng` on PATH. First run downloads a ~30 MB TTS model from HuggingFace Hub.
  847. ```bash
  848. node cli.ts say "Eyes open. Starting calibration."
  849. node cli.ts say "Break time. Next: Eyes Closed." --voice Jasper
  850. node cli.ts say "Calibration complete." --http
  851. node cli.ts say "Hello!" --json
  852. ```
  853. **HTTP:**
  854. ```bash
  855. curl -s -X POST http://127.0.0.1:8375/ \
  856. -H "Content-Type: application/json" \
  857. -d '{"command":"say","text":"Eyes open. Starting calibration."}'
  858. # With a specific voice:
  859. curl -s -X POST http://127.0.0.1:8375/ \
  860. -H "Content-Type: application/json" \
  861. -d '{"command":"say","text":"Break time.","voice":"Jasper"}'
  862. ```
  863. **Response:**
  864. ```jsonc
  865. { "command": "say", "ok": true, "spoken": "Eyes open. Starting calibration." }
  866. // With --voice Jasper:
  867. { "command": "say", "ok": true, "spoken": "Break time.", "voice": "Jasper" }
  868. ```
  869. > **Note:** `--voice` is optional; omitting it uses the voice last selected in Settings → Voice.
  870. ---
  871. ### `label`
  872. Create a timestamped text annotation on the current EEG moment.
  873. Labels are stored in the database, shown in the dashboard, and searchable via `search-labels`.
  874. Optional flags:
  875. - `--context "..."` — long-form body stored alongside the short text; used by
  876. `search-labels --mode context` and `--mode both`.
  877. - `--at <utc>` — backdate the label to a specific unix second instead of using
  878. the current time (useful for retrospective annotation).
  879. ```bash
  880. node cli.ts label "meditation start"
  881. node cli.ts label "eyes closed"
  882. node cli.ts label "feeling anxious"
  883. node cli.ts label "coffee just finished"
  884. node cli.ts label "task switch: coding → email"
  885. node cli.ts label "phone notification distracted me"
  886. node cli.ts label --json "focus block start" # just print the label_id
  887. node cli.ts label "breathwork" --context "box breathing 4-4-4-4, 10 min"
  888. node cli.ts label "retrospective note" --at 1740412800
  889. ```
  890. **HTTP:**
  891. ```bash
  892. curl -s -X POST http://127.0.0.1:8375/ \
  893. -H "Content-Type: application/json" \
  894. -d '{"command":"label","text":"meditation start"}'
  895. # With long-form context:
  896. curl -s -X POST http://127.0.0.1:8375/ \
  897. -H "Content-Type: application/json" \
  898. -d '{"command":"label","text":"eyes closed","context":"4-7-8 breathing exercise"}'
  899. # Backdated to a specific timestamp:
  900. curl -s -X POST http://127.0.0.1:8375/ \
  901. -H "Content-Type: application/json" \
  902. -d '{"command":"label","text":"retrospective note","label_start_utc":1740412800}'
  903. # Save the label_id for later reference:
  904. LABEL_ID=$(curl -s -X POST http://127.0.0.1:8375/ \
  905. -H "Content-Type: application/json" \
  906. -d '{"command":"label","text":"focus block start"}' | jq '.label_id')
  907. echo "Created label #$LABEL_ID"
  908. ```
  909. **Response:**
  910. ```jsonc
  911. { "command": "label", "ok": true, "label_id": 42 }
  912. ```
  913. ---
  914. ### `hooks`
  915. List configured Proactive Hooks with scenario + last-trigger metadata.
  916. Supports the following subcommands:
  917. | Subcommand | Description |
  918. |---|---|
  919. | `hooks` (or `hooks status`) | List hooks with scenario + last-trigger metadata |
  920. | `hooks list` | List raw hook rules (name, keywords, threshold, enabled, …) |
  921. | `hooks add <name> [opts]` | Add a new hook rule |
  922. | `hooks remove <name>` | Delete a hook by name |
  923. | `hooks enable <name>` | Enable a hook |
  924. | `hooks disable <name>` | Disable a hook |
  925. | `hooks update <name> [opts]` | Update fields on an existing hook |
  926. | `hooks suggest "kw1,kw2"` | Suggest threshold from matching labels + recent EEG embeddings |
  927. | `hooks log [--limit N --offset M]` | View paginated hook trigger audit log rows |
  928. **Hook mutation flags** (for `hooks add` and `hooks update`):
  929. | Flag | Description |
  930. |---|---|
  931. | `--keywords <csv>` | Comma-separated keywords (e.g. `"focus,deep work,flow"`) |
  932. | `--scenario <s>` | `any` \| `cognitive` \| `emotional` \| `physical` |
  933. | `--command <cmd>` | Command to run on trigger |
  934. | `--hook-text <txt>` | Payload text |
  935. | `--threshold <f>` | Distance threshold (0.01–1.0) |
  936. | `--recent <n>` | Recent-refs limit (10–20) |
  937. ```bash
  938. # Status (default) — hooks with scenario + last trigger
  939. node cli.ts hooks
  940. node cli.ts hooks --json
  941. node cli.ts hooks --json | jq '.hooks[] | {name: .hook.name, scenario: .hook.scenario, last: .last_trigger.triggered_at_utc}'
  942. # List raw hook rules
  943. node cli.ts hooks list
  944. node cli.ts hooks list --json
  945. # Add a new hook
  946. node cli.ts hooks add "Deep Work Guard" --keywords "focus,deep work,flow" --scenario cognitive --threshold 0.14
  947. node cli.ts hooks add "Stress Alert" --keywords "stress,anxious,overwhelmed" --scenario emotional --threshold 0.12
  948. # Update an existing hook
  949. node cli.ts hooks update "Deep Work Guard" --keywords "focus,flow" --threshold 0.12
  950. # Enable / disable
  951. node cli.ts hooks enable "Deep Work Guard"
  952. node cli.ts hooks disable "Deep Work Guard"
  953. # Remove
  954. node cli.ts hooks remove "Deep Work Guard"
  955. # Suggest threshold from real EEG/label data
  956. node cli.ts hooks suggest "focus,deep work"
  957. node cli.ts hooks suggest "focus" --json | jq '.suggestion.suggested'
  958. # Scenario-focused quick examples:
  959. # cognitive: deep work overload guard
  960. node cli.ts hooks suggest "focus,deep work"
  961. # emotional: stress-recovery style labels
  962. node cli.ts hooks suggest "stress,anxious,overwhelmed"
  963. # physical: fatigue/body-state style labels
  964. node cli.ts hooks suggest "fatigue,tired,slump"
  965. # View hook trigger audit log
  966. node cli.ts hooks log --limit 20 --offset 0
  967. node cli.ts hooks log --json | jq '.rows[] | {ts: .triggered_at_utc, hook: (.hook_json|fromjson).name, scenario: (.hook_json|fromjson).scenario}'
  968. ```
  969. **HTTP:**
  970. ```bash
  971. # Status
  972. curl -s -X POST http://127.0.0.1:8375/ \
  973. -H "Content-Type: application/json" \
  974. -d '{"command":"hooks_status"}'
  975. # List raw rules
  976. curl -s -X POST http://127.0.0.1:8375/ \
  977. -H "Content-Type: application/json" \
  978. -d '{"command":"hooks_get"}'
  979. # Set hooks (add/remove/update — sends the full array)
  980. curl -s -X POST http://127.0.0.1:8375/ \
  981. -H "Content-Type: application/json" \
  982. -d '{"command":"hooks_set","hooks":[...]}'
  983. # Suggest threshold
  984. curl -s -X POST http://127.0.0.1:8375/ \
  985. -H "Content-Type: application/json" \
  986. -d '{"command":"hooks_suggest","keywords":["focus","deep work"]}'
  987. # Audit log
  988. curl -s -X POST http://127.0.0.1:8375/ \
  989. -H "Content-Type: application/json" \
  990. -d '{"command":"hooks_log","limit":20,"offset":0}'
  991. ```
  992. #### How Proactive Hooks Work (Broadcast → `listen`)
  993. Proactive Hooks are a **real-time pattern matching system** that runs inside the
  994. EEG embedding pipeline. Every 5 seconds, when a new EEG embedding epoch is
  995. computed, the server checks all enabled hooks against the live brain state:
  996. ```
  997. EEG stream → 5 s epoch → embedding vector → cosine distance to hook references
  998. ↓
  999. distance ≤ threshold?
  1000. ↓
  1001. scenario gate passes?
  1002. ↓
  1003. broadcast { event: "hook", payload: {...} }
  1004. + audit log in hooks.duckdb
  1005. + OS toast notification
  1006. ```
  1007. **Step by step:**
  1008. 1. **Labels as reference patterns** — When you create labels (`node cli.ts label "deep focus"`),
  1009. the server embeds both the text and the surrounding EEG window. Each hook's
  1010. `keywords` are matched against label texts to build a set of reference EEG
  1011. embeddings (up to `recent_limit` most recent matches).
  1012. 2. **Live comparison** — Every new 5-second EEG epoch is compared (cosine distance)
  1013. against every enabled hook's reference embeddings. If the closest match is
  1014. within the hook's `distance_threshold`, the hook fires.
  1015. 3. **Scenario gating** — Before firing, the hook checks the current epoch's metrics
  1016. against the scenario filter:
  1017. - `any` — always passes
  1018. - `cognitive` — requires elevated theta/beta ratio or cognitive load ≥ 55
  1019. - `emotional` — requires stress index ≥ 55, mood ≤ 45, or relaxation ≤ 35
  1020. - `physical` — requires drowsiness ≥ 55, migraine index ≥ 45, or extreme HR
  1021. 4. **Cooldown** — A hook cannot fire more than once every 10 seconds (prevents
  1022. rapid-fire spam when the brain state is sustained).
  1023. 5. **Broadcast** — When a hook fires, the server pushes a `{ "event": "hook" }` message
  1024. over WebSocket to **all connected clients**. This is the same broadcast mechanism
  1025. used for EEG, scores, and label events — any WebSocket listener receives it.
  1026. 6. **Audit log** — Every trigger is persisted to `hooks.duckdb` for later review
  1027. via `hooks log`.
  1028. **Why this matters for the CLI:**
  1029. Because hook triggers are broadcast events, `listen` captures them automatically.
  1030. This lets you build automation pipelines that react to your brain state in real time:
  1031. ```bash
  1032. # ── React to hook triggers in a shell script ──────────────────────────────────
  1033. # Listen for 5 minutes and act on any hook triggers:
  1034. node cli.ts listen --seconds 300 --json | jq -c '.[] | select(.event == "hook") | .payload' | while read -r payload; do
  1035. HOOK=$(echo "$payload" | jq -r '.hook')
  1036. DIST=$(echo "$payload" | jq -r '.distance')
  1037. LABEL=$(echo "$payload" | jq -r '.label_text')
  1038. echo "Hook triggered: $HOOK (dist=$DIST, label=$LABEL)"
  1039. # Run custom actions based on hook name:
  1040. case "$HOOK" in
  1041. "Deep Work Guard")
  1042. node cli.ts notify "Deep Focus Detected" "Distance: $DIST to '$LABEL'"
  1043. ;;
  1044. "Stress Alert")
  1045. osascript -e 'display notification "Take a break" with title "Stress Detected"'
  1046. ;;
  1047. esac
  1048. done
  1049. # ── Python real-time hook listener ────────────────────────────────────────────
  1050. python3 - <<'EOF'
  1051. import asyncio, json
  1052. import websockets
  1053. async def listen_for_hooks(port: int):
  1054. async with websockets.connect(f"ws://127.0.0.1:{port}") as ws:
  1055. print("Listening for hook triggers…")
  1056. async for raw in ws:
  1057. msg = json.loads(raw)
  1058. if msg.get("event") == "hook":
  1059. p = msg["payload"]
  1060. print(f"🪝 {p['hook']} fired! distance={p['distance']:.4f} label=\"{p['label_text']}\"")
  1061. # Do something: send Slack message, log to CSV, trigger HomeKit, etc.
  1062. asyncio.run(listen_for_hooks(8375))
  1063. EOF
  1064. # ── End-to-end workflow: create labels, add hook, listen for triggers ─────────
  1065. # 1. Record some EEG while in a specific state and label it:
  1066. node cli.ts label "deep focus coding"
  1067. node cli.ts label "deep concentration"
  1068. # 2. Create a hook that fires when your brain returns to that state:
  1069. node cli.ts hooks add "Focus Mode" \
  1070. --keywords "focus,concentration,deep" \
  1071. --scenario cognitive \
  1072. --threshold 0.15
  1073. # 3. Verify the threshold makes sense:
  1074. node cli.ts hooks suggest "focus,concentration,deep"
  1075. # 4. Listen and watch for triggers:
  1076. node cli.ts listen --seconds 300
  1077. # 5. Check the audit log after the session:
  1078. node cli.ts hooks log --limit 10
  1079. ```
  1080. **Hook trigger event shape (WebSocket):**
  1081. ```jsonc
  1082. {
  1083. "event": "hook",
  1084. "payload": {
  1085. "hook": "Deep Work Guard", // hook rule name
  1086. "scenario": "cognitive", // scenario filter
  1087. "context": "labels", // match source
  1088. "distance": 0.0892, // cosine distance to closest reference
  1089. "label_id": 7, // which label's EEG pattern matched
  1090. "label_text": "focused reading session",
  1091. "triggered_at_utc": 1740412830, // unix seconds
  1092. "command": "notify", // configured action
  1093. "text": "You're in deep focus!" // configured payload
  1094. }
  1095. }
  1096. ```
  1097. > **Note:** Hook broadcast events are only available over WebSocket. HTTP transport
  1098. > (`--http`) has no push streaming, so you cannot receive hook triggers via HTTP.
  1099. > Use `listen` (which requires WebSocket) or connect directly via `ws://`.
  1100. ---
  1101. ### `search-labels`
  1102. Semantic (vector) search across all your EEG annotations.
  1103. The query is embedded and compared against the label HNSW index.
  1104. ```bash
  1105. node cli.ts search-labels "deep focus"
  1106. node cli.ts search-labels "relaxed meditation" --k 10
  1107. node cli.ts search-labels "anxiety" --mode context
  1108. node cli.ts search-labels "flow state" --mode both --k 5
  1109. node cli.ts search-labels "creative work" --json | jq '.results[].text'
  1110. node cli.ts search-labels "morning routine" --json | jq '.results[] | {text, sim: .similarity}'
  1111. ```
  1112. **Modes:**
  1113. - `text` (default) — searches the label short-text HNSW index
  1114. - `context` — searches the long-context HNSW (requires context fields to be set)
  1115. - `both` — runs both indexes, deduplicates by best cosine distance
  1116. **HTTP:**
  1117. ```bash
  1118. curl -s -X POST http://127.0.0.1:8375/ \
  1119. -H "Content-Type: application/json" \
  1120. -d '{"command":"search_labels","query":"deep focus","k":10,"mode":"text"}'
  1121. ```
  1122. **Example output:**
  1123. ```
  1124. ⚡ search-labels "deep focus" (mode: text, k: 10)
  1125. model: Xenova/bge-small-en-v1.5
  1126. k: 10 results: 3
  1127. #7 "focused reading session"
  1128. similarity: 88% distance: 0.1204 model: bge-small-en-v1.5
  1129. recorded: 2/24/2026, 8:05:00 AM (300s window)
  1130. eeg: focus=0.74 relaxation=0.38 engagement=0.62 hr=66.10 mood=0.58
  1131. #12 "deep work block"
  1132. similarity: 84% distance: 0.1601
  1133. recorded: 2/23/2026, 9:20:00 AM (300s window)
  1134. eeg: focus=0.71 relaxation=0.42 engagement=0.65 hr=68.30 mood=0.55
  1135. ```
  1136. **JSON response:**
  1137. ```jsonc
  1138. {
  1139. "command": "search_labels",
  1140. "ok": true,
  1141. "query": "deep focus",
  1142. "mode": "text",
  1143. "model": "Xenova/bge-small-en-v1.5",
  1144. "k": 10,
  1145. "count": 3,
  1146. "results": [
  1147. {
  1148. "label_id": 7,
  1149. "text": "focused reading session",
  1150. "context": "",
  1151. "distance": 0.1204,
  1152. "similarity": 0.8796, // 1 − distance
  1153. "eeg_start": 1740412800,
  1154. "eeg_end": 1740413100,
  1155. "created_at": 1740412810,
  1156. "embedding_model": "bge-small-en-v1.5",
  1157. "eeg_metrics": {
  1158. "relaxation": 0.38,
  1159. "relaxation": 0.38,
  1160. "engagement": 0.62,
  1161. "hr": 66.1,
  1162. "mood": 0.58,
  1163. "rel_alpha": 0.35,
  1164. "rel_beta": 0.19
  1165. }
  1166. }
  1167. ]
  1168. }
  1169. ```
  1170. ---
  1171. ### `interactive`
  1172. Cross-modal 5-layer graph search. Combines semantic text search, EEG similarity search,
  1173. temporal label proximity, and screenshot discovery into a single directed graph:
  1174. ```
  1175. "deep focus" → text_label nodes (semantically similar annotations)
  1176. ↓
  1177. eeg_point nodes (raw EEG moments from label time windows)
  1178. ↓
  1179. found_label nodes (labels near those EEG moments in time)
  1180. ↓
  1181. screenshot nodes (screenshots near EEG timestamps, ranked by
  1182. window-title / OCR-text proximity to query)
  1183. ```
  1184. Four output formats — choose exactly one:
  1185. | Flag | Output |
  1186. |---|---|
  1187. | _(none)_ | Colored human-readable summary of all four layers |
  1188. | `--full` | Summary **+** colorized JSON appended below |
  1189. | `--json` | Raw JSON: `{ query, nodes, edges, dot }` — pipe-safe |
  1190. | `--dot` | Graphviz DOT source only — pipe directly to `dot -Tsvg` or `dot -Tpng` |
  1191. ```bash
  1192. # Default summary:
  1193. node cli.ts interactive "deep focus"
  1194. # Tune the pipeline:
  1195. node cli.ts interactive "meditation" --k-text 8 --k-eeg 8 --k-labels 5 --reach 15
  1196. # Raw JSON — count nodes:
  1197. node cli.ts interactive "flow state" --json | jq '.nodes | length'
  1198. # Extract text_label texts:
  1199. node cli.ts interactive "focus" --json | jq '[.nodes[] | select(.kind == "text_label") | .text]'
  1200. # Extract EEG moment timestamps:
  1201. node cli.ts interactive "anxiety" --json | jq '[.nodes[] | select(.kind == "eeg_point") | .timestamp_unix]'
  1202. # Extract discovered nearby labels:
  1203. node cli.ts interactive "stress" --json | jq '[.nodes[] | select(.kind == "found_label") | .text]'
  1204. # Extract discovered screenshots:
  1205. node cli.ts interactive "coding" --json | jq '[.nodes[] | select(.kind == "screenshot") | {file: .filename, app: .app_name, ocr_sim: .ocr_similarity}]'
  1206. # Render graph as SVG (requires graphviz):
  1207. node cli.ts interactive "deep focus" --dot | dot -Tsvg > graph.svg
  1208. # Render graph as PNG:
  1209. node cli.ts interactive "meditation" --dot | dot -Tpng > graph.png
  1210. # Pull DOT from JSON output instead:
  1211. node cli.ts interactive "focus" --json | jq -r '.dot' | dot -Tsvg > graph.svg
  1212. # Full inspection (summary + full JSON):
  1213. node cli.ts interactive "anxiety" --full
  1214. ```
  1215. **Pipeline parameters:**
  1216. | Flag | Default | Range | Description |
  1217. |---|---|---|---|
  1218. | `--k-text <n>` | 5 | 1–20 | k for text-label HNSW search |
  1219. | `--k-eeg <n>` | 5 | 1–20 | k for EEG-similarity HNSW per text label |
  1220. | `--k-labels <n>` | 3 | 1–10 | k for label-proximity per EEG point |
  1221. | `--reach <n>` | 10 | 1–60 | Temporal window (minutes) around each EEG point |
  1222. All parameters are server-clamped to their stated range. Out-of-range values are silently adjusted.
  1223. **HTTP:**
  1224. ```bash
  1225. curl -s -X POST http://127.0.0.1:8375/ \
  1226. -H "Content-Type: application/json" \
  1227. -d '{
  1228. "command": "interactive_search",
  1229. "query": "deep focus",
  1230. "k_text": 5,
  1231. "k_eeg": 5,
  1232. "k_labels": 3,
  1233. "reach_minutes": 10
  1234. }'
  1235. ```
  1236. **Example default output:**
  1237. ```
  1238. ⚡ interactive "deep focus" (k-text:5, k-eeg:5, k-labels:3, reach:10m)
  1239. Graph 7 nodes · 9 edges
  1240. edges: text_sim ×2 eeg_bridge ×3 label_prox ×4
  1241. ──────────────────────────────────────────────────────
  1242. ● query "deep focus"
  1243. ◆ Text Labels (2 semantically similar labels)
  1244. #0 "focused reading session" 2/24/2026, 8:00:00 AM PST
  1245. similarity: 88% dist: 0.1204
  1246. focus 0.74 relaxation 0.38 engagement 0.62 hr 66.10 meditation 0.44
  1247. #1 "concentration phase" 2/23/2026, 2:30:00 PM PST
  1248. similarity: 82% dist: 0.1805
  1249. ◈ EEG Moments (3 neural moments found)
  1250. #0 2/24/2026, 8:12:45 AM PST dist: 0.0231 ← tl_0
  1251. #1 2/22/2026, 10:14:00 AM PST dist: 0.0319 ← tl_0
  1252. #2 2/21/2026, 3:02:00 PM PST dist: 0.0487 ← tl_1
  1253. ◉ Nearby Labels (2 labels found near EEG moments)
  1254. #0 "eyes closed" 2/24/2026, 8:13:00 AM PST 0.8m from EEG point
  1255. #1 "task complete" 2/22/2026, 10:18:00 AM PST 4.0m from EEG point
  1256. tip: rerun with --dot | dot -Tsvg > graph.svg to visualize
  1257. ```
  1258. **JSON response structure:**
  1259. ```jsonc
  1260. {
  1261. "command": "interactive_search",
  1262. "ok": true,
  1263. "query": "deep focus",
  1264. "k_text": 5,
  1265. "k_eeg": 5,
  1266. "k_labels": 3,
  1267. "reach_minutes": 10,
  1268. "nodes": [
  1269. {
  1270. "id": "query",
  1271. "kind": "query",
  1272. "text": "deep focus",
  1273. "timestamp_unix": null,
  1274. "distance": 0.0,
  1275. "eeg_metrics": null,
  1276. "parent_id": null
  1277. },
  1278. {
  1279. "id": "tl_0",
  1280. "kind": "text_label",
  1281. "text": "focused reading session",
  1282. "timestamp_unix": 1740412800,
  1283. "distance": 0.1204, // cosine distance from query
  1284. "eeg_metrics": {
  1285. "relaxation": 0.38, "engagement": 0.62,
  1286. "hr": 66.1, "meditation": 0.44, "rel_alpha": 0.35
  1287. },
  1288. "parent_id": "query"
  1289. },
  1290. {
  1291. "id": "ep_1740413565",
  1292. "kind": "eeg_point",
  1293. "text": null,
  1294. "timestamp_unix": 1740413565,
  1295. "distance": 0.0231, // cosine distance in EEG embedding space
  1296. "eeg_metrics": null,
  1297. "parent_id": "tl_0"
  1298. },
  1299. {
  1300. "id": "fl_42",
  1301. "kind": "found_label",
  1302. "text": "eyes closed",
  1303. "timestamp_unix": 1740413580,
  1304. "distance": 0.133, // fraction of reach window (0 = right at the EEG point)
  1305. "eeg_metrics": null,
  1306. "parent_id": "ep_1740413565"
  1307. },
  1308. {
  1309. "id": "ss_20260224080530",
  1310. "kind": "screenshot",
  1311. "text": null,
  1312. "timestamp_unix": 1740413130,
  1313. "distance": 0.05,
  1314. "eeg_metrics": null,
  1315. "parent_id": "ep_1740413565",
  1316. "filename": "20260224/20260224080530.webp",
  1317. "app_name": "VS Code",
  1318. "window_title": "main.rs",
  1319. "ocr_text": "fn dispatch(app: &AppHandle, command: &str…",
  1320. "ocr_similarity": 0.42,
  1321. "proj_x": 0.31,
  1322. "proj_y": -0.18,
  1323. "proj_z": 0.72
  1324. }
  1325. // ... more nodes
  1326. ],
  1327. "edges": [
  1328. { "from_id": "query", "to_id": "tl_0", "distance": 0.1204, "kind": "text_sim" },
  1329. { "from_id": "tl_0", "to_id": "ep_1740413565", "distance": 0.0231, "kind": "eeg_bridge" },
  1330. { "from_id": "ep_1740413565","to_id": "fl_42", "distance": 0.133, "kind": "label_prox" },
  1331. { "from_id": "ep_1740413565","to_id": "ss_20260224080530","distance": 2.0, "kind": "screenshot_prox" },
  1332. { "from_id": "ep_1740413565","to_id": "ss_20260224080530","distance": 0.42, "kind": "ocr_sim" }
  1333. // ...
  1334. ],
  1335. "dot": "digraph interactive_search {\n graph [rankdir=TB, ...];\n \"query\" [...];\n ...",
  1336. "svg": "<svg ...>...</svg>",
  1337. "svg_col": "<svg ...>...</svg>",
  1338. "svg_3d": "<svg ...>...</svg>"
  1339. }
  1340. ```
  1341. **Node kinds:**
  1342. | Kind | Layer | Color | Description |
  1343. |---|---|---|---|
  1344. | `query` | 0 | violet | The embedded search keyword (always exactly 1) |
  1345. | `text_label` | 1 | blue | Annotations semantically similar to the query |
  1346. | `eeg_point` | 2 | amber | Raw EEG moments from label time windows |
  1347. | `found_label` | 3 | emerald | Annotations discovered near EEG moments in time |
  1348. | `screenshot` | 4 | pink | Screenshots near EEG timestamps, ranked by window-title / OCR proximity |
  1349. **Edge kinds:**
  1350. | Kind | Connects | What the distance means |
  1351. |---|---|---|
  1352. | `text_sim` | query → text_label | Cosine distance in text embedding space |
  1353. | `eeg_bridge` | text_label → eeg_point | Cosine distance in EEG embedding space |
  1354. | `eeg_sim` | eeg_point → eeg_point | Cosine distance (shared EEG point, cross-edge) |
  1355. | `label_prox` | eeg_point → found_label | Temporal proximity (fraction of reach window) |
  1356. | `screenshot_prox` | eeg_point → screenshot | Temporal proximity (seconds between EEG epoch and screenshot capture) |
  1357. | `ocr_sim` | eeg_point → screenshot | Cosine similarity between query text and screenshot OCR text |
  1358. **Screenshot node fields** (only present on `screenshot` kind nodes):
  1359. | Field | Type | Description |
  1360. |---|---|---|
  1361. | `filename` | string | Relative path to the screenshot image file |
  1362. | `app_name` | string | Application name at capture time |
  1363. | `window_title` | string | Window title at capture time |
  1364. | `ocr_text` | string | OCR-extracted text from the screenshot |
  1365. | `ocr_similarity` | number | Cosine similarity (0–1) between query text and OCR text |
  1366. **3-D projection fields** (present on all nodes when text embeddings are available):
  1367. | Field | Type | Description |
  1368. |---|---|---|
  1369. | `proj_x` | number | PCA axis 1, normalised to [-1, 1] |
  1370. | `proj_y` | number | PCA axis 2, normalised to [-1, 1] |
  1371. | `proj_z` | number | PCA axis 3, normalised to [-1, 1] |
  1372. > **Empty results:** If no labels have been embedded yet, only the query node is returned
  1373. > (`nodes.length === 1`, `edges.length === 0`). Annotate moments with `label` first, then
  1374. > run `search-labels` to verify the embedding index, then re-run `interactive`.
  1375. ---
  1376. ### `search`
  1377. Find EEG moments from your entire history that are neurally similar to a query range.
  1378. Uses approximate nearest-neighbor (ANN) search over the 5-second embedding HNSW index.
  1379. Auto-range: when no `--start`/`--end` flags are given, the CLI automatically uses your
  1380. most recent session and prints a `rerun:` line you can copy-paste.
  1381. ```bash
  1382. node cli.ts search # auto: last session, k=5
  1383. node cli.ts search --k 10 # 10 nearest neighbors
  1384. node cli.ts search --start 1740412800 --end 1740415500
  1385. node cli.ts search --start 1740412800 --end 1740415500 --k 20
  1386. node cli.ts search --json | jq '.result.results | length'
  1387. node cli.ts search --json | jq '.result.results[0].neighbors[0]'
  1388. ```
  1389. **HTTP:**
  1390. ```bash
  1391. curl -s -X POST http://127.0.0.1:8375/ \
  1392. -H "Content-Type: application/json" \
  1393. -d '{"command":"search","start_utc":1740412800,"end_utc":1740415500,"k":5}'
  1394. ```
  1395. **Example output:**
  1396. ```
  1397. ⚡ search
  1398. range: 1740412800–1740415500 (auto: 2/24/2026 8:00 AM → 8:45 AM, 45m 0s)
  1399. k: 5
  1400. rerun: node cli.ts search --start 1740412800 --end 1740415500 --k 5
  1401. Search Results
  1402. query epochs: 541 searched days: 31 total matches: 2705 span: 744.3h
  1403. Match Quality (cosine distance — lower = more similar)
  1404. ████████████████████░░░░ similarity 82%
  1405. min 0.0231 mean 0.1842 max 0.3901 σ 0.0612
  1406. Neighbor Metrics (avg · min–max across 2705 matches)
  1407. focus 0.67 0.34 – 0.91
  1408. relaxation 0.43 0.19 – 0.74
  1409. hr (bpm) 67.4 52.0 – 88.3
  1410. α alpha 0.33 0.18 – 0.51
  1411. θ/α ratio 0.54 0.28 – 0.89
  1412. Top Matches (closest by cosine distance)
  1413. #1 2/22/2026, 10:14:00 AM dist 0.0231 focus 0.73 relax 0.41 hr 66.2
  1414. #2 2/21/2026, 3:02:00 PM dist 0.0319 focus 0.69 relax 0.44 hr 67.8
  1415. ...
  1416. Temporal Distribution (matches by hour of day, UTC)
  1417. 08:00 ████████████░░░░░░░░ 142 20:00 ███░░░░░░░░░░░░░░░░░ 38
  1418. 09:00 ████████████████░░░░ 198 21:00 █░░░░░░░░░░░░░░░░░░░ 12
  1419. ...
  1420. ```
  1421. **JSON response:**
  1422. ```jsonc
  1423. {
  1424. "command": "search",
  1425. "ok": true,
  1426. "result": {
  1427. "query_count": 541,
  1428. "searched_days": ["20260224", "20260223", ...],
  1429. "analysis": {
  1430. "distance_stats": { "min": 0.0231, "mean": 0.1842, "max": 0.3901, "stddev": 0.0612 },
  1431. "time_span_hours": 744.3,
  1432. "neighbor_metrics": { "relaxation": 0.38, "relaxation": 0.43, "hr": 67.4, ... },
  1433. "temporal_distribution": { "8": 142, "9": 198, ... },
  1434. "top_days": [["20260222", 312], ["20260221", 289], ...]
  1435. },
  1436. "results": [
  1437. {
  1438. "timestamp_unix": 1740412800,
  1439. "neighbors": [
  1440. {
  1441. "distance": 0.0231, // cosine distance — lower = more similar
  1442. "timestamp_unix": 1740320040,
  1443. "date": "20260222",
  1444. "device_name": "Muse-A1B2",
  1445. "labels": [{ "text": "morning focus block" }],
  1446. "metrics": {
  1447. "relaxation": 0.38,
  1448. "relaxation": 0.41,
  1449. "hr": 66.2,
  1450. "rel_alpha": 0.34
  1451. }
  1452. }
  1453. ]
  1454. }
  1455. ]
  1456. }
  1457. }
  1458. ```
  1459. ---
  1460. ### `compare`
  1461. Side-by-side A/B comparison of two sessions.
  1462. Returns averaged metrics for both ranges, delta values, and trend direction for every metric.
  1463. Also enqueues a 3D UMAP projection (use `umap` to get the spatial points).
  1464. Auto-range: uses your last two sessions as A (older) and B (newer).
  1465. ```bash
  1466. node cli.ts compare # auto: last 2 sessions
  1467. node cli.ts compare --a-start 1740380100 --a-end 1740382665 \
  1468. --b-start 1740412800 --b-end 1740415510
  1469. node cli.ts compare --json
  1470. node cli.ts compare --json | jq '{a_relax: .a.relaxation, b_relax: .b.relaxation}'
  1471. node cli.ts compare --json | jq '.insights.deltas.relaxation'
  1472. node cli.ts compare --json | jq '.insights.improved'
  1473. node cli.ts compare --json | jq '.insights.declined'
  1474. ```
  1475. **HTTP:**
  1476. ```bash
  1477. curl -s -X POST http://127.0.0.1:8375/ \
  1478. -H "Content-Type: application/json" \
  1479. -d '{
  1480. "command": "compare",
  1481. "a_start_utc": 1740380100, "a_end_utc": 1740382665,
  1482. "b_start_utc": 1740412800, "b_end_utc": 1740415510
  1483. }' | jq '{a_relax: .a.relaxation, b_relax: .b.relaxation}'
  1484. ```
  1485. **Example output:**
  1486. ```
  1487. ⚡ compare
  1488. A: 1740380100–1740382665 (auto: 2/23/2026 2:30 PM → 3:12 PM, 42m 45s)
  1489. B: 1740412800–1740415510 (auto: 2/24/2026 8:00 AM → 8:45 AM, 45m 10s)
  1490. rerun: node cli.ts compare --a-start 1740380100 --a-end 1740382665 ...
  1491. Compare Insights (513 vs 541 epochs)
  1492. metric A B Δ Δ% dir
  1493. ────────────────────────────────────────────────────────
  1494. focus 0.62 0.71 +0.09 +14.5% ↑
  1495. relaxation 0.45 0.38 -0.07 -15.6% ↓
  1496. engagement 0.58 0.60 +0.02 +3.4% →
  1497. hr 72.1 68.4 -3.70 -5.1% ↓
  1498. meditation 0.44 0.52 +0.08 +18.2% ↑
  1499. drowsiness 0.18 0.10 -0.08 -44.4% ↓
  1500. ▲ improved: focus, meditation, engagement
  1501. ▼ declined: relaxation, hr
  1502. ```
  1503. **JSON response:**
  1504. ```jsonc
  1505. {
  1506. "ok": true,
  1507. "a": { "relaxation": 0.45, "engagement": 0.62, "hr": 72.1, "n_epochs": 513, ... },
  1508. "b": { "relaxation": 0.38, "engagement": 0.71, "hr": 68.4, "n_epochs": 541, ... },
  1509. "sleep_a": { "total_epochs": 0, ... },
  1510. "sleep_b": { "total_epochs": 0, ... },
  1511. "insights": {
  1512. "n_epochs_a": 513,
  1513. "n_epochs_b": 541,
  1514. "deltas": {
  1515. "relaxation": { "a": 0.45, "b": 0.38, "abs": 0.07, "pct": -15.6, "direction": "down" },
  1516. "relaxation": { "a": 0.45, "b": 0.38, "abs": -0.07, "pct": -15.6, "direction": "down" },
  1517. ...
  1518. },
  1519. "improved": ["focus", "meditation", "engagement"],
  1520. "declined": ["relaxation", "hr"]
  1521. },
  1522. "umap": {
  1523. "queued": true,
  1524. "job_id": 5,
  1525. "estimated_secs": 14,
  1526. "n_a": 513,
  1527. "n_b": 541
  1528. }
  1529. }
  1530. ```
  1531. ---
  1532. ### `sleep`
  1533. Classify EEG epochs into sleep stages (Wake / N1 / N2 / N3 / REM) using
  1534. relative band-power ratios and simplified AASM heuristics.
  1535. Auto-range: all sessions from the last 24 hours.
  1536. By index: `sleep 0` = most recent session, `sleep 1` = previous, etc.
  1537. ```bash
  1538. node cli.ts sleep # auto: last 24h of sessions
  1539. node cli.ts sleep 0 # most recent session's sleep data
  1540. node cli.ts sleep 1 # previous session
  1541. node cli.ts sleep --start 1740380100 --end 1740415510
  1542. node cli.ts sleep --json | jq '.summary'
  1543. node cli.ts sleep --json | jq '.analysis'
  1544. node cli.ts sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
  1545. ```
  1546. **HTTP:**
  1547. ```bash
  1548. curl -s -X POST http://127.0.0.1:8375/ \
  1549. -H "Content-Type: application/json" \
  1550. -d '{"command":"sleep","start_utc":1740380100,"end_utc":1740415510}' | jq '.summary'
  1551. ```
  1552. **Example output:**
  1553. ```
  1554. ⚡ sleep
  1555. range: 1740380100–1740415510 (auto: 2/23/2026 2:30 PM → 2/24/2026 8:45 AM, 9h 50m)
  1556. rerun: node cli.ts sleep --start 1740380100 --end 1740415510
  1557. Sleep Summary
  1558. total: 1054 epochs (87 min)
  1559. Wake 134 (12.7%)
  1560. N1 89 (8.4%)
  1561. N2 421 (39.9%)
  1562. N3 298 (28.3%)
  1563. REM 112 (10.6%)
  1564. Sleep Analysis
  1565. efficiency: 85.2%
  1566. onset latency: 12.5 min
  1567. REM latency: 62.0 min
  1568. transitions: 38 awakenings: 11
  1569. Stage durations: Wake 11m N1 7m N2 35m N3 25m REM 9m
  1570. Bout analysis:
  1571. WAKE 11 bouts avg 1.0m max 3.5m
  1572. N2 14 bouts avg 2.5m max 8.0m
  1573. N3 6 bouts avg 4.2m max 9.0m
  1574. REM 4 bouts avg 2.3m max 4.5m
  1575. ```
  1576. **JSON response:**
  1577. ```jsonc
  1578. {
  1579. "command": "sleep",
  1580. "ok": true,
  1581. "summary": {
  1582. "total_epochs": 1054,
  1583. "wake_epochs": 134,
  1584. "n1_epochs": 89,
  1585. "n2_epochs": 421,
  1586. "n3_epochs": 298,
  1587. "rem_epochs": 112,
  1588. "epoch_secs": 5
  1589. },
  1590. "analysis": {
  1591. "efficiency_pct": 85.2,
  1592. "onset_latency_min": 12.5,
  1593. "rem_latency_min": 62.0,
  1594. "transitions": 38,
  1595. "awakenings": 11,
  1596. "stage_minutes": { "wake": 11, "n1": 7, "n2": 35, "n3": 25, "rem": 9 },
  1597. "bouts": {
  1598. "WAKE": { "count": 11, "mean_min": 1.0, "max_min": 3.5 },
  1599. "N3": { "count": 6, "mean_min": 4.2, "max_min": 9.0 },
  1600. "REM": { "count": 4, "mean_min": 2.3, "max_min": 4.5 }
  1601. }
  1602. },
  1603. "epochs": [
  1604. { "utc": 1740380100, "stage": 0, "rel_delta": 0.18, "rel_theta": 0.21, "rel_alpha": 0.38, "rel_beta": 0.17 },
  1605. { "utc": 1740380105, "stage": 2, "rel_delta": 0.41, "rel_theta": 0.28, "rel_alpha": 0.19, "rel_beta": 0.09 },
  1606. ...
  1607. ]
  1608. }
  1609. ```
  1610. > **Stage codes:** `0` = Wake, `1` = N1, `2` = N2, `3` = N3, `4` = REM.
  1611. ---
  1612. ### `sleep-schedule`
  1613. View or update the sleep schedule used for session classification and sleep staging analysis.
  1614. The schedule defines your expected bedtime and wake-up time, and can be set to one of five
  1615. built-in presets or a fully custom window.
  1616. ```bash
  1617. # Show current schedule:
  1618. node cli.ts sleep-schedule
  1619. node cli.ts sleep-schedule --json
  1620. # Update with explicit times:
  1621. node cli.ts sleep-schedule set --bedtime 23:00 --wake 07:00
  1622. node cli.ts sleep-schedule set --bedtime 01:00 --wake 09:00
  1623. # Apply a named preset:
  1624. node cli.ts sleep-schedule set --preset early_bird
  1625. node cli.ts sleep-schedule set --preset night_owl
  1626. # Combine preset with override:
  1627. node cli.ts sleep-schedule set --preset short_sleeper
  1628. node cli.ts sleep-schedule set --bedtime 00:30 --wake 06:30 --preset custom
  1629. ```
  1630. **Available presets:**
  1631. | Preset | Bedtime | Wake | Duration |
  1632. |---|---|---|---|
  1633. | `default` | 23:00 | 07:00 | 8 h |
  1634. | `early_bird` | 21:30 | 05:30 | 8 h |
  1635. | `night_owl` | 01:00 | 09:00 | 8 h |
  1636. | `short_sleeper` | 00:00 | 06:00 | 6 h |
  1637. | `long_sleeper` | 22:00 | 08:00 | 10 h |
  1638. When you set `--bedtime` or `--wake` without `--preset`, the preset is automatically
  1639. set to `custom`.
  1640. **HTTP:**
  1641. ```bash
  1642. # Get current schedule:
  1643. curl -s -X POST http://127.0.0.1:8375/ \
  1644. -H "Content-Type: application/json" \
  1645. -d '{"command":"sleep_schedule"}'
  1646. # Update schedule:
  1647. curl -s -X POST http://127.0.0.1:8375/ \
  1648. -H "Content-Type: application/json" \
  1649. -d '{"command":"sleep_schedule_set","bedtime":"23:00","wake_time":"07:00","preset":"default"}'
  1650. # Apply a preset (only the fields you send are updated):
  1651. curl -s -X POST http://127.0.0.1:8375/ \
  1652. -H "Content-Type: application/json" \
  1653. -d '{"command":"sleep_schedule_set","preset":"early_bird","bedtime":"21:30","wake_time":"05:30"}'
  1654. ```
  1655. **Example output (default):**
  1656. ```
  1657. ⚡ sleep-schedule current schedule
  1658. Sleep Schedule
  1659. bedtime 23:00
  1660. wake 07:00
  1661. duration 8h (480 min)
  1662. preset default
  1663. Available presets:
  1664. ● default 23:00 — 07:00 (8h)
  1665. ○ early_bird 21:30 — 05:30 (8h)
  1666. ○ night_owl 01:00 — 09:00 (8h)
  1667. ○ short_sleeper 00:00 — 06:00 (6h)

Lines 2,001–4,351 are not shown. The link to the file on GitHub has every line.

README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # NeuroSkill™
  2. [www.neuroskill.com](https://neuroskill.com)
  3. [![Release](https://img.shields.io/github/v/release/NeuroSkill-com/skill?style=for-the-badge&logo=github&logoColor=white&label=Latest)](https://github.com/NeuroSkill-com/skill/releases/latest)
  4. [![License](https://img.shields.io/badge/License-GPL--3.0-blue?style=for-the-badge)](https://github.com/NeuroSkill-com/skill/blob/main/LICENSE)
  5. [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/Rcvb8Cx4cZ)
  6. > ⚠️ **Research use only — not a medical device.**
  7. > NeuroSkill is an open-source EXG/BCI research tool. It is not FDA/CE approved and must not be used for diagnosis or treatment.
  8. NeuroSkill is a local-first desktop neurofeedback + BCI app built with **Tauri v2 (Rust)** and **SvelteKit**.
  9. <p align="center">
  10. <img src="./docs/dashboard.png" alt="NeuroSkill Dashboard" width="49%" />
  11. <img src="./docs/devices.png" alt="NeuroSkill Supported Devices" width="49%" />
  12. </p>
  13. ## Quick links
  14. - **Downloads:** [latest release](https://github.com/NeuroSkill-com/skill/releases/latest): macOS `.dmg` (Apple Silicon), Windows `-setup.exe`, Linux `.deb`, `.rpm` or portable `.tar.gz`
  15. - **Install (Homebrew):** `brew install --cask https://raw.githubusercontent.com/NeuroSkill-com/skill/main/Casks/neuroskill.rb`
  16. - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
  17. - **Security:** [SECURITY.md](SECURITY.md): how to report a vulnerability, and how remote devices are paired
  18. - **Changelog:** [CHANGELOG.md](CHANGELOG.md)
  19. ## What it does
  20. - Real-time EXG streaming and visualization
  21. - GPU band-power analysis + neural embeddings
  22. - Session comparison, sleep staging, and UMAP visualization
  23. - Labeling, similarity search, and screenshot-based search
  24. - Local LLM + TTS integration
  25. - LSL + remote rlsl-iroh streaming
  26. - Remote access from a phone over iroh, paired with single-use codes ([SECURITY.md](SECURITY.md))
  27. - WebSocket/HTTP API
  28. Models run on the GPU where there is one: Metal on macOS, CUDA or DirectX 12 on
  29. Windows, CUDA or Vulkan on Linux. Without a usable GPU they run on the CPU.
  30. ## Supported devices
  31. <!-- AUTO-GENERATED:SUPPORTED_DEVICES:START -->
  32. <!-- Run: npm run sync:readme:supported -->
  33. - **ANT Neuro:** eego 8, eego 24, eego 64, eego mylab, eego sport, eego rt, eego hub
  34. - **AttentivU:** AttentivU Glasses *(iOS bridge only)*
  35. - **AWEAR:** AWEAR EEG
  36. - **BrainBit LLC:** BrainBit, BrainBit 2, BrainBit Flex 4/8
  37. - **BrainMaster Technologies:** Atlantis 4×4 (4-ch), Discovery (24-ch), Freedom (24-ch wireless)
  38. - **Cognionics / CGX:** Quick-20r, Quick-32r, Quick-8r, AIM-2
  39. - **EmotiBit:** EmotiBit sensor board (WiFi / BLE)
  40. - **Emotiv:** EPOC X, FLEX Saline, Insight, MN8
  41. - **g.tec medical engineering:** Unicorn Hybrid Black
  42. - **IDUN:** Guardian
  43. - **InteraXon:** Muse 2016, Muse 2, Muse S, Muse S Athena
  44. - **Mendi:** Mendi Headband
  45. - **Neurofield Inc:** Q21 (20-ch)
  46. - **Neurosity:** Crown / Notion
  47. - **NeuroSky:** MindWave / MindWave Mobile
  48. - **Neurable:** MW75 Neuro
  49. - **OpenBCI:** Cyton, Cyton Daisy, Galea, Ganglion
  50. - **Ōura:** Oura Ring (Gen 3 / Gen 4)
  51. - **Brain Products:** BrainVision RDA
  52. - **RE-AK:** Nucleus-Hermès
  53. - **Vital Neuro:** Vital Neuro Headphones
  54. - **WHOOP:** WHOOP 4.0 / 5.0 / MG strap
  55. Plus any compatible **LSL** source (e.g. BrainFlow, MATLAB, pylsl).
  56. <!-- AUTO-GENERATED:SUPPORTED_DEVICES:END -->
  57. ## Supported EXG/BCI foundation models
  58. Canonical source: `src-tauri/exg_catalog.json`
  59. <!-- AUTO-GENERATED:SUPPORTED_MODELS:START -->
  60. <!-- Run: npm run sync:readme:supported -->
  61. - **ZUNA** (`Zyphra/ZUNA`)
  62. - **LUNA Base** (`PulpBio/LUNA`)
  63. - **LUNA Large** (`PulpBio/LUNA`)
  64. - **LUNA Huge** (`PulpBio/LUNA`)
  65. - **REVE Base** (`brain-bzh/reve-base`)
  66. - **REVE Large** (`brain-bzh/reve-large`)
  67. - **Brain-JEPA** (`eugenehp/BrainJEPA`)
  68. - **OpenTSLM** (`StanfordBDHG/OpenTSLM`)
  69. - **SensorLM** (`google/sensorlm`)
  70. - **SleepFM** (`zou-group/sleepfm-clinical`)
  71. - **SleepLM** (`yang-ai-lab/SleepLM`)
  72. - **OSF Base** (`yang-ai-lab/OSF-Base`)
  73. - **SignalJEPA** (`braindecode/SignalJEPA-PreLocal-pretrained`)
  74. - **LaBraM** (`braindecode/labram-pretrained`)
  75. - **EEGPT** (`braindecode/eegpt-pretrained`)
  76. - **TRIBE v2** (`eugenehp/tribev2`)
  77. - **EEG-DINO Small** (`eugenehp/eegdino`)
  78. - **EEG-DINO Medium** (`eugenehp/eegdino`)
  79. - **EEG-DINO Large** (`eugenehp/eegdino`)
  80. - **LuMamba (Reconstruction)** (`PulpBio/LuMamba`)
  81. - **LuMamba (LeJEPA+Recon 128)** (`PulpBio/LuMamba`)
  82. - **LuMamba (LeJEPA+Recon 300)** (`PulpBio/LuMamba`)
  83. - **LuMamba (LeJEPA only)** (`PulpBio/LuMamba`)
  84. - **NeuroRVQ** (`eugenehp/NeuroRVQ`)
  85. - **CBraMod** (`braindecode/cbramod-pretrained`)
  86. - **ST-EEGFormer Small** (`eugenehp/ST-EEGFormer`)
  87. - **ST-EEGFormer Base** (`eugenehp/ST-EEGFormer`)
  88. - **ST-EEGFormer Large** (`eugenehp/ST-EEGFormer`)
  89. <!-- AUTO-GENERATED:SUPPORTED_MODELS:END -->
  90. ## Documentation
  91. Long-form documentation lives in `./docs`:
  92. - Docs index: [docs/README.md](docs/README.md)
  93. - Architecture overview: [docs/architecture.md](docs/architecture.md)
  94. - AI/ML model inventory (LLM, EXG, vision, OCR): [docs/AI.md](docs/AI.md)
  95. - Device support and integration notes: [docs/DEVICES.md](docs/DEVICES.md)
  96. - UI notes: [docs/UI.md](docs/UI.md)
  97. - Metrics reference and formulas: [docs/METRICS.md](docs/METRICS.md)
  98. - Hooks: [docs/HOOKS.md](docs/HOOKS.md)
  99. - LLM internals: [docs/LLM.md](docs/LLM.md)
  100. - LSL integration notes: [docs/lsl-integration.md](docs/lsl-integration.md)
  101. - API reference (WebSocket + HTTP): [docs/API.md](docs/API.md)
  102. - Development guide: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
  103. - Linux build/packaging: [docs/LINUX.md](docs/LINUX.md)
  104. - Raspberry Pi (4/5, 64-bit): [docs/RASPBERRY_PI.md](docs/RASPBERRY_PI.md)
  105. - Windows build setup: [docs/WINDOWS.md](docs/WINDOWS.md)
  106. ## Development (quickstart)
  107. Product version lives in the repo-root [`VERSION`](VERSION) file (`npm run bump`
  108. keeps `package.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml` in
  109. sync). Release builds enable one daemon OS umbrella (`apple` / `linux` /
  110. `windows`). PR CI runs clippy/tests; signed product builds run on release tags
  111. or Preview Build. Details: [CONTRIBUTING.md](CONTRIBUTING.md) ·
  112. [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
  113. `npm run setup` checks that Rust is installed, offers to install Node.js 22 into
  114. `~/.local` if it is missing or older than 22.17, offers to install CMake, protoc
  115. and the other native build tools (Homebrew on macOS, the system package manager
  116. on Linux), and installs the JavaScript dependencies with
  117. `npm ci`, the same way CI does. On Windows, follow
  118. [docs/WINDOWS.md](docs/WINDOWS.md) instead.
  119. Install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) (`curl -LsSf https://hf.co/cli/install.sh | bash` on macOS/Linux, `powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"` on Windows), then:
  120. ```bash
  121. npm run setup -- --yes
  122. hf download Zyphra/ZUNA
  123. npm run tauri dev
  124. ```
  125. Build production app:
  126. ```bash
  127. npm run tauri:build
  128. ```
  129. ## License
  130. GPL-3.0-only. See [LICENSE](LICENSE).
scripts/ci.mjs · Bundled script · 960 lines · 1 finding marked
  1. #!/usr/bin/env node
  2. // SPDX-License-Identifier: GPL-3.0-only
  3. //
  4. // Shared CI helpers — single cross-platform entry point (Node.js).
  5. //
  6. // Usage:
  7. // node scripts/ci.mjs <command> [args...]
  8. //
  9. // Commands:
  10. // resolve-version Resolve version from VERSION, validate tag + derived files
  11. // verify-secrets V1 V2 ... Check env vars are non-empty
  12. // prepare-changelog VER OUT [RANGE] Generate release notes markdown
  13. // publish-llm-catalog [--tag T --upload] [--mirror-to-rc-latest] Validate + publish src-tauri/llm_catalog.json
  14. // update-latest-json ... Merge platform entry into Tauri updater manifest
  15. // discord-notify ... Send Discord webhook notification
  16. // import-apple-cert Import .p12 into temporary keychain (macOS)
  17. // setup-widget-signing Prepare WidgetKit automatic signing (macOS CI)
  18. // build-widgets Build SkillWidgets.appex with CI signing (macOS)
  19. // validate-notarization Check Apple notarization credentials (macOS)
  20. // validate-apple-signing-identity Assert APPLE_SIGNING_IDENTITY is a Developer ID Application cert
  21. // free-disk-space Remove unused toolchains on Linux runners
  22. // install-protoc-windows Install protoc via choco or direct download (Windows)
  23. // compile-product Shared daemon+tty+app cargo recipe (release CI)
  24. // self-test Validate all commands + workflow references
  25. // dry-run-release Local release dry-run
  26. import { execSync, spawnSync } from "child_process";
  27. import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, rmSync, statSync } from "fs";
  28. import { basename, join, dirname } from "path";
  29. import { tmpdir } from "os";
  30. import { createHash } from "crypto";
  31. import {
  32. compileProduct,
  33. daemonOsFeature,
  34. parseCompileProductArgs,
  35. printCompileProductHelp,
  36. } from "./lib/compile-product.mjs";
  37. // ── Globals ──────────────────────────────────────────────────────────────────
  38. let CMD = "ci";
  39. const T0 = performance.now();
  40. // ── Helpers ──────────────────────────────────────────────────────────────────
  41. function log(msg) {
  42. console.log(`[${CMD}] ${msg}`);
  43. }
  44. function ghOutput(key, value) {
  45. const p = process.env.GITHUB_OUTPUT;
  46. if (p) writeFileSync(p, `${key}=${value}\n`, { flag: "a" });
  47. log(`output ${key}=${value}`);
  48. }
  49. function ghEnv(key, value) {
  50. const p = process.env.GITHUB_ENV;
  51. if (p) writeFileSync(p, `${key}=${value}\n`, { flag: "a" });
  52. log(`env ${key}=${value}`);
  53. }
  54. function ghPath(dir) {
  55. const p = process.env.GITHUB_PATH;
  56. if (p) writeFileSync(p, `${dir}\n`, { flag: "a" });
  57. log(`path +=${dir}`);
  58. }
  59. function error(msg) {
  60. console.log(`::error::[${CMD}] ${msg}`);
  61. }
  62. function warning(msg) {
  63. console.log(`::warning::[${CMD}] ${msg}`);
  64. }
  65. /** Product version from repo-root VERSION (source of truth). */
  66. function confVersion() {
  67. const raw = readFileSync("VERSION", "utf8").trim();
  68. const version = raw.split(/\r?\n/)[0]?.trim() ?? "";
  69. if (!version) throw new Error("VERSION file is empty");
  70. if (!/^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version)) {
  71. throw new Error(`Invalid VERSION "${version}" (expected x.y.z or x.y.z-rc.N)`);
  72. }
  73. // Derived consumers must stay in sync with VERSION (bump.js writes all of them).
  74. const pkg = JSON.parse(readFileSync("package.json", "utf8"));
  75. if (pkg.version !== version) {
  76. throw new Error(`package.json version (${pkg.version}) does not match VERSION (${version})`);
  77. }
  78. const tauriText = readFileSync("src-tauri/tauri.conf.json", "utf8");
  79. const tauriMatch = tauriText.match(/"version"\s*:\s*"([^"]+)"/);
  80. if (!tauriMatch) throw new Error("Could not find version in src-tauri/tauri.conf.json");
  81. if (tauriMatch[1] !== version) {
  82. throw new Error(
  83. `src-tauri/tauri.conf.json version (${tauriMatch[1]}) does not match VERSION (${version})`,
  84. );
  85. }
  86. const cargoText = readFileSync("src-tauri/Cargo.toml", "utf8");
  87. const cargoMatch = cargoText.match(/^version\s*=\s*"([^"]+)"/m);
  88. if (!cargoMatch) throw new Error("Could not find package version in src-tauri/Cargo.toml");
  89. if (cargoMatch[1] !== version) {
  90. throw new Error(
  91. `src-tauri/Cargo.toml version (${cargoMatch[1]}) does not match VERSION (${version})`,
  92. );
  93. }
  94. for (const path of ["crates/skill-daemon/Cargo.toml", "crates/skill-tty/Cargo.toml"]) {
  95. const text = readFileSync(path, "utf8");
  96. const m = text.match(/^version\s*=\s*"([^"]+)"/m);
  97. if (!m) throw new Error(`Could not find package version in ${path}`);
  98. if (m[1] !== version) {
  99. throw new Error(`${path} version (${m[1]}) does not match VERSION (${version})`);
  100. }
  101. }
  102. return version;
  103. }
  104. function run(cmd, opts = {}) {
  105. const isArray = Array.isArray(cmd);
  106. const label = isArray ? cmd.join(" ") : cmd;
  107. log(`$ ${label}`);
  108. const args = isArray ? cmd : [cmd];
  109. const result = spawnSync(args[0], args.slice(1), {
  110. stdio: opts.capture ? "pipe" : "inherit",
  111. shell: !isArray, // shell only for string commands, not arrays
  112. encoding: "utf8",
  113. cwd: opts.cwd,
  114. env: { ...process.env, ...opts.env },
  115. });
  116. if (opts.check && result.status !== 0) {
  117. const err = new Error(`Command failed (exit ${result.status}): ${label}`);
  118. err.status = result.status;
  119. err.stdout = result.stdout;
  120. err.stderr = result.stderr;
  121. throw err;
  122. }
  123. return result;
  124. }
  125. function parseArgs(argv, spec) {
  126. // Minimal arg parser: spec = { "--flag": "key", "--opt": "key" }
  127. const result = { _: [] };
  128. let i = 0;
  129. while (i < argv.length) {
  130. const arg = argv[i];
  131. if (spec[arg] !== undefined) {
  132. if (spec[arg] === true) {
  133. result[arg.replace(/^--/, "")] = true;
  134. i++;
  135. } else {
  136. result[spec[arg]] = argv[i + 1];
  137. i += 2;
  138. }
  139. } else if (arg.startsWith("--")) {
  140. // Boolean flag
  141. result[arg.replace(/^--/, "")] = true;
  142. i++;
  143. } else {
  144. result._.push(arg);
  145. i++;
  146. }
  147. }
  148. return result;
  149. }
  150. // ── Commands ─────────────────────────────────────────────────────────────────
  151. function cmdResolveVersion() {
  152. const version = confVersion();
  153. const event = process.env.GITHUB_EVENT_NAME || "";
  154. const ref = process.env.GITHUB_REF || "";
  155. const refName = process.env.GITHUB_REF_NAME || "";
  156. const dryRun = process.env.DRY_RUN || "false";
  157. let isRelease = "false";
  158. let tag = "";
  159. if (dryRun === "true") {
  160. tag = `v${version}`;
  161. log(`[dry-run] Using version from VERSION: ${version}`);
  162. } else if (event === "push" && ref.startsWith("refs/tags/v")) {
  163. isRelease = "true";
  164. tag = refName;
  165. const tagVer = tag.replace(/^v/, "");
  166. if (tagVer !== version) {
  167. error(`Tag version (${tagVer}) does not match VERSION (${version}).`);
  168. error("Run npm run bump (writes VERSION + derived files), then re-tag.");
  169. process.exit(1);
  170. }
  171. }
  172. // Channel is derived from the version string itself: a `-rc.N` suffix marks
  173. // a release candidate. The CI workflow uses `prerelease` to set the GitHub
  174. // Release flag, and `channel` to decide whether to mirror latest.json into
  175. // the `rc-latest` mutable release.
  176. const isRc = /-rc\.\d+$/.test(version);
  177. const channel = isRc ? "rc" : "stable";
  178. const prerelease = isRc ? "true" : "false";
  179. for (const [k, v] of [
  180. ["is_release", isRelease],
  181. ["version", version],
  182. ["tag", tag],
  183. ["dry_run", dryRun],
  184. ["channel", channel],
  185. ["prerelease", prerelease],
  186. ]) {
  187. ghOutput(k, v);
  188. }
  189. ghEnv("VERSION", version);
  190. ghEnv("TAG", tag);
  191. console.log(`✓ Version: ${version} (release=${isRelease}, channel=${channel}, dry_run=${dryRun})`);
  192. }
  193. function cmdVerifySecrets(args) {
  194. const names = args._;
  195. let ok = true;
  196. for (const name of names) {
  197. if (!process.env[name]) {
  198. error(`Secret '${name}' is empty or not set.`);
  199. ok = false;
  200. }
  201. }
  202. if (!ok) process.exit(1);
  203. console.log(`✓ All required secrets are present (${names.length} checked).`);
  204. }
  205. function cmdPrepareChangelog(args) {
  206. const [version, output] = args._;
  207. const commitRange = args._[2] || "HEAD~50..HEAD";
  208. if (!version || !output) {
  209. console.error("Usage: prepare-changelog <version> <output> [range]");
  210. process.exit(1);
  211. }
  212. // Extract changelog section
  213. let section = "";
  214. try {
  215. const changelog = readFileSync("CHANGELOG.md", "utf8");
  216. const re = new RegExp(`^## \\[${version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\]`, "m");
  217. const start = changelog.search(re);
  218. if (start >= 0) {
  219. const afterHeader = changelog.indexOf("\n", start) + 1;
  220. const nextSection = changelog.indexOf("\n## [", afterHeader);
  221. section = changelog.slice(afterHeader, nextSection > 0 ? nextSection : undefined).trim();
  222. }
  223. } catch {}
  224. // Contributors
  225. let contributors = "";
  226. try {
  227. const r = run(["git", "log", `--format=%aN`, commitRange], { capture: true });
  228. const seen = new Set();
  229. for (const name of (r.stdout || "").split("\n").map((l) => l.trim()).filter(Boolean)) {
  230. if (!seen.has(name)) {
  231. seen.add(name);
  232. contributors += `- ${name}\n`;
  233. }
  234. }
  235. } catch {}
  236. let body = "## Changelog\n\n";
  237. body += section || `_No changelog section found for version ${version} in CHANGELOG.md._`;
  238. body += "\n\n## Contributors\n\n";
  239. body += contributors || `_No commit contributors found in range ${commitRange}._\n`;
  240. writeFileSync(output, body);
  241. const lines = body.split("\n").length;
  242. console.log(`✓ Release notes written to ${output} (${lines} lines)`);
  243. }
  244. function cmdUpdateLatestJson(args) {
  245. const { platform, url, "sig-file": sigFile, tag, version, upload } = args;
  246. const mirrorToRcLatest = args["mirror-to-rc-latest"] || false;
  247. const signature = readFileSync(sigFile, "utf8").trim();
  248. // Try to download existing manifest
  249. const dl = run(["gh", "release", "download", tag, "--pattern", "latest.json", "--output", "latest.json", "--clobber"], { capture: true });
  250. let manifest;
  251. if (dl.status === 0 && existsSync("latest.json")) {
  252. manifest = JSON.parse(readFileSync("latest.json", "utf8"));
  253. } else {
  254. let notes = "";
  255. try {
  256. const r = run(["git", "tag", "-l", "--format=%(contents)", tag], { capture: true });
  257. notes = (r.stdout || "").trim();
  258. } catch {}
  259. if (!notes) notes = `NeuroSkill\u2122 v${version}`;
  260. manifest = {
  261. version,
  262. notes,
  263. pub_date: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
  264. platforms: {},
  265. };
  266. }
  267. manifest.platforms = manifest.platforms || {};
  268. manifest.platforms[platform] = { url, signature };
  269. writeFileSync("latest.json", JSON.stringify(manifest, null, 2) + "\n");
  270. const plats = Object.keys(manifest.platforms).sort().join(", ");
  271. console.log(`Updated latest.json (${Object.keys(manifest.platforms).length} platform(s): ${plats})`);
  272. if (upload) {
  273. run(["gh", "release", "upload", tag, "latest.json", "--clobber"], { check: true });
  274. console.log(`✓ latest.json uploaded to release ${tag}`);
  275. }
  276. // The `rc-latest` release is a mutable pointer used by the RC update channel.
  277. // Both stable and RC builds mirror their latest.json here so opted-in users
  278. // always receive the most recent build of either kind. Stable users hit
  279. // `releases/latest/download/latest.json` instead, which GitHub auto-resolves
  280. // to the most recent non-prerelease release (skipping RCs).
  281. if (mirrorToRcLatest) {
  282. ensureRcLatestRelease();
  283. run(["gh", "release", "upload", "rc-latest", "latest.json", "--clobber"], { check: true });
  284. console.log("✓ latest.json mirrored to rc-latest");
  285. }
  286. }
  287. /**
  288. * Ensure the `rc-latest` GitHub Release exists. It's a mutable pointer release
  289. * tagged at whatever commit was current when first created — the tag itself
  290. * doesn't matter because the URL clients use is
  291. * https://github.com/<repo>/releases/download/rc-latest/latest.json
  292. * which is asset-based, not commit-based. Marked `prerelease` so it never
  293. * becomes "latest" in GitHub's auto-resolution.
  294. */
  295. function ensureRcLatestRelease() {
  296. const view = run(["gh", "release", "view", "rc-latest"], { capture: true });
  297. if (view.status === 0) return;
  298. log("rc-latest release does not exist — creating");
  299. run([
  300. "gh", "release", "create", "rc-latest",
  301. "--prerelease",
  302. "--title", "RC channel pointer",
  303. "--notes", "Mutable release that always carries the latest latest.json (RC or stable build). Used by users opted into the rc update channel. Do not delete.",
  304. ], { check: true });
  305. }
  306. /**
  307. * Problems with an LLM catalog that would mislead users or break the app; [] if
  308. * none. Curated quirks the app tolerates (a family with two hand-picked
  309. * recommended quants) are not errors.
  310. */
  311. export function validateLlmCatalog(cat) {
  312. const errors = [];
  313. if (!cat || typeof cat !== "object") return ["catalog is not a JSON object"];
  314. const families = cat.families ?? {};
  315. const models = Array.isArray(cat.models) ? cat.models : [];
  316. if (models.length === 0) errors.push("no models");
  317. const seen = new Set();
  318. for (const m of models) {
  319. const id = `${m.family}/${m.filename}`;
  320. if (!families[m.family]) errors.push(`${id}: unknown family`);
  321. // GGUF files, or multi-file packs (mlx-community) listing their files.
  322. const isPack = Array.isArray(m.shard_files) && m.shard_files.includes(m.filename);
  323. if (!/\.gguf$/i.test(m.filename ?? "") && !isPack) errors.push(`${id}: not a .gguf file or a listed pack file`);
  324. if (!(typeof m.size_gb === "number" && m.size_gb > 0)) errors.push(`${id}: size_gb must be > 0`);
  325. if (seen.has(id)) errors.push(`${id}: duplicate entry`);
  326. seen.add(id);
  327. }
  328. for (const [id, f] of Object.entries(families)) {
  329. if (!f.repo) errors.push(`family ${id}: no repo`);
  330. }
  331. const isMmproj = (m) => /mmproj/i.test(m.filename);
  332. const active = models.find((m) => m.filename === cat.active_model);
  333. if (!active) errors.push(`active_model ${cat.active_model} is not in the catalog`);
  334. else if (isMmproj(active)) errors.push(`active_model ${cat.active_model} is a vision projector`);
  335. if (cat.active_mmproj && !models.some((m) => isMmproj(m) && m.filename === cat.active_mmproj)) {
  336. errors.push(`active_mmproj ${cat.active_mmproj} is not a projector in the catalog`);
  337. }
  338. return errors;
  339. }
  340. /**
  341. * Publish the bundled LLM catalog (src-tauri/llm_catalog.json — the file
  342. * compiled into this build) as release assets with a `compatibility` block
  343. * ([`llmCatalogCompatibility`]) prepended, plus a SHA-256.
  344. *
  345. * Usage:
  346. * node scripts/ci.mjs publish-llm-catalog [--tag <tag>] [--upload] [--mirror-to-rc-latest]
  347. *
  348. * Without --upload it only validates and writes the files (dry run). Stable
  349. * clients can then fetch releases/latest/download/llm_catalog.json; the RC
  350. * channel reads the copy mirrored to the `rc-latest` release.
  351. */
  352. /** Layout of llm_catalog.json (normalized `families` + `models`). Bump when
  353. * the app can no longer read an older catalog, or an older app a newer one. */
  354. const LLM_CATALOG_SCHEMA = 1;
  355. /** First release whose app reads schema 1 (catalog normalized in d04cd538). */
  356. const LLM_CATALOG_MIN_APP_VERSION = "0.0.131-rc.10";
  357. /** Platforms every release builds — the latest.json platform keys. */
  358. const RELEASE_PLATFORMS = ["darwin-aarch64", "linux-x86_64", "windows-x86_64"];
  359. /** The rlx git revision this build runs models on, from Cargo.lock. */
  360. function lockedRlxRevision() {
  361. const lock = readFileSync("Cargo.lock", "utf8");
  362. const m = lock.match(/\[\[package\]\]\nname = "rlx"\nversion = "([^"]+)"\nsource = "([^"]+)"/);
  363. if (!m) return null;
  364. const [, version, source] = m;
  365. return { version, source: source.replace(/#.*$/, ""), rev: source.includes("#") ? source.split("#").pop() : null };
  366. }
  367. /**
  368. * What a published catalog is compatible with. Reading it needs an app of at
  369. * least `min_app_version`; the models in it were bundled with, and validated
  370. * against, `bundled_in` (that app build) running `runtime.rlx`. An older app
  371. * can read the catalog but may lack runtime support for a newer model.
  372. */
  373. function llmCatalogCompatibility() {
  374. const version = confVersion();
  375. const commit = process.env.GITHUB_SHA || run(["git", "rev-parse", "HEAD"], { capture: true }).stdout.trim();
  376. return {
  377. schema: LLM_CATALOG_SCHEMA,
  378. min_app_version: LLM_CATALOG_MIN_APP_VERSION,
  379. bundled_in: { version, tag: `v${version}`, commit, platforms: RELEASE_PLATFORMS },
  380. runtime: { rlx: lockedRlxRevision() },
  381. };
  382. }
  383. function cmdPublishLlmCatalog(args) {
  384. const src = "src-tauri/llm_catalog.json";
  385. const cat = JSON.parse(readFileSync(src, "utf8"));
  386. const errors = validateLlmCatalog(cat);
  387. if (errors.length) {
  388. throw new Error(`${src} is not publishable:\n ${errors.join("\n ")}`);
  389. }
  390. // The bundled catalog plus where it is compatible (the app ignores unknown
  391. // top-level fields, so this stays readable by any schema-1 app).
  392. const compatibility = llmCatalogCompatibility();
  393. const raw = `${JSON.stringify({ compatibility, ...cat }, null, 2)}\n`;
  394. const files = ["llm_catalog.json", "llm_catalog.json.sha256"];
  395. writeFileSync(files[0], raw);
  396. writeFileSync(files[1], `${createHash("sha256").update(raw).digest("hex")} llm_catalog.json\n`);
  397. console.log(`✓ llm_catalog.json valid (${cat.models.length} models, ${Object.keys(cat.families).length} families, default ${cat.active_model})`);
  398. console.log(` compatible: app >= ${compatibility.min_app_version} (schema ${compatibility.schema}); bundled in v${compatibility.bundled_in.version}, rlx ${compatibility.runtime.rlx?.rev?.slice(0, 8) ?? "?"}`);
  399. if (args.upload) {
  400. if (!args.tag) throw new Error("--upload needs --tag");
  401. run(["gh", "release", "upload", args.tag, ...files, "--clobber"], { check: true });
  402. console.log(`✓ llm_catalog.json uploaded to release ${args.tag}`);
  403. }
  404. if (args["mirror-to-rc-latest"]) {
  405. ensureRcLatestRelease();
  406. run(["gh", "release", "upload", "rc-latest", ...files, "--clobber"], { check: true });
  407. console.log("✓ llm_catalog.json mirrored to rc-latest");
  408. }
  409. }
  410. /**
  411. * Reconcile the Homebrew cask (Casks/neuroskill.rb) to a released build.
  412. *
  413. * Usage:
  414. * node scripts/ci.mjs update-cask [--version <ver>] [--sha256 <hex>]
  415. * [--dmg <path>] [--cask <path>] [--repo <owner/name>]
  416. *
  417. * Resolution:
  418. * version : --version, else the latest *stable* (non-prerelease) GitHub release.
  419. * sha256 : --sha256, else computed from --dmg, else the release asset's digest
  420. * fetched via `gh api` (no download of the ~100 MB DMG).
  421. *
  422. * Only the `version` and `sha256` lines are rewritten — every other stanza
  423. * (depends_on, zap, url template, …) is preserved. Idempotent: a no-op when the
  424. * cask already matches, so the reconcile workflow only opens a PR on real drift.
  425. */
  426. function cmdUpdateCask(args) {
  427. const repo = args.repo || process.env.GITHUB_REPOSITORY || "NeuroSkill-com/skill";
  428. const caskPath = args.cask || "Casks/neuroskill.rb";
  429. // 1. Resolve the target version — explicit, or the latest non-prerelease release.
  430. let version = args.version;
  431. if (version) {
  432. version = version.replace(/^v/, "");
  433. } else {
  434. const r = run(["gh", "api", `repos/${repo}/releases/latest`, "-q", ".tag_name"], { capture: true, check: true });
  435. version = (r.stdout || "").trim().replace(/^v/, "");
  436. if (!version) throw new Error("could not resolve the latest stable release");
  437. }
  438. const dmgName = `NeuroSkill_${version}_aarch64.dmg`;
  439. // 2. Resolve the sha256 — explicit, from a local DMG, or the release asset digest.
  440. let sha256 = args.sha256;
  441. if (!sha256 && args.dmg) {
  442. sha256 = createHash("sha256").update(readFileSync(args.dmg)).digest("hex");
  443. }
  444. if (!sha256) {
  445. const q = `.assets[] | select(.name=="${dmgName}") | .digest`;
  446. const r = run(["gh", "api", `repos/${repo}/releases/tags/v${version}`, "-q", q], { capture: true, check: true });
  447. const digest = (r.stdout || "").trim();
  448. if (!digest) throw new Error(`release v${version} has no asset named ${dmgName}`);
  449. sha256 = digest.replace(/^sha256:/, "");
  450. }
  451. if (!/^[0-9a-f]{64}$/.test(sha256)) throw new Error(`invalid sha256: ${sha256}`);
  452. // 3. Rewrite the version + sha256 lines, preserving everything else.
  453. const before = readFileSync(caskPath, "utf8");
  454. if (!/^\s*version\s+"/m.test(before) || !/^\s*sha256\s+"/m.test(before)) {
  455. throw new Error(`${caskPath} is missing a version or sha256 stanza`);
  456. }
  457. const after = before
  458. .replace(/^(\s*version\s+)"[^"]*"/m, `$1"${version}"`)
  459. .replace(/^(\s*sha256\s+)"[^"]*"/m, `$1"${sha256}"`);
  460. if (after === before) {
  461. console.log(`Cask already current: version ${version}, sha256 ${sha256.slice(0, 12)}…`);
  462. return;
  463. }
  464. writeFileSync(caskPath, after);
  465. console.log(`Updated ${caskPath} → version ${version}, sha256 ${sha256.slice(0, 12)}…`);
  466. }
  467. async function cmdDiscordNotify(args) {
  468. const webhook = process.env.DISCORD_WEBHOOK_URL;
  469. if (!webhook) {
  470. console.log("⚠ DISCORD_WEBHOOK_URL not set, skipping.");
  471. return;
  472. }
  473. let commit = "";
  474. try {
  475. // Full message (subject + body). Cap for the Discord embed field
  476. // (limit 1024) and add an ellipsis when truncated.
  477. const r = run(["git", "log", "-1", "--format=%B"], { capture: true });
  478. const full = (r.stdout || "").trim();
  479. commit = full.length > 500 ? `${full.slice(0, 500)}…` : full;
  480. } catch {}
  481. const { status, title, version, tag, platform } = args;
  482. const releaseUrl = args["release-url"] || "";
  483. const runUrl = args["run-url"] || "";
  484. const color = status === "success" ? 3066993 : 15158332;
  485. const desc = status === "success"
  486. ? `Build published and ready to download.\n\n**[Download v${version}](${releaseUrl || runUrl})**`
  487. : `The build failed. Check the run for details.\n\n**[View failed run](${runUrl})**`;
  488. const payload = JSON.stringify({
  489. embeds: [{
  490. title, description: desc, url: runUrl, color,
  491. fields: [
  492. { name: "Tag", value: `\`${tag}\``, inline: true },
  493. { name: "Version", value: `\`${version}\``, inline: true },
  494. { name: "Platform", value: platform, inline: true },
  495. { name: "Actor", value: process.env.GITHUB_ACTOR || "ci", inline: true },
  496. { name: "Commit", value: commit, inline: false },
  497. ],
  498. footer: { text: process.env.GITHUB_REPOSITORY || "" },
  499. }],
  500. });
  501. try {
  502. // Use built-in fetch (Node 18+) to avoid platform-specific curl quoting issues.
  503. const r = await fetch(webhook, {
  504. method: "POST",
  505. headers: { "Content-Type": "application/json" },
  506. body: payload,
  507. });
  508. if (!r.ok) throw new Error(`HTTP ${r.status}`);
  509. } catch {
  510. console.log("⚠ Discord notification failed (non-fatal).");
  511. }
  512. }
  513. function findFiles(dir) {
  514. const results = [];
  515. for (const entry of readdirSync(dir, { withFileTypes: true })) {
  516. const full = join(dir, entry.name);
  517. if (entry.isDirectory()) results.push(...findFiles(full));
  518. else results.push(full);
  519. }
  520. return results;
  521. }
  522. // Apple ships several certificate types under "codesigning". Only one of them
  523. // — `Developer ID Application` — produces binaries Gatekeeper trusts for
  524. // distribution. The Safari extension wrapper this app builds at runtime is
  525. // only loaded by Safari when the parent (.app) clears Gatekeeper, so signing
  526. // the main app with anything else (Apple Development, Mac Developer, ad-hoc,
  527. // self-signed) silently breaks the Safari extension flow on end-user Macs.
  528. //
  529. // Catch the wrong identity here, before a 15-minute build burns a release
  530. // slot. The check is cheap: just inspect the secret string.
  531. function cmdValidateAppleSigningIdentity() {
  532. const id = process.env.APPLE_SIGNING_IDENTITY || "";
  533. if (!id) {
  534. error("APPLE_SIGNING_IDENTITY is empty.");
  535. process.exit(1);
  536. }
  537. if (!id.startsWith("Developer ID Application")) {
  538. error(`APPLE_SIGNING_IDENTITY must be a 'Developer ID Application' certificate.`);
  539. error(` Got: ${id.replace(/\(.+\)/, "(…)")}`);
  540. error(` Why: only Developer ID Application certs pass Gatekeeper for distribution.`);
  541. error(` Apple Development / Mac Developer certs only work for the signing`);
  542. error(` developer's own Mac via Xcode — Safari refuses to load extensions`);
  543. error(` from apps Gatekeeper rejects on end-user machines.`);
  544. error(` Fix: regenerate the cert at https://developer.apple.com/account/resources/certificates`);
  545. error(` choosing 'Developer ID Application', export to .p12, and update both`);
  546. error(` APPLE_CERTIFICATE and APPLE_SIGNING_IDENTITY secrets.`);
  547. process.exit(1);
  548. }
  549. console.log(`✓ APPLE_SIGNING_IDENTITY is a Developer ID Application certificate.`);
  550. }
  551. function cmdImportAppleCert() {
  552. const tmp = process.env.RUNNER_TEMP;
  553. const keychain = join(tmp, "app-signing.keychain-db");
  554. const password = execSync("openssl rand -base64 32", { encoding: "utf8" }).trim();
  555. ghEnv("KEYCHAIN_PATH", keychain);
  556. ghEnv("KEYCHAIN_PASSWORD", password);
  557. run(["security", "create-keychain", "-p", password, keychain], { check: true });
  558. run(["security", "set-keychain-settings", "-lut", "21600", keychain], { check: true });
  559. run(["security", "unlock-keychain", "-p", password, keychain], { check: true });
  560. const certPath = join(tmp, "cert.p12");
  561. writeFileSync(certPath, Buffer.from(process.env.APPLE_CERTIFICATE, "base64"));
  562. run(["security", "import", certPath, "-k", keychain, "-P", process.env.APPLE_CERTIFICATE_PASSWORD, "-T", "/usr/bin/codesign", "-T", "/usr/bin/security"], { check: true });
  563. rmSync(certPath);
  564. run(["security", "set-key-partition-list", "-S", "apple-tool:,apple:", "-s", "-k", password, keychain], { check: true });
  565. run(["security", "list-keychains", "-d", "user", "-s", keychain, "login.keychain"], { check: true });
    • Dismissed after review: Reads a credential file in a script that also sends data over the network
    • Line 625 on GitHub
  566. console.log(`✓ Apple Developer certificate imported into ${keychain}`);
  567. }
  568. /** Prepare WidgetKit automatic signing on GitHub Actions runners. */
  569. function cmdSetupWidgetSigning() {
  570. const teamId = process.env.APPLE_TEAM_ID;
  571. if (!teamId) {
  572. warning("APPLE_TEAM_ID not set — skipping widget signing setup");
  573. return;
  574. }
  575. ghEnv("WIDGET_CODE_SIGN_STYLE", "Automatic");
  576. // Optional: App Store Connect API key for -allowProvisioningUpdates.
  577. const ascKeyId = process.env.APPLE_ASC_KEY_ID;
  578. const ascIssuer = process.env.APPLE_ASC_KEY_ISSUER_ID;
  579. const ascKeyB64 = process.env.APPLE_ASC_KEY_BASE64;
  580. if (ascKeyId && ascIssuer && ascKeyB64) {
  581. const keyDir = join(process.env.HOME, ".private_keys");
  582. mkdirSync(keyDir, { recursive: true });
  583. const keyPath = join(keyDir, `AuthKey_${ascKeyId}.p8`);
  584. writeFileSync(keyPath, Buffer.from(ascKeyB64, "base64"), { mode: 0o600 });
  585. ghEnv("AUTH_KEY_PATH", keyPath);
  586. ghEnv("AUTH_KEY_ID", ascKeyId);
  587. ghEnv("AUTH_KEY_ISSUER_ID", ascIssuer);
  588. console.log(`✓ App Store Connect API key installed for widget provisioning (${ascKeyId})`);
  589. } else {
  590. console.log("ℹ No APPLE_ASC_KEY_* secrets — relying on portal profiles + -allowProvisioningUpdates");
  591. }
  592. // Optional: pre-downloaded macOS provisioning profile (base64 .provisionprofile).
  593. const profileB64 = process.env.APPLE_WIDGET_PROVISIONING_PROFILE_BASE64;
  594. if (profileB64) {
  595. const profileDir = join(process.env.HOME, "Library/MobileDevice/Provisioning Profiles");
  596. mkdirSync(profileDir, { recursive: true });
  597. const profilePath = join(profileDir, "SkillWidgetsWidgetExtension.provisionprofile");
  598. writeFileSync(profilePath, Buffer.from(profileB64, "base64"));
  599. console.log(`✓ Widget provisioning profile installed (${profilePath})`);
  600. }
  601. console.log(`✓ Widget signing ready (team ${teamId}, automatic)`);
  602. }
  603. function cmdBuildWidgets() {
  604. const widgetScript = join("extensions", "widgets", "build-widgets.sh");
  605. if (!existsSync(widgetScript)) {
  606. throw new Error(`Missing ${widgetScript}`);
  607. }
  608. run(["bash", widgetScript, "--release", "--ci"], { check: true });
  609. }
  610. function cmdValidateNotarization() {
  611. console.log("Checking notarization credentials …");
  612. const r = run(["xcrun", "notarytool", "history", "--apple-id", process.env.APPLE_ID, "--password", process.env.APPLE_PASSWORD, "--team-id", process.env.APPLE_TEAM_ID, "--output-format", "json"], { capture: true });
  613. const output = (r.stdout || "") + (r.stderr || "");
  614. if (output.includes('"history"')) {
  615. console.log("✓ Notarization credentials are valid.");
  616. } else if (/unauthorized|invalid.*credentials|401/i.test(output)) {
  617. error("Apple notarization credentials are invalid.");
  618. error("Generate a new app-specific password at https://appleid.apple.com");
  619. error("Then update APPLE_PASSWORD in: GitHub → Settings → Environments → Release → Secrets");
  620. process.exit(1);
  621. } else {
  622. warning("Could not verify notarization credentials (Apple API may be intermittent).");
  623. warning(`Output: ${output.slice(0, 500)}`);
  624. console.log("Proceeding — actual notarization will fail later if credentials are invalid.");
  625. }
  626. }
  627. function cmdFreeDiskSpace() {
  628. const dirs = ["/usr/local/lib/android", "/usr/share/dotnet", "/opt/ghc", "/usr/local/.ghcup", "/usr/local/share/powershell", "/usr/local/share/chromium", "/usr/share/swift", "/opt/hostedtoolcache/CodeQL"];
  629. for (const d of dirs) {
  630. if (existsSync(d)) run(["sudo", "rm", "-rf", d]);
  631. }
  632. run(["sudo", "docker", "image", "prune", "-af"], { capture: true });
  633. run(["df", "-h", "/"]);
  634. }
  635. function cmdInstallProtocWindows() {
  636. // Check if already installed
  637. const which = run(["where", "protoc"], { capture: true });
  638. if (which.status === 0) {
  639. run(["protoc", "--version"]);
  640. return;
  641. }
  642. // Try Chocolatey
  643. let installed = false;
  644. for (let i = 1; i <= 3; i++) {
  645. run(["choco", "install", "protoc", "--no-progress", "-y"], { capture: true });
  646. const check = run(["where", "protoc"], { capture: true });
  647. if (check.status === 0) {
  648. installed = true;
  649. break;
  650. }
  651. log(`choco attempt ${i} failed, retrying in ${5 * i}s...`);
  652. execSync(`timeout /t ${5 * i} /nobreak >nul 2>&1`, { shell: true, stdio: "ignore" });
  653. }
  654. if (!installed) {
  655. console.log("[warn] Chocolatey unavailable; falling back to direct download");
  656. const ver = "25.3";
  657. const url = `https://github.com/protocolbuffers/protobuf/releases/download/v${ver}/protoc-${ver}-win64.zip`;
  658. const tmp = process.env.RUNNER_TEMP || tmpdir();
  659. const zipPath = join(tmp, `protoc-${ver}-win64.zip`);
  660. const dest = join(tmp, `protoc-${ver}`);
  661. execSync(`curl -fSL "${url}" -o "${zipPath}"`, { stdio: "inherit" });
  662. execSync(`tar -xf "${zipPath}" -C "${dest}"`, { stdio: "inherit" });
  663. const binDir = join(dest, "bin");
  664. if (!existsSync(join(binDir, "protoc.exe"))) {
  665. throw new Error("protoc fallback install failed: protoc.exe not found");
  666. }
  667. ghPath(binDir);
  668. process.env.PATH = `${binDir};${process.env.PATH}`;
  669. console.log("[ok] Installed protoc via direct download");
  670. }
  671. run(["protoc", "--version"]);
  672. }
  673. function cmdCompileProduct() {
  674. const opts = parseCompileProductArgs(process.argv.slice(3));
  675. if (opts.help) {
  676. printCompileProductHelp();
  677. return;
  678. }
  679. compileProduct(opts);
  680. }
  681. function cmdSelfTest() {
  682. const errors = [];
  683. const commandMap = {
  684. "resolve-version": cmdResolveVersion, "verify-secrets": cmdVerifySecrets,
  685. "prepare-changelog": cmdPrepareChangelog, "update-latest-json": cmdUpdateLatestJson,
  686. "discord-notify": cmdDiscordNotify,
  687. "import-apple-cert": cmdImportAppleCert,
  688. "setup-widget-signing": cmdSetupWidgetSigning,
  689. "build-widgets": cmdBuildWidgets,
  690. "validate-notarization": cmdValidateNotarization,
  691. "validate-apple-signing-identity": cmdValidateAppleSigningIdentity,
  692. "free-disk-space": cmdFreeDiskSpace, "install-protoc-windows": cmdInstallProtocWindows,
  693. "compile-product": cmdCompileProduct,
  694. "self-test": cmdSelfTest, "dry-run-release": cmdDryRunRelease,
  695. "update-cask": cmdUpdateCask, "publish-llm-catalog": cmdPublishLlmCatalog,
  696. };
  697. for (const [name, fn] of Object.entries(commandMap)) {
  698. if (typeof fn !== "function") errors.push(` ${name}: not a function`);
  699. else log(`✓ ${name}`);
  700. }
  701. // Check workflow references
  702. try {
  703. const known = new Set(Object.keys(commandMap));
  704. for (const yml of readdirSync(".github/workflows").filter((f) => f.endsWith(".yml"))) {
  705. const content = readFileSync(join(".github/workflows", yml), "utf8");
  706. const re = /scripts\/ci\.mjs\s+([a-z][-a-z]*)/g;
  707. let m;
  708. while ((m = re.exec(content))) {
  709. if (!known.has(m[1])) errors.push(` ${yml}: unknown command '${m[1]}'`);
  710. }
  711. }
  712. } catch {}
  713. // The catalog every release publishes (publish-llm-catalog) must be valid.
  714. try {
  715. const catErrors = validateLlmCatalog(JSON.parse(readFileSync("src-tauri/llm_catalog.json", "utf8")));
  716. if (catErrors.length) errors.push(...catErrors.map((e) => ` llm_catalog.json: ${e}`));
  717. else log("✓ llm_catalog.json publishable");
  718. } catch (e) {
  719. errors.push(` llm_catalog.json: ${e.message}`);
  720. }
  721. // Verify confVersion
  722. try {
  723. const v = confVersion();
  724. log(`✓ confVersion() = ${v}`);
  725. } catch (e) {
  726. errors.push(` confVersion(): ${e.message}`);
  727. }
  728. // OS umbrella mapping
  729. try {
  730. const cases = [
  731. ["aarch64-apple-darwin", "apple"],
  732. ["x86_64-unknown-linux-gnu", "linux"],
  733. ["x86_64-pc-windows-msvc", "windows"],
  734. ];
  735. for (const [triple, want] of cases) {
  736. const got = daemonOsFeature(triple);
  737. if (got !== want) {
  738. errors.push(` daemonOsFeature(${triple}): got ${got}, want ${want}`);
  739. }
  740. }
  741. log("✓ daemonOsFeature OS mapping");
  742. } catch (e) {
  743. errors.push(` daemonOsFeature(): ${e.message}`);
  744. }
  745. if (errors.length) {
  746. error("self-test failed:");
  747. errors.forEach((e) => console.log(e));
  748. process.exit(1);
  749. }
  750. log(`✓ all ${Object.keys(commandMap).length} commands OK`);
  751. }
  752. function cmdDryRunRelease(args) {
  753. const target = args.target || "aarch64-apple-darwin";
  754. const skipCompile = args["skip-compile"] || false;
  755. log("Step 1/6: resolve version");
  756. const version = confVersion();
  757. log(`version = ${version}`);
  758. log("Step 2/6: build frontend");
  759. if (!skipCompile) run(["npm", "run", "build"], { check: true });
  760. else log("(skipped)");
  761. log("Step 3/6: cargo build (compile-product)");
  762. if (!skipCompile) {
  763. compileProduct({
  764. target,
  765. release: true,
  766. locked: false,
  767. timings: false,
  768. daemon: true,
  769. app: true,
  770. tty: "auto",
  771. });
  772. } else log("(skipped)");
  773. log("Step 4/6: assemble .app bundle");
  774. const binary = `src-tauri/target/${target}/release/skill`;
  775. if (!existsSync(binary)) {
  776. if (skipCompile) warning(`Binary not found at ${binary} — run without --skip-compile first`);
  777. else { error(`Binary not found at ${binary} after build`); process.exit(1); }
  778. } else {
  779. run(["bash", "scripts/assemble-macos-app.sh", target], { check: true });
  780. }
  781. log("Step 5/6: prepare changelog");
  782. const tag = `v${version}`;
  783. const prev = run(["git", "describe", "--tags", "--abbrev=0", `${tag}^`], { capture: true });
  784. const prevTag = prev.status === 0 ? prev.stdout.trim() : "";
  785. const range = prevTag ? `${prevTag}..HEAD` : "HEAD~20..HEAD";
  786. cmdPrepareChangelog({ _: [version, "dry-run-release-notes.md", range] });
  787. log("Step 6/6: summary");
  788. const app = `src-tauri/target/${target}/release/bundle/macos/NeuroSkill.app`;
  789. console.log("\n" + "=".repeat(60));
  790. console.log(` Dry-run release: v${version} (${target})`);
  791. console.log("=".repeat(60));
  792. if (existsSync(app)) {
  793. const size = findFiles(app).reduce((s, f) => s + statSync(f).size, 0);
  794. console.log(` .app bundle: ${app} (${(size / 1048576).toFixed(1)} MB)`);
  795. } else console.log(" .app bundle: (not found)");
  796. console.log(" changelog: dry-run-release-notes.md");
  797. console.log(`\n To run: open '${app}'`);
  798. console.log(` To sign: APPLE_SIGNING_IDENTITY=... bash scripts/assemble-macos-app.sh ${target}`);
  799. console.log("=".repeat(60) + "\n");
  800. }
  801. // ── CLI ──────────────────────────────────────────────────────────────────────
  802. const COMMANDS = {
  803. "resolve-version": cmdResolveVersion,
  804. "verify-secrets": cmdVerifySecrets,
  805. "prepare-changelog": cmdPrepareChangelog,
  806. "update-latest-json": (a) => cmdUpdateLatestJson(a),
  807. "discord-notify": (a) => cmdDiscordNotify(a),
  808. "import-apple-cert": cmdImportAppleCert,
  809. "setup-widget-signing": cmdSetupWidgetSigning,
  810. "build-widgets": cmdBuildWidgets,
  811. "validate-notarization": cmdValidateNotarization,
  812. "validate-apple-signing-identity": cmdValidateAppleSigningIdentity,
  813. "free-disk-space": cmdFreeDiskSpace,
  814. "install-protoc-windows": cmdInstallProtocWindows,
  815. "compile-product": cmdCompileProduct,
  816. "self-test": cmdSelfTest,
  817. "dry-run-release": (a) => cmdDryRunRelease(a),
  818. "update-cask": cmdUpdateCask,
  819. "publish-llm-catalog": cmdPublishLlmCatalog,
  820. };
  821. async function main() {
  822. const argv = process.argv.slice(2);
  823. const command = argv[0];
  824. if (!command || command === "--help" || command === "-h") {
  825. console.log("Usage: node scripts/ci.mjs <command> [args...]");
  826. console.log("\nCommands:");
  827. for (const name of Object.keys(COMMANDS)) console.log(` ${name}`);
  828. process.exit(0);
  829. }
  830. if (!COMMANDS[command]) {
  831. error(`Unknown command: ${command}`);
  832. process.exit(1);
  833. }
  834. CMD = command;
  835. const args = parseArgs(argv.slice(1), {
  836. "--platform": "platform", "--url": "url", "--sig-file": "sig-file",
  837. "--tag": "tag", "--version": "version", "--upload": true,
  838. "--mirror-to-rc-latest": true,
  839. "--status": "status", "--title": "title", "--release-url": "release-url",
  840. "--run-url": "run-url", "--target": "target", "--skip-compile": true,
  841. "--sha256": "sha256", "--dmg": "dmg", "--cask": "cask", "--repo": "repo",
  842. });
  843. log("starting");
  844. try {
  845. await COMMANDS[command](args);
  846. } catch (e) {
  847. if (e.status !== undefined) {
  848. error(`Command failed (exit ${e.status}): ${e.message}`);
  849. if (e.stdout) console.log(`[${CMD}] stdout:\n${e.stdout.trim()}`);
  850. if (e.stderr) console.log(`[${CMD}] stderr:\n${e.stderr.trim()}`);
  851. } else {
  852. error(`${e.constructor.name}: ${e.message}`);
  853. console.error(e.stack);
  854. }
  855. const elapsed = ((performance.now() - T0) / 1000).toFixed(1);
  856. error(`Failed after ${elapsed}s`);
  857. process.exit(1);
  858. }
  859. const elapsed = ((performance.now() - T0) / 1000).toFixed(1);
  860. log(`done (${elapsed}s)`);
  861. }
  862. main();
scripts/create-windows-nsis.ps1 · Bundled script · 910 lines · 2 findings marked
  1. <#
  2. .SYNOPSIS
  3. Create a Windows NSIS installer from a pre-built release binary.
  4. .DESCRIPTION
  5. Assembles the application directory structure, generates an NSIS installer
  6. with background/banner images (app icon + version), and optionally signs
  7. the installer with a code-signing certificate.
  8. This script bypasses the Tauri CLI bundler for cases where it fails or
  9. when a standalone packaging step is preferred.
  10. Prerequisites:
  11. - NSIS installed (makensis on PATH, or set $env:NSIS_DIR)
  12. Install: choco install nsis -or- winget install NSIS.NSIS
  13. - Python 3 with Pillow (for installer images)
  14. Install: pip install Pillow
  15. - The release binary must be pre-built
  16. .PARAMETER Target
  17. Rust target triple (default: x86_64-pc-windows-msvc)
  18. .PARAMETER Sign
  19. When set, sign the installer with signtool.exe using $env:CERTIFICATE_THUMBPRINT
  20. .EXAMPLE
  21. .\scripts\create-windows-nsis.ps1
  22. .\scripts\create-windows-nsis.ps1 -Sign
  23. $env:CERTIFICATE_THUMBPRINT = "ABC123..." ; .\scripts\create-windows-nsis.ps1 -Sign
  24. #>
  25. param(
  26. [string]$Target = "x86_64-pc-windows-msvc",
  27. [switch]$Sign
  28. )
  29. Set-StrictMode -Version Latest
  30. $ErrorActionPreference = "Stop"
  31. # Ensure consistent UTF-8 handling for trademark and other non-ASCII UI text.
  32. try {
  33. $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
  34. [Console]::InputEncoding = $utf8NoBom
  35. [Console]::OutputEncoding = $utf8NoBom
  36. $OutputEncoding = $utf8NoBom
  37. chcp 65001 | Out-Null
  38. } catch {
  39. # best-effort only; keep script functional in restricted hosts
  40. }
  41. $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
  42. $Root = Split-Path -Parent $ScriptDir
  43. $TauriDir = Join-Path $Root "src-tauri"
  44. $Conf = Get-Content (Join-Path $TauriDir "tauri.conf.json") -Raw | ConvertFrom-Json
  45. $ProductName = $Conf.productName
  46. $ProductDisplayName = if ($ProductName.EndsWith("™")) { $ProductName } else { "$ProductName™" }
  47. $Version = $Conf.version
  48. # NSIS's VIProductVersion requires strict 4-segment numeric format X.X.X.X
  49. # (Win32 VS_FIXEDFILEINFO). User-facing ProductVersion/FileVersion strings
  50. # accept any text, but VIProductVersion does not — it rejects "-rc.N" suffixes.
  51. # Map the SemVer string to a numeric 4-tuple:
  52. # "0.0.130" -> "0.0.130.0"
  53. # "0.0.130-rc.2" -> "0.0.130.2" (use RC number as fourth segment)
  54. # "0.0.130-beta.7" -> "0.0.130.7"
  55. if ($Version -match '^(\d+\.\d+\.\d+)(?:-[A-Za-z]+\.(\d+))?') {
  56. $vibase = $Matches[1]
  57. $vibuild = if ($Matches[2]) { $Matches[2] } else { "0" }
  58. $VIVersion = "$vibase.$vibuild"
  59. } else {
  60. $VIVersion = "0.0.0.0"
  61. }
  62. $BinaryName = "skill.exe"
  63. $TargetReleaseDir = Join-Path $TauriDir "target/$Target/release"
  64. $HostReleaseDir = Join-Path $TauriDir "target/release"
  65. $TargetBinary = Join-Path -Path $TargetReleaseDir -ChildPath $BinaryName
  66. $HostBinary = Join-Path -Path $HostReleaseDir -ChildPath $BinaryName
  67. $BinaryCandidates = @(
  68. $TargetBinary,
  69. $HostBinary
  70. )
  71. $Binary = $null
  72. $ReleaseDir = $null
  73. foreach ($candidate in $BinaryCandidates) {
  74. if (Test-Path $candidate) {
  75. $Binary = $candidate
  76. $ReleaseDir = Split-Path -Parent $candidate
  77. break
  78. }
  79. }
  80. if (-not $Binary) {
  81. Write-Error @"
  82. Release binary not found.
  83. Checked:
  84. - $($BinaryCandidates[0])
  85. - $($BinaryCandidates[1])
  86. Run first: npx tauri build --target $Target --no-bundle
  87. -or- npx tauri build --no-bundle
  88. -or- cargo build --release --target $Target --features custom-protocol
  89. "@
  90. exit 1
  91. }
  92. if ($Binary -eq $HostBinary) {
  93. Write-Warning "Using host release binary layout at target/release/$BinaryName (no explicit Rust target output path found)."
  94. }
  95. Write-Host "-> Creating NSIS installer for $ProductName v$Version ($Target)"
  96. # ── Locate NSIS ─────────────────────────────────────────────────────────────
  97. $NsisDir = $env:NSIS_DIR
  98. if ($NsisDir -and (Test-Path $NsisDir) -and -not (Test-Path (Join-Path $NsisDir "makensis.exe"))) {
  99. $item = Get-Item $NsisDir -ErrorAction SilentlyContinue
  100. if ($item -and -not $item.PSIsContainer -and $item.Name -ieq "makensis.exe") {
  101. $NsisDir = Split-Path -Parent $item.FullName
  102. }
  103. }
  104. if (-not $NsisDir -or -not (Test-Path (Join-Path $NsisDir "makensis.exe"))) {
  105. $makensis = Get-Command makensis -ErrorAction SilentlyContinue
  106. if ($makensis) {
  107. $NsisDir = Split-Path -Parent $makensis.Source
  108. } else {
  109. # Common install locations
  110. foreach ($path in @(
  111. "C:\Program Files (x86)\NSIS",
  112. "C:\Program Files\NSIS",
  113. "$env:LOCALAPPDATA\NSIS"
  114. )) {
  115. if (Test-Path (Join-Path $path "makensis.exe")) {
  116. $NsisDir = $path
  117. break
  118. }
  119. }
  120. }
  121. }
  122. if (-not $NsisDir -or -not (Test-Path (Join-Path $NsisDir "makensis.exe"))) {
  123. Write-Error @"
  124. NSIS not found. Install it:
  125. choco install nsis
  126. -or- winget install NSIS.NSIS
  127. -or- set `$env:NSIS_DIR to the NSIS install directory
  128. "@
  129. exit 1
  130. }
  131. $MakeNsis = Join-Path $NsisDir "makensis.exe"
  132. Write-Host " NSIS: $MakeNsis"
  133. # ── Prepare staging directory ───────────────────────────────────────────────
  134. $BundleDir = Join-Path $ReleaseDir "bundle"
  135. $NsisOutDir = Join-Path $BundleDir "nsis"
  136. $Staging = Join-Path $env:TEMP "neuroskill-nsis-staging-$(Get-Random)"
  137. New-Item -ItemType Directory -Force -Path $Staging | Out-Null
  138. New-Item -ItemType Directory -Force -Path $NsisOutDir | Out-Null
  139. try {
  140. # Binary
  141. Copy-Item $Binary (Join-Path $Staging $BinaryName)
  142. Write-Host " [ok] $BinaryName"
  143. # Daemon sidecar (must sit next to skill.exe in installed dir)
  144. $DaemonName = "skill-daemon.exe"
  145. $DaemonCandidates = @(
  146. (Join-Path $ReleaseDir $DaemonName),
  147. (Join-Path $TauriDir "binaries/skill-daemon-$Target.exe")
  148. )
  149. $Daemon = $null
  150. foreach ($candidate in $DaemonCandidates) {
  151. if (Test-Path $candidate) {
  152. $Daemon = $candidate
  153. break
  154. }
  155. }
  156. if ($Daemon) {
  157. Copy-Item $Daemon (Join-Path $Staging $DaemonName) -Force
  158. Write-Host " [ok] $DaemonName"
  159. } else {
  160. Write-Warning " Missing daemon sidecar (checked release + src-tauri/binaries)"
  161. }
  162. # Icon
  163. $IconIco = Join-Path $TauriDir "icons/icon.ico"
  164. if (Test-Path $IconIco) {
  165. Copy-Item $IconIco (Join-Path $Staging "icon.ico")
  166. Write-Host " [ok] icon.ico"
  167. }
  168. # ── ONNX Runtime — no longer used on any platform ─────────────────────────
  169. # KittenTTS was the only `ort` consumer and now runs natively on RLX, so
  170. # `ort` / `ort-sys` are absent from Cargo.lock entirely and there is no
  171. # onnxruntime.dll to ship on any target. The Linux .so bundling was removed
  172. # for the same reason.
  173. # ── Bundle OpenBLAS DLL ──────────────────────────────────────────────────
  174. # rlx-cpu's `blas` default feature links against openblas; turbovec on
  175. # Linux/macOS does the same. The upstream OpenBLAS 0.3.30 Windows DLL
  176. # is statically linked against the MinGW runtime so no extra DLLs are
  177. # needed alongside it.
  178. $OpenBlasDll = $null
  179. if ($env:OPENBLAS_DLL -and (Test-Path $env:OPENBLAS_DLL)) {
  180. $OpenBlasDll = Get-Item $env:OPENBLAS_DLL
  181. } else {
  182. $OpenBlasDll = Get-ChildItem -Path $ReleaseDir -Recurse -Filter "openblas.dll" `
  183. -ErrorAction SilentlyContinue |
  184. Select-Object -First 1
  185. }
  186. if (-not $OpenBlasDll -and $env:OPENBLAS_DIR) {
  187. $alt = Join-Path $env:OPENBLAS_DIR "bin\openblas.dll"
  188. if (Test-Path $alt) { $OpenBlasDll = Get-Item $alt }
  189. }
  190. if ($OpenBlasDll) {
  191. Copy-Item $OpenBlasDll.FullName (Join-Path $Staging "openblas.dll") -Force
  192. Write-Host " [ok] openblas.dll (from $($OpenBlasDll.FullName))"
  193. } else {
  194. Write-Warning " openblas.dll not found — turboquant / rlx-cpu BLAS paths will fail at runtime"
  195. }
  196. # ── Bundle VC++ CRT DLLs (app-local deployment) ─────────────────────────
  197. # The binary uses dynamic CRT (/MD) because native deps (DirectML, ONNX
  198. # Runtime, Vulkan loader) ship as pre-built /MD DLLs. Bundling the CRT
  199. # DLLs alongside skill.exe means users don't need the VC++ Redistributable
  200. # pre-installed. Windows finds DLLs in the exe directory first (app-local).
  201. #
  202. # Required DLLs: vcruntime140.dll, vcruntime140_1.dll, msvcp140.dll,
  203. # msvcp140_1.dll, vcomp140.dll (OpenMP, used by llama.cpp)
  204. #
  205. # Source: CRT_REDIST_DIR env var (set by CI), or auto-detected via vswhere.
  206. $crtRedistDir = $env:CRT_REDIST_DIR
  207. if (-not $crtRedistDir -or -not (Test-Path $crtRedistDir)) {
  208. # Auto-detect from Visual Studio installation
  209. $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
  210. if (Test-Path $vswhere) {
  211. $vsPath = & $vswhere -latest -property installationPath 2>$null
  212. if ($vsPath) {
  213. $redistRoot = Join-Path $vsPath "VC\Redist\MSVC"
  214. if (Test-Path $redistRoot) {
  215. $crtRedistDir = Get-ChildItem $redistRoot -Directory |
  216. Sort-Object Name -Descending |
  217. ForEach-Object { Join-Path $_.FullName "x64\Microsoft.VC143.CRT" } |
  218. Where-Object { Test-Path $_ } |
  219. Select-Object -First 1
  220. if (-not $crtRedistDir) {
  221. # Fallback to VC142
  222. $crtRedistDir = Get-ChildItem $redistRoot -Directory |
  223. Sort-Object Name -Descending |
  224. ForEach-Object { Join-Path $_.FullName "x64\Microsoft.VC142.CRT" } |
  225. Where-Object { Test-Path $_ } |
  226. Select-Object -First 1
  227. }
  228. }
  229. }
  230. }
  231. }
  232. $crtDllNames = @(
  233. "vcruntime140.dll",
  234. "vcruntime140_1.dll",
  235. "msvcp140.dll",
  236. "msvcp140_1.dll",
  237. "vcomp140.dll"
  238. )
  239. # If no redist dir found yet, fall back to System32 (works if VC++ Redist
  240. # is installed system-wide, e.g. by the CI step or on developer machines).
  241. if (-not $crtRedistDir -or -not (Test-Path $crtRedistDir)) {
  242. $sys32 = "$env:SystemRoot\System32"
  243. $allInSys32 = $true
  244. foreach ($dllName in @("vcruntime140.dll", "msvcp140.dll")) {
  245. if (-not (Test-Path (Join-Path $sys32 $dllName))) { $allInSys32 = $false; break }
  246. }
  247. if ($allInSys32) {
  248. $crtRedistDir = $sys32
  249. Write-Host " [info] Using System32 as CRT source: $crtRedistDir"
  250. }
  251. }
  252. $bundledCrt = @()
  253. if ($crtRedistDir -and (Test-Path $crtRedistDir)) {
  254. foreach ($dllName in $crtDllNames) {
  255. $src = Join-Path $crtRedistDir $dllName
  256. if (Test-Path $src) {
  257. Copy-Item $src (Join-Path $Staging $dllName) -Force
  258. $bundledCrt += $dllName
  259. Write-Host " [ok] $dllName (from $crtRedistDir)"
  260. }
  261. }
  262. }
  263. if ($bundledCrt.Count -eq 0) {
  264. Write-Error @"
  265. VC++ CRT DLLs not found. The installer cannot be built without them.
  266. The binary uses dynamic CRT (/MD) and requires vcruntime140.dll etc.
  267. to be bundled alongside skill.exe for app-local deployment.
  268. Fix: ensure Visual Studio with the 'Desktop development with C++'
  269. workload is installed, or set `$env:CRT_REDIST_DIR to the directory
  270. containing the MSVC redistributable DLLs (e.g.
  271. C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Redist\MSVC\14.x.y\x64\Microsoft.VC143.CRT
  272. ).
  273. "@
  274. exit 1
  275. }
  276. # Verify all required DLLs were found
  277. $requiredCrt = @("vcruntime140.dll", "vcruntime140_1.dll", "msvcp140.dll", "msvcp140_1.dll")
  278. # Under strict mode, Where-Object may return $null (no misses) or a scalar
  279. # string (single miss). Force array semantics before reading .Count.
  280. $missingCrt = @($requiredCrt | Where-Object { $_ -notin $bundledCrt })
  281. if ($missingCrt.Count -gt 0) {
  282. Write-Error "Required CRT DLLs missing from bundle: $($missingCrt -join ', ')"
  283. Write-Host "Found: $($bundledCrt -join ', ')"
  284. Write-Host "CRT redist dir: $crtRedistDir"
  285. exit 1
  286. }
  287. Write-Host " [ok] Bundled $($bundledCrt.Count) CRT DLLs for app-local deployment"
  288. # Resources (espeak-ng-data, neutts-samples)
  289. $resources = $Conf.bundle.resources
  290. if ($resources) {
  291. foreach ($prop in $resources.PSObject.Properties) {
  292. $srcRel = $prop.Name
  293. $dstRel = $prop.Value
  294. $src = Join-Path $TauriDir $srcRel
  295. $dst = Join-Path $Staging $dstRel
  296. if (Test-Path $src) {
  297. if ((Get-Item $src).PSIsContainer) {
  298. Copy-Item $src $dst -Recurse -Force
  299. } else {
  300. New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
  301. Copy-Item $src $dst -Force
  302. }
  303. Write-Host " [ok] $dstRel"
  304. } else {
  305. Write-Warning " Missing resource: $srcRel"
  306. }
  307. }
  308. }
  309. # Docs
  310. foreach ($doc in @("README.md", "CHANGELOG.md", "LICENSE")) {
  311. $docPath = Join-Path $Root $doc
  312. if (Test-Path $docPath) {
  313. Copy-Item $docPath (Join-Path $Staging $doc)
  314. Write-Host " [ok] $doc"
  315. }
  316. }
  317. # ── Generate installer images ───────────────────────────────────────────
  318. # NSIS uses two bitmap images:
  319. # - Header image (150×57) — top-right of installer pages
  320. # - Welcome/Finish image (164×314) — left panel of welcome/finish pages
  321. $HeaderBmp = Join-Path $Staging "header.bmp"
  322. $WelcomeBmp = Join-Path $Staging "welcome.bmp"
  323. $IconPng = Join-Path $TauriDir "icons/icon.png"
  324. $imagesGenerated = $false
  325. if (Test-Path $IconPng) {
  326. try {
  327. python3 -c @"
  328. import sys
  329. from PIL import Image, ImageDraw, ImageFont
  330. icon_path = sys.argv[1]
  331. version = sys.argv[2]
  332. header_out = sys.argv[3]
  333. welcome_out = sys.argv[4]
  334. icon = Image.open(icon_path).convert('RGBA')
  335. # ── Header image (150x57) ──────────────────────────────────────────
  336. header = Image.new('RGB', (150, 57), (30, 30, 30))
  337. hi = icon.resize((45, 45), Image.LANCZOS)
  338. header.paste(hi, (8, 6), hi)
  339. draw_h = ImageDraw.Draw(header)
  340. font_h = None
  341. for fp in [
  342. 'C:/Windows/Fonts/segoeui.ttf',
  343. 'C:/Windows/Fonts/arial.ttf',
  344. ]:
  345. try:
  346. font_h = ImageFont.truetype(fp, 14)
  347. break
  348. except (OSError, IOError):
  349. continue
  350. if font_h is None:
  351. font_h = ImageFont.load_default()
  352. draw_h.text((60, 12), f'v{version}', fill=(200, 200, 200), font=font_h)
  353. header.save(header_out, 'BMP')
  354. # ── Welcome/Finish image (164x314) ─────────────────────────────────
  355. welcome = Image.new('RGB', (164, 314), (30, 30, 30))
  356. wi = icon.resize((100, 100), Image.LANCZOS)
  357. welcome.paste(wi, (32, 60), wi)
  358. draw_w = ImageDraw.Draw(welcome)
  359. font_w = None
  360. font_ws = None
  361. for fp in [
  362. 'C:/Windows/Fonts/segoeui.ttf',
  363. 'C:/Windows/Fonts/arial.ttf',
  364. ]:
  365. try:
  366. font_w = ImageFont.truetype(fp, 16)
  367. font_ws = ImageFont.truetype(fp, 12)
  368. break
  369. except (OSError, IOError):
  370. continue
  371. if font_w is None:
  372. font_w = ImageFont.load_default()
  373. font_ws = font_w
  374. vtxt = f'v{version}'
  375. vbox = draw_w.textbbox((0, 0), vtxt, font=font_w)
  376. vw = vbox[2] - vbox[0]
  377. draw_w.text(((164 - vw) // 2, 170), vtxt, fill=(200, 200, 200), font=font_w)
  378. welcome.save(welcome_out, 'BMP')
  379. print(' [ok] installer images generated')
  380. "@ -- $IconPng $Version $HeaderBmp $WelcomeBmp 2>&1
  381. if ($LASTEXITCODE -eq 0) {
  382. $imagesGenerated = $true
  383. }
  384. } catch {
  385. Write-Host " [skip] Could not generate installer images (Pillow not available?)"
  386. }
  387. }
  388. # ── Write NSIS script ───────────────────────────────────────────────────
  389. $InstallerExe = "NeuroSkill_${Version}_x64-setup.exe"
  390. $InstallerPath = Join-Path $NsisOutDir $InstallerExe
  391. $NsiScript = Join-Path $Staging "installer.nsi"
  392. # Build the file/directory install commands and uninstall commands
  393. $installFiles = @(' SetOutPath "$INSTDIR"')
  394. $installFiles += ' File "skill.exe"'
  395. if (Test-Path (Join-Path $Staging "skill-daemon.exe")) {
  396. $installFiles += ' File "skill-daemon.exe"'
  397. }
  398. if (Test-Path (Join-Path $Staging "icon.ico")) {
  399. $installFiles += ' File "icon.ico"'
  400. }
  401. foreach ($doc in @("README.md", "CHANGELOG.md", "LICENSE")) {
  402. if (Test-Path (Join-Path $Staging $doc)) {
  403. $installFiles += " File `"$doc`""
  404. }
  405. }
  406. # Bundle OpenBLAS DLL if present (rlx-cpu / turbovec runtime dependency)
  407. if (Test-Path (Join-Path $Staging "openblas.dll")) {
  408. $installFiles += ' File "openblas.dll"'
  409. }
  410. # Bundle VC++ CRT DLLs (app-local deployment)
  411. $crtDlls = Get-ChildItem $Staging -Filter "*.dll" |
  412. Where-Object { $_.Name -match "(?i)^(vcruntime|msvcp|concrt|vcomp)" }
  413. foreach ($dll in $crtDlls) {
  414. $installFiles += " File `"$($dll.Name)`""
  415. }
  416. $uninstallFiles = @()
  417. $uninstallFiles += ' Delete "$INSTDIR\skill.exe"'
  418. $uninstallFiles += ' Delete "$INSTDIR\skill-daemon.exe"'
  419. $uninstallFiles += ' Delete "$INSTDIR\icon.ico"'
  420. $uninstallFiles += ' Delete "$INSTDIR\openblas.dll"'
  421. foreach ($doc in @("README.md", "CHANGELOG.md", "LICENSE")) {
  422. $uninstallFiles += " Delete `"`$INSTDIR\$doc`""
  423. }
  424. # VC++ CRT DLLs (app-local deployment)
  425. foreach ($dll in $crtDlls) {
  426. $uninstallFiles += " Delete `"`$INSTDIR\$($dll.Name)`""
  427. }
  428. # Resource directories
  429. $resourceDirs = @()
  430. if ($resources) {
  431. foreach ($prop in $resources.PSObject.Properties) {
  432. $dstRel = $prop.Value
  433. $srcStaging = Join-Path $Staging $dstRel
  434. if (Test-Path $srcStaging) {
  435. $installFiles += " SetOutPath `"`$INSTDIR\$dstRel`""
  436. $installFiles += " File /r `"$dstRel\*.*`""
  437. $resourceDirs += $dstRel
  438. $uninstallFiles += " RMDir /r `"`$INSTDIR\$dstRel`""
  439. }
  440. }
  441. }
  442. # Header/welcome image directives
  443. $imageDirectives = ""
  444. if ($imagesGenerated) {
  445. $imageDirectives = @"
  446. !define MUI_HEADERIMAGE
  447. !define MUI_HEADERIMAGE_BITMAP "header.bmp"
  448. !define MUI_HEADERIMAGE_RIGHT
  449. !define MUI_WELCOMEFINISHPAGE_BITMAP "welcome.bmp"
  450. "@
  451. }
  452. $nsiContent = @"
  453. ; NeuroSkill NSIS Installer Script
  454. ; Generated by create-windows-nsis.ps1
  455. !include "MUI2.nsh"
  456. !include "FileFunc.nsh"
  457. !include "Sections.nsh"
  458. !include "nsDialogs.nsh"
  459. ; ── General ─────────────────────────────────────────────────────────────
  460. Name "$ProductName"
  461. OutFile "$InstallerPath"
  462. InstallDir "`$PROGRAMFILES64\$ProductName"
  463. InstallDirRegKey HKLM "Software\$ProductName" "InstallDir"
  464. RequestExecutionLevel admin
  465. Unicode True
  466. ; ── Branding ────────────────────────────────────────────────────────────
  467. !define MUI_ICON "icon.ico"
  468. !define MUI_UNICON "icon.ico"
  469. $imageDirectives
  470. !define MUI_ABORTWARNING
  471. ; ── Finish page: launch app after install ───────────────────────────────
  472. ; MUI_FINISHPAGE_RUN is intentionally left empty — we use a custom callback
  473. ; (un-elevated launch) instead. The installer runs as admin
  474. ; (RequestExecutionLevel admin), so a naive Exec/ExecShell would launch the
  475. ; app as Administrator. The MUI_FINISHPAGE_RUN_FUNCTION callback invokes
  476. ; explorer.exe to start the app in the real user's context (not elevated).
  477. !define MUI_FINISHPAGE_RUN
  478. !define MUI_FINISHPAGE_RUN_TEXT "Launch $ProductDisplayName"
  479. !define MUI_FINISHPAGE_RUN_FUNCTION LaunchAsCurrentUser
  480. ; ── Pages ───────────────────────────────────────────────────────────────
  481. !insertmacro MUI_PAGE_WELCOME
  482. !insertmacro MUI_PAGE_LICENSE "LICENSE"
  483. !insertmacro MUI_PAGE_COMPONENTS
  484. !insertmacro MUI_PAGE_DIRECTORY
  485. !insertmacro MUI_PAGE_INSTFILES
  486. !insertmacro MUI_PAGE_FINISH
  487. !insertmacro MUI_UNPAGE_CONFIRM
  488. !insertmacro MUI_UNPAGE_INSTFILES
  489. !insertmacro MUI_LANGUAGE "English"
  490. ; ── Version info ────────────────────────────────────────────────────────
  491. VIProductVersion "$VIVersion"
  492. VIAddVersionKey "ProductName" "$ProductDisplayName"
  493. VIAddVersionKey "ProductVersion" "$Version"
  494. VIAddVersionKey "FileVersion" "$Version"
  495. VIAddVersionKey "LegalCopyright" "GPL-3.0-only"
  496. VIAddVersionKey "FileDescription" "$ProductDisplayName Installer"
  497. ; ── Launch helper (drop admin elevation) ────────────────────────────────
  498. ; The installer runs elevated (admin). Launching the app directly with
  499. ; Exec/ExecShell would run it as Administrator, which breaks per-user
  500. ; paths, tray registration, and autostart.
  501. ;
  502. ; The reliable no-plugin approach: use the Windows "runas" trick in
  503. ; reverse — ask Explorer (running as the real user) to open the exe.
  504. ; We do this by invoking explorer.exe with the full exe path, which
  505. ; causes Explorer to ShellExecute it in the user's own session context.
  506. Function LaunchAsCurrentUser
  507. Exec '"`$WINDIR\explorer.exe" "`$INSTDIR\skill.exe"'
  508. FunctionEnd
  509. ; ── Kill running instance before install ─────────────────────────────────
  510. ; If the app is already running, the installer cannot replace skill.exe.
  511. ; Gracefully ask the user, then force-kill if needed.
  512. Function KillRunningInstance
  513. FindWindow `$0 "" "$ProductDisplayName"
  514. IntCmp `$0 0 not_running
  515. ; App window found — ask user
  516. MessageBox MB_OKCANCEL|MB_ICONINFORMATION "$ProductDisplayName is currently running and must be closed before installing.$\n$\nClick OK to close it automatically, or Cancel to abort." IDOK kill_it
  517. Abort
  518. kill_it:
  519. ; Try graceful WM_CLOSE first
  520. SendMessage `$0 `${WM_CLOSE} 0 0
  521. Sleep 2000
  522. ; Force-kill if still running
  523. nsExec::ExecToLog 'taskkill /F /IM skill.exe'
  524. nsExec::ExecToLog 'taskkill /F /IM skill-daemon.exe'
  525. Sleep 500
  526. not_running:
  527. FunctionEnd
  528. ; ── Install section ─────────────────────────────────────────────────────
  529. Section "$ProductName (required)" SEC_MAIN
  530. SectionIn RO ; required — cannot be unchecked
  531. ; Kill any running instance before overwriting files
  532. Call KillRunningInstance
  533. $($installFiles -join "`n")
  534. ; Uninstaller
  535. SetOutPath "`$INSTDIR"
  536. WriteUninstaller "`$INSTDIR\uninstall.exe"
  537. ; Start Menu shortcut
  538. CreateDirectory "`$SMPROGRAMS\$ProductName"
  539. CreateShortCut "`$SMPROGRAMS\$ProductName\$ProductName.lnk" "`$INSTDIR\skill.exe" "" "`$INSTDIR\icon.ico"
  540. CreateShortCut "`$SMPROGRAMS\$ProductName\Uninstall.lnk" "`$INSTDIR\uninstall.exe"
  541. ; Desktop shortcut
  542. CreateShortCut "`$DESKTOP\$ProductName.lnk" "`$INSTDIR\skill.exe" "" "`$INSTDIR\icon.ico"
  543. ; Registry (Add/Remove Programs)
  544. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "DisplayName" "$ProductDisplayName"
  545. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "DisplayVersion" "$Version"
  546. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "UninstallString" "`$INSTDIR\uninstall.exe"
  547. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "DisplayIcon" "`$INSTDIR\icon.ico"
  548. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "Publisher" "NeuroSkill"
  549. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "InstallLocation" "`$INSTDIR"
  550. WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "NoModify" 1
  551. WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "NoRepair" 1
  552. ; Estimated size
  553. `${GetSize} "`$INSTDIR" "/S=0K" `$0 `$1 `$2
  554. IntFmt `$0 "0x%08X" `$0
  555. WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName" "EstimatedSize" `$0
  556. WriteRegStr HKLM "Software\$ProductName" "InstallDir" "`$INSTDIR"
  557. ; ── Enable Win32 long paths ──────────────────────────────────────────────
  558. ; HuggingFace model cache paths can exceed the 260-char MAX_PATH limit.
  559. ; This registry key (available since Windows 10 1607) lifts the restriction
  560. ; for long-path-aware applications. Requires a reboot to take effect, but
  561. ; the installer does not force one — it takes effect on next login.
  562. WriteRegDWORD HKLM "SYSTEM\CurrentControlSet\Control\FileSystem" "LongPathsEnabled" 1
  563. ; ── Windows Firewall rule for the local LLM/WebSocket server ───────────
  564. ; The app listens on localhost for LLM inference and WebSocket commands.
  565. ; Pre-adding a firewall rule prevents the "allow access?" popup on first
  566. ; launch. Failure is non-fatal (user can allow manually).
  567. nsExec::ExecToLog 'netsh advfirewall firewall delete rule name="$ProductName"'
  568. nsExec::ExecToLog 'netsh advfirewall firewall add rule name="$ProductName" dir=in action=allow program="`$INSTDIR\skill.exe" enable=yes profile=private,public'
  569. nsExec::ExecToLog 'netsh advfirewall firewall delete rule name="$ProductName Daemon"'
  570. nsExec::ExecToLog 'netsh advfirewall firewall add rule name="$ProductName Daemon" dir=in action=allow program="`$INSTDIR\skill-daemon.exe" enable=yes profile=private,public'
  571. SectionEnd
  572. ; ── Vulkan Runtime section (optional, auto-selected when missing) ───────
  573. ; GPU-accelerated LLM inference requires the Vulkan loader (vulkan-1.dll).
  574. ; Most Windows 10/11 PCs with discrete GPUs already have it. If it is
  575. ; missing, this section downloads and silently installs the LunarG Vulkan
  576. ; Runtime, which is ~3 MB and redistributable.
  577. Section /o "Install Vulkan Runtime (GPU acceleration)" SEC_VULKAN
  578. ; Temporary download path
  579. StrCpy `$0 "`$TEMP\VulkanRT-Installer.exe"
  580. ; Download the latest Vulkan Runtime installer from LunarG
  581. DetailPrint "Downloading Vulkan Runtime..."
  582. NSISdl::download "https://sdk.lunarg.com/sdk/download/latest/windows/vulkan-runtime.exe" `$0
    • Note: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 659 on GitHub
  583. Pop `$1
  584. StrCmp `$1 "success" +3
  585. DetailPrint "Vulkan Runtime download failed (`$1). GPU acceleration may not work."
  586. Goto vulkan_done
  587. ; Silent install (/S = silent mode for the NSIS-based LunarG installer)
  588. DetailPrint "Installing Vulkan Runtime..."
  589. nsExec::ExecToLog '"`$0" /S'
  590. Pop `$1
  591. ; Non-zero exit is non-fatal — the app still works (falls back to CPU)
  592. IntCmp `$1 0 +2
  593. DetailPrint "Vulkan Runtime installer exited with code `$1 (non-fatal)."
  594. Delete `$0
  595. vulkan_done:
  596. SectionEnd
  597. ; ── VC++ Redistributable section (on by default) ───────────────────────
  598. ; The binary uses dynamic CRT (/MD) and requires vcruntime140.dll /
  599. ; msvcp140.dll. CRT DLLs are bundled app-locally in `$INSTDIR, but the
  600. ; full VC++ Redistributable is also installed as a system-wide fallback.
  601. ; The official Microsoft installer is ~25 MB and is a no-op if already
  602. ; present — it silently exits with code 0 or 1638 (already installed).
  603. Section "Install VC++ Redistributable" SEC_VCREDIST
  604. StrCpy `$0 "`$TEMP\vc_redist.x64.exe"
  605. DetailPrint "Downloading Visual C++ Redistributable..."
  606. NSISdl::download "https://aka.ms/vs/17/release/vc_redist.x64.exe" `$0
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 688 on GitHub
  607. Pop `$1
  608. StrCmp `$1 "success" +3
  609. DetailPrint "VC++ Redistributable download failed (`$1). Some features may not work."
  610. Goto vcredist_done
  611. ; /install /quiet /norestart — standard silent switches for the VC++ installer.
  612. ; Exit code 0 = success, 1638 = already installed (both are fine).
  613. DetailPrint "Installing Visual C++ Redistributable..."
  614. nsExec::ExecToLog '"`$0" /install /quiet /norestart'
  615. Pop `$1
  616. IntCmp `$1 0 vcredist_ok
  617. IntCmp `$1 1638 vcredist_ok
  618. DetailPrint "VC++ Redistributable installer exited with code `$1 (non-fatal)."
  619. Goto vcredist_cleanup
  620. vcredist_ok:
  621. DetailPrint "Visual C++ Redistributable installed successfully."
  622. vcredist_cleanup:
  623. Delete `$0
  624. vcredist_done:
  625. SectionEnd
  626. ; ── WebView2 Runtime section (optional, auto-selected when missing) ─────
  627. ; Tauri 2 requires the Microsoft Edge WebView2 Runtime to render the app
  628. ; UI. It is built into Windows 11 but may be absent on older Windows 10
  629. ; machines. The Evergreen Bootstrapper is ~1.8 MB and installs silently.
  630. Section /o "Install WebView2 Runtime (required for UI)" SEC_WEBVIEW2
  631. StrCpy `$0 "`$TEMP\MicrosoftEdgeWebview2Setup.exe"
  632. DetailPrint "Downloading WebView2 Runtime..."
  633. NSISdl::download "https://go.microsoft.com/fwlink/p/?LinkId=2124703" `$0
  634. Pop `$1
  635. StrCmp `$1 "success" +3
  636. DetailPrint "WebView2 download failed (`$1). The app may not display correctly."
  637. Goto webview2_done
  638. ; /silent /install — standard quiet switches for the Evergreen Bootstrapper.
  639. DetailPrint "Installing WebView2 Runtime..."
  640. nsExec::ExecToLog '"`$0" /silent /install'
  641. Pop `$1
  642. IntCmp `$1 0 webview2_ok
  643. DetailPrint "WebView2 installer exited with code `$1 (may already be installed)."
  644. Goto webview2_cleanup
  645. webview2_ok:
  646. DetailPrint "WebView2 Runtime installed successfully."
  647. webview2_cleanup:
  648. Delete `$0
  649. webview2_done:
  650. SectionEnd
  651. ; ── GPU TDR timeout section (optional) ──────────────────────────────────
  652. ; Windows kills GPU compute shaders after 2 seconds by default (Timeout
  653. ; Detection and Recovery). LLM inference on GPU can exceed this, causing
  654. ; the driver to reset and the inference to fail. Increasing TdrDelay to
  655. ; 60 seconds prevents this. Requires a reboot to take effect.
  656. ; See: https://learn.microsoft.com/en-us/windows-hardware/drivers/display/tdr-registry-keys
  657. Section /o "Increase GPU timeout for LLM inference" SEC_TDR
  658. WriteRegDWORD HKLM "SYSTEM\CurrentControlSet\Control\GraphicsDrivers" "TdrDelay" 60
  659. DetailPrint "GPU TDR timeout set to 60 seconds (reboot required to take effect)."
  660. SectionEnd
  661. ; ── Launch at login section (on by default) ─────────────────────────────
  662. ; Registers the app in HKCU\...\Run so it starts automatically on login.
  663. ; The user can also toggle this later from Settings inside the app.
  664. ; Uses the same registry key that the in-app autostart crate writes.
  665. Section "Launch at login" SEC_AUTOSTART
  666. WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Run" "skill" '"`$INSTDIR\skill.exe"'
  667. DetailPrint "Autostart enabled (HKCU\Software\Microsoft\Windows\CurrentVersion\Run\skill)."
  668. SectionEnd
  669. ; ── Component descriptions ──────────────────────────────────────────────
  670. !insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
  671. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_MAIN} "Install $ProductDisplayName application files."
  672. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_VULKAN} "Download and install the Vulkan Runtime for GPU-accelerated LLM inference. Not needed if your GPU driver already provides Vulkan support."
  673. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_VCREDIST} "Download and install the Microsoft Visual C++ 2015-2022 Redistributable (x64). Required for the application to run. CRT DLLs are also bundled locally, but the system-wide install ensures long-term compatibility. Safe to install even if already present."
  674. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_WEBVIEW2} "Download and install the Microsoft Edge WebView2 Runtime. Required to display the application interface. Already included in Windows 11."
  675. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_TDR} "Increase the Windows GPU timeout from 2 to 60 seconds. Prevents GPU driver resets during long LLM inference runs. Requires a reboot."
  676. !insertmacro MUI_DESCRIPTION_TEXT `${SEC_AUTOSTART} "Start $ProductDisplayName automatically when you log in to Windows. You can change this later in the app settings."
  677. !insertmacro MUI_FUNCTION_DESCRIPTION_END
  678. ; ── Auto-select optional sections when prerequisites are missing ────────
  679. Function .onInit
  680. ; Vulkan Runtime
  681. IfFileExists "`$SYSDIR\vulkan-1.dll" vulkan_found vulkan_missing
  682. vulkan_missing:
  683. !insertmacro SelectSection `${SEC_VULKAN}
  684. Goto vulkan_check_done
  685. vulkan_found:
  686. vulkan_check_done:
  687. ; VC++ Redistributable — always on by default (Section without /o).
  688. ; No auto-select logic needed since the section is already enabled.
  689. ; WebView2 — check registry for installed WebView2 Runtime
  690. ; The Evergreen Runtime writes to this key on both per-user and per-machine installs.
  691. ReadRegStr `$0 HKLM "SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
  692. StrCmp `$0 "" 0 webview2_reg_found
  693. ReadRegStr `$0 HKCU "SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
  694. StrCmp `$0 "" 0 webview2_reg_found
  695. ; Not found — select the WebView2 section
  696. !insertmacro SelectSection `${SEC_WEBVIEW2}
  697. Goto webview2_check_done
  698. webview2_reg_found:
  699. webview2_check_done:
  700. FunctionEnd
  701. ; ── Uninstall: kill running instance ─────────────────────────────────────
  702. Function un.KillRunningInstance
  703. nsExec::ExecToLog 'taskkill /F /IM skill.exe'
  704. nsExec::ExecToLog 'taskkill /F /IM skill-daemon.exe'
  705. ; Remove the daemon Windows service if it was registered at runtime
  706. nsExec::ExecToLog 'sc.exe stop com.skill.daemon'
  707. nsExec::ExecToLog 'sc.exe delete com.skill.daemon'
  708. Sleep 500
  709. FunctionEnd
  710. ; ── Uninstall section ───────────────────────────────────────────────────
  711. Section "Uninstall"
  712. ; Kill the app if it is still running
  713. Call un.KillRunningInstance
  714. $($uninstallFiles -join "`n")
  715. Delete "`$INSTDIR\uninstall.exe"
  716. ; Shortcuts
  717. Delete "`$SMPROGRAMS\$ProductName\$ProductName.lnk"
  718. Delete "`$SMPROGRAMS\$ProductName\Uninstall.lnk"
  719. RMDir "`$SMPROGRAMS\$ProductName"
  720. Delete "`$DESKTOP\$ProductName.lnk"
  721. ; Firewall rules
  722. nsExec::ExecToLog 'netsh advfirewall firewall delete rule name="$ProductName"'
  723. nsExec::ExecToLog 'netsh advfirewall firewall delete rule name="$ProductName Daemon"'
  724. ; Autostart registry entry (the app registers as "skill" in HKCU\...\Run)
  725. DeleteRegValue HKCU "Software\Microsoft\Windows\CurrentVersion\Run" "skill"
  726. ; Registry
  727. DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\$ProductName"
  728. DeleteRegKey HKLM "Software\$ProductName"
  729. ; Remove install directory (only if empty after file deletions)
  730. RMDir "`$INSTDIR"
  731. ; ── Offer to remove user data ────────────────────────────────────────
  732. ; %LOCALAPPDATA%\NeuroSkill contains settings, sessions, databases, and
  733. ; downloaded models. Ask the user whether to keep or delete it.
  734. IfFileExists "`$LOCALAPPDATA\NeuroSkill\*.*" 0 skip_data_prompt
  735. MessageBox MB_YESNO|MB_ICONQUESTION "Do you want to remove your $ProductDisplayName data folder?$\n$\n`$LOCALAPPDATA\NeuroSkill$\n$\nThis includes settings, session recordings, and downloaded AI models. Choose No to keep your data for a future reinstall." IDYES remove_data
  736. Goto skip_data_prompt
  737. remove_data:
  738. RMDir /r "`$LOCALAPPDATA\NeuroSkill"
  739. skip_data_prompt:
  740. SectionEnd
  741. "@
  742. # NSIS with `Unicode True` requires a BOM to detect UTF-8 encoding.
  743. # Without BOM it falls back to the system ANSI codepage and mangles
  744. # non-ASCII characters like ™ in the product display name.
  745. $utf8WithBom = New-Object System.Text.UTF8Encoding($true)
  746. [System.IO.File]::WriteAllText($NsiScript, $nsiContent, $utf8WithBom)
  747. Write-Host " [ok] NSIS script written (UTF-8 with BOM)"
  748. # ── Run NSIS ────────────────────────────────────────────────────────────
  749. Write-Host " Compiling installer ..."
  750. & $MakeNsis /V2 $NsiScript
  751. if ($LASTEXITCODE -ne 0) {
  752. Write-Error "makensis failed with exit code $LASTEXITCODE"
  753. exit $LASTEXITCODE
  754. }
  755. Write-Host " [ok] $InstallerExe"
  756. # ── Sign installer (optional) ───────────────────────────────────────────
  757. if ($Sign) {
  758. $thumbprint = $env:CERTIFICATE_THUMBPRINT
  759. if (-not $thumbprint) {
  760. Write-Warning " -Sign requested but `$env:CERTIFICATE_THUMBPRINT is not set. Skipping."
  761. } else {
  762. Write-Host " Signing installer ..."
  763. & signtool sign `
  764. /sha1 $thumbprint `
  765. /fd sha256 `
  766. /tr http://timestamp.digicert.com `
  767. /td sha256 `
  768. /v `
  769. $InstallerPath
  770. if ($LASTEXITCODE -ne 0) {
  771. Write-Error "signtool failed with exit code $LASTEXITCODE"
  772. exit $LASTEXITCODE
  773. }
  774. Write-Host " [ok] Installer signed"
  775. }
  776. }
  777. # ── Summary ─────────────────────────────────────────────────────────────
  778. $size = "{0:N1} MB" -f ((Get-Item $InstallerPath).Length / 1MB)
  779. Write-Host ""
  780. Write-Host "[ok] $InstallerPath ($size)"
  781. Write-Host ""
  782. Write-Host "Contents:"
  783. Write-Host " - $BinaryName"
  784. Write-Host " - icon.ico"
  785. foreach ($dll in $bundledCrt) {
  786. Write-Host " - $dll (CRT app-local)"
  787. }
  788. foreach ($doc in @("README.md", "CHANGELOG.md", "LICENSE")) {
  789. if (Test-Path (Join-Path $Staging $doc)) {
  790. Write-Host " - $doc"
  791. }
  792. }
  793. if ($resources) {
  794. foreach ($prop in $resources.PSObject.Properties) {
  795. Write-Host " - $($prop.Value)/"
  796. }
  797. }
  798. Write-Host ""
  799. Write-Host "To install: run $InstallerExe"
  800. } finally {
  801. # Clean up staging directory
  802. if (Test-Path $Staging) {
  803. Remove-Item $Staging -Recurse -Force -ErrorAction SilentlyContinue
  804. }
  805. }
scripts/ensure-vcredist.ps1 · Bundled script · 150 lines · 1 finding marked
  1. <#
  2. .SYNOPSIS
  3. Ensure VC++ Redistributable CRT DLLs are available for app-local bundling.
  4. .DESCRIPTION
  5. Locates the MSVC CRT redistributable DLLs (vcruntime140.dll, msvcp140.dll,
  6. etc.) needed for app-local deployment.
  7. Strategy order:
  8. 1. VCToolsRedistDir env var (set by ilammy/msvc-dev-cmd on CI)
  9. 2. vswhere to find VS install path
  10. 3. Download + install VC++ Redistributable from Microsoft, copy from System32
  11. On success, sets CRT_REDIST_DIR via GITHUB_ENV (CI) or process env.
  12. #>
  13. Set-StrictMode -Version Latest
  14. $ErrorActionPreference = "Stop"
  15. $required = @(
  16. "vcruntime140.dll",
  17. "vcruntime140_1.dll",
  18. "msvcp140.dll",
  19. "msvcp140_1.dll",
  20. "vcomp140.dll"
  21. )
  22. function Test-AllDlls($dir) {
  23. foreach ($dll in $required) {
  24. if (-not (Test-Path (Join-Path $dir $dll))) { return $false }
  25. }
  26. return $true
  27. }
  28. function Find-CrtInRedistRoot($redistRoot) {
  29. if (-not $redistRoot -or -not (Test-Path $redistRoot)) { return $null }
  30. foreach ($vcVer in @("VC143", "VC142")) {
  31. $dirs = Get-ChildItem $redistRoot -Directory -ErrorAction SilentlyContinue |
  32. Sort-Object Name -Descending
  33. foreach ($d in $dirs) {
  34. $candidate = Join-Path $d.FullName "x64\Microsoft.$vcVer.CRT"
  35. if (Test-Path $candidate) { return $candidate }
  36. }
  37. }
  38. return $null
  39. }
  40. $crtDir = $null
  41. # ── Strategy 1: VCToolsRedistDir (set by ilammy/msvc-dev-cmd) ───────────────
  42. if ($env:VCToolsRedistDir) {
  43. Write-Host "[info] VCToolsRedistDir = $env:VCToolsRedistDir"
  44. $crtDir = Find-CrtInRedistRoot $env:VCToolsRedistDir
  45. if (-not $crtDir) {
  46. # VCToolsRedistDir itself may be the parent — try going up
  47. $parent = Split-Path $env:VCToolsRedistDir -Parent
  48. $crtDir = Find-CrtInRedistRoot $parent
  49. }
  50. if ($crtDir -and (Test-AllDlls $crtDir)) {
  51. Write-Host "[ok] CRT DLLs found via VCToolsRedistDir: $crtDir"
  52. }
  53. else {
  54. Write-Host "[warn] VCToolsRedistDir set but DLLs not found there"
  55. $crtDir = $null
  56. }
  57. }
  58. # ── Strategy 2: vswhere ──────────────────────────────────────────────────────
  59. if (-not $crtDir) {
  60. $pf86 = [Environment]::GetFolderPath("ProgramFilesX86")
  61. if (-not $pf86) { $pf86 = "C:\Program Files (x86)" }
  62. $vswhere = Join-Path $pf86 "Microsoft Visual Studio\Installer\vswhere.exe"
  63. if (Test-Path $vswhere) {
  64. $vsPath = & $vswhere -latest -property installationPath 2>$null
  65. if ($vsPath) {
  66. $redistRoot = Join-Path $vsPath "VC\Redist\MSVC"
  67. $crtDir = Find-CrtInRedistRoot $redistRoot
  68. if ($crtDir -and (Test-AllDlls $crtDir)) {
  69. Write-Host "[ok] CRT DLLs found via vswhere: $crtDir"
  70. }
  71. else {
  72. $crtDir = $null
  73. }
  74. }
  75. }
  76. }
  77. # ── Strategy 3: Download + install VC++ Redistributable ──────────────────────
  78. if (-not $crtDir) {
  79. Write-Host "[info] Downloading VC++ Redistributable from Microsoft..."
  80. $tempDir = if ($env:RUNNER_TEMP) { $env:RUNNER_TEMP } else { $env:TEMP }
  81. $vcRedistExe = Join-Path $tempDir "vc_redist.x64.exe"
  82. Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vc_redist.x64.exe" `
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 96 on GitHub
  83. -OutFile $vcRedistExe -UseBasicParsing
  84. if (-not (Test-Path $vcRedistExe)) {
  85. Write-Error "Failed to download VC++ Redistributable"
  86. exit 1
  87. }
  88. $sizeMB = [math]::Round((Get-Item $vcRedistExe).Length / 1MB, 1)
  89. Write-Host "[ok] Downloaded ($sizeMB MB)"
  90. Write-Host "[info] Installing VC++ Redistributable..."
  91. $proc = Start-Process -FilePath $vcRedistExe `
  92. -ArgumentList "/install", "/quiet", "/norestart" `
  93. -Wait -PassThru
  94. $exitCode = $proc.ExitCode
  95. if ($exitCode -ne 0 -and $exitCode -ne 1638) {
  96. Write-Error "VC++ Redistributable install failed (exit $exitCode)"
  97. exit 1
  98. }
  99. Write-Host "[ok] VC++ Redistributable installed (exit $exitCode)"
  100. Remove-Item $vcRedistExe -Force -ErrorAction SilentlyContinue
  101. $crtDir = Join-Path $env:SystemRoot "System32"
  102. }
  103. # ── Final verification ───────────────────────────────────────────────────────
  104. $missing = @()
  105. foreach ($dll in $required) {
  106. if (-not (Test-Path (Join-Path $crtDir $dll))) {
  107. $missing += $dll
  108. }
  109. }
  110. if ($missing.Count -gt 0) {
  111. $missingList = $missing -join ", "
  112. Write-Error "CRT DLLs still missing after all strategies: $missingList"
  113. exit 1
  114. }
  115. Write-Host "[ok] All $($required.Count) CRT DLLs verified:"
  116. foreach ($dll in $required) {
  117. Write-Host " $(Join-Path $crtDir $dll)"
  118. }
  119. # ── Export CRT_REDIST_DIR ────────────────────────────────────────────────────
  120. $env:CRT_REDIST_DIR = $crtDir
  121. if ($env:GITHUB_ENV) {
  122. "CRT_REDIST_DIR=$crtDir" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
  123. }
  124. Write-Host "[ok] CRT_REDIST_DIR=$crtDir"
src/lib/chat/chat-utils.ts · Bundled script · 290 lines · 1 finding marked
  1. // SPDX-License-Identifier: GPL-3.0-only
  2. // Copyright (C) 2026 NeuroSkill.com
  3. /**
  4. * Pure utility functions for the chat page — tool-call parsing,
  5. * danger detection, and assistant output parsing.
  6. *
  7. * Extracted from `routes/chat/+page.svelte` to reduce file size and
  8. * allow independent unit testing.
  9. */
  10. import type { TranslationKey } from "#lib/i18n/keys";
  11. // ── Generation-phase progress labels ────────────────────────────────────────
  12. /** Backend generation-phase identifiers, delivered on `status` chunks during
  13. * the pre-token lead-in (see `ChatChunkStatus`). Kept here so the string
  14. * literals live in exactly one place on the frontend. */
  15. export const GEN_PHASE = {
  16. vision: "vision",
  17. prefill: "prefill",
  18. /** A built-in tool is executing (web_search, location, …). These can take
  19. * tens of seconds, and before they were reported the client simply went
  20. * quiet for the whole round-trip. */
  21. tool: "tool",
  22. } as const;
  23. /** i18n key for the pre-token "processing" indicator: the real backend phase
  24. * when known ("vision" → reading image, "prefill" → preparing response),
  25. * otherwise the image/text fallback. */
  26. export function processingLabelKey(phase: string | undefined, hasImage: boolean | undefined): TranslationKey {
  27. switch (phase) {
  28. case GEN_PHASE.vision:
  29. return "chat.phaseVision";
  30. case GEN_PHASE.prefill:
  31. return "chat.phasePrefill";
  32. case GEN_PHASE.tool:
  33. return "chat.phaseTool";
  34. default:
  35. return hasImage ? "chat.analyzingImage" : "chat.processing";
  36. }
  37. }
  38. // ── Tool-call stripping ─────────────────────────────────────────────────────
  39. /** Known built-in tool names — must stay in sync with KNOWN_TOOL_NAMES in tools.rs */
  40. const KNOWN_TOOLS = new Set([
  41. "date",
  42. "location",
  43. "web_search",
  44. "web_fetch",
  45. "bash",
  46. "read_file",
  47. "write_file",
  48. "edit_file",
  49. "search_output",
  50. ]);
  51. function isToolCallObject(v: Record<string, unknown>): boolean {
  52. if (("name" in v || "tool" in v || "tool_calls" in v) && ("parameters" in v || "arguments" in v || "tool_calls" in v))
  53. return true;
  54. const keys = Object.keys(v);
  55. return (
  56. keys.length > 0 &&
  57. keys.some((k) => KNOWN_TOOLS.has(k)) &&
  58. Object.values(v).every((val) => typeof val === "object" && val !== null)
  59. );
  60. }
  61. function looksLikeToolCallJsonPrefix(s: string): boolean {
  62. const trimmed = s.trimStart();
  63. if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
  64. const probe = trimmed.slice(0, 320).toLowerCase();
  65. const isDictStyle = [...KNOWN_TOOLS].some((name) => probe.includes(`"${name}":`) || probe.includes(`"${name}": `));
  66. if (isDictStyle) return true;
  67. const mentionsToolName =
  68. probe.includes('"name"') ||
  69. probe.includes('"tool"') ||
  70. probe.includes('"tool_calls"') ||
  71. probe.includes('"function"');
  72. const mentionsArgs = probe.includes('"parameter') || probe.includes('"argument') || probe.includes("<think>");
  73. return mentionsToolName && mentionsArgs;
  74. }
  75. function isToolCallArray(v: unknown): boolean {
  76. if (!Array.isArray(v)) return false;
  77. return v.some(
  78. (item) =>
  79. typeof item === "object" &&
  80. item !== null &&
  81. !Array.isArray(item) &&
  82. isToolCallObject(item as Record<string, unknown>),
  83. );
  84. }
  85. /**
  86. * Strip tool-call JSON code fences that leaked into rawAcc.
  87. *
  88. * The streaming sanitizer on the Rust side holds back tool-call JSON, but
  89. * it can only recognise a fence as a tool call once it has seen BOTH a
  90. * "tool"/"name" key AND a "parameters"/"arguments" key. Tokens emitted
  91. * before that threshold are already in rawAcc and need to be cleaned here.
  92. */
  93. export function stripToolCallFences(raw: string): string {
  94. // 1. Complete fenced blocks
  95. let s = raw.replace(/```(?:json)?\n([\s\S]*?)\n?```/g, (match, body: string) => {
  96. const trimmedBody = body.trim();
  97. try {
  98. const v = JSON.parse(trimmedBody);
  99. if (typeof v === "object" && v !== null && !Array.isArray(v) && isToolCallObject(v)) return "";
  100. if (isToolCallArray(v)) return "";
  101. } catch {
  102. /* not JSON — keep */
  103. }
  104. if (looksLikeToolCallJsonPrefix(trimmedBody)) return "";
  105. return match;
  106. });
  107. // 2a. Incomplete fence immediately before a <think> tag.
  108. s = s.replace(/```(?:json)?\n([\s\S]*?)(?=\n*<think>)/g, (match, body: string) =>
  109. looksLikeToolCallJsonPrefix(body) ? "" : match,
  110. );
  111. // 2b. Incomplete fence at end of string (still streaming).
  112. s = s.replace(/```(?:json)?\n([\s\S]*)$/g, (match, body: string) => (looksLikeToolCallJsonPrefix(body) ? "" : match));
  113. // 3. Bare inline tool-call JSON (not fenced)
  114. s = s.replace(/(?:^|\n)\s*[[{][\s\S]*$/gm, (match) => {
  115. if (looksLikeToolCallJsonPrefix(match.trim())) return "";
  116. return match;
  117. });
  118. // 4. Complete [TOOL_CALL]…[/TOOL_CALL] blocks
  119. s = s.replace(/\[TOOL_CALL\][\s\S]*?\[\/TOOL_CALL\]/g, "");
  120. // 5. Incomplete [TOOL_CALL] at end of string (mid-stream)
  121. s = s.replace(/\[TOOL_C[\s\S]*$/g, "");
  122. return s;
  123. }
  124. // ── Lead-in cleaning ────────────────────────────────────────────────────────
  125. export function cleanAssistantLeadIn(raw: string): string {
  126. return raw
  127. .replace(/```[a-z]*\s*/gi, "")
  128. .split("\n")
  129. .filter((line) => !/^\s*(json|copy)\s*$/i.test(line))
  130. .join("\n")
  131. .trim();
  132. }
  133. /**
  134. * Clean lead-in text for display. When tool calls are active, aggressively
  135. * strip ALL incomplete code fences and any JSON-like fragments.
  136. */
  137. export function cleanLeadInForDisplay(raw: string, hasToolUses: boolean): string {
  138. if (!raw.trim()) return "";
  139. let s = stripToolCallFences(raw);
  140. if (hasToolUses) {
  141. s = s.replace(/```[a-z]*\n[\s\S]*$/gi, "");
  142. s = s.replace(/\n\s*[[{][\s\S]*$/g, "");
  143. }
  144. return s.trim();
  145. }
  146. // ── Danger detection ────────────────────────────────────────────────────────
  147. /** Bash patterns that indicate a potentially dangerous command (mirrored from Rust). */
  148. const DANGEROUS_BASH_PATTERNS = [
  149. "rm ",
  150. "rm\t",
  151. "rmdir",
  152. "shred",
  153. "mkfs",
  154. "dd if=",
  155. "dd of=",
  156. "sudo ",
  157. "su -",
  158. "su\t",
  159. "> /dev/",
  160. "chmod",
  161. "chown",
  162. "kill ",
  163. "killall",
  164. "pkill",
  165. "shutdown",
  166. "reboot",
  167. "halt",
  168. "poweroff",
  169. "systemctl stop",
  170. "systemctl disable",
  171. ":(){ :|:& };:",
  172. "/etc/",
  173. "/boot/",
  174. "/usr/",
  175. "/var/",
  176. "/sys/",
  177. "/proc/",
  178. ];
  179. /** Sensitive path prefixes (mirrored from Rust). */
  180. const SENSITIVE_PATH_PREFIXES = [
  181. "/etc/",
  182. "/boot/",
  183. "/usr/",
  184. "/var/",
  185. "/sys/",
  186. "/proc/",
  187. "/bin/",
  188. "/sbin/",
  189. "/lib/",
  190. "/opt/",
  191. ];
  192. /**
  193. * Check if a tool call looks dangerous based on its name and arguments.
  194. * Returns a danger reason i18n key, or null if safe.
  195. *
  196. * Accepts any object with `tool` and optional `args` fields.
  197. */
  198. export function detectToolDanger(tu: { tool: string; args?: Record<string, unknown> }): string | null {
  199. if (tu.tool === "bash" && typeof tu.args?.command === "string") {
  200. const cmd = tu.args.command.toLowerCase();
  201. for (const pat of DANGEROUS_BASH_PATTERNS) {
  202. if (cmd.includes(pat)) {
  203. return `chat.tools.dangerBash`;
  204. }
  205. }
  206. }
  207. if (["write_file", "edit_file", "read_file"].includes(tu.tool) && typeof tu.args?.path === "string") {
  208. const path = tu.args.path;
  209. for (const prefix of SENSITIVE_PATH_PREFIXES) {
  210. if (path.startsWith(prefix)) {
  211. return `chat.tools.dangerPath`;
  212. }
  213. }
  214. }
  215. return null;
  216. }
  217. // ── Assistant output parsing ────────────────────────────────────────────────
  218. /**
  219. * Split raw assistant output into three display zones:
  220. * - `leadIn` = inter-think text segments (all except the last)
  221. * - `thinking` = merged <think>…</think> blocks
  222. * - `content` = the final answer (last non-empty segment)
  223. */
  224. export function parseAssistantOutput(raw: string): {
  225. leadIn: string;
  226. thinking: string;
  227. content: string;
  228. } {
  229. const s = stripToolCallFences(raw);
  230. if (!s.includes("<think>")) return { leadIn: "", thinking: "", content: s };
  231. const thinkingParts: string[] = [];
  232. let withoutThink = s.replace(/<think>([\s\S]*?)<\/think>/g, (_: string, inner: string) => {
  233. thinkingParts.push(inner.trim());
  234. return "\x00";
  235. });
  236. // Handle an unclosed <think> at the end (still streaming)
  237. const openIdx = withoutThink.indexOf("<think>");
  238. if (openIdx !== -1) {
  239. thinkingParts.push(withoutThink.slice(openIdx + 7).trim());
  240. withoutThink = withoutThink.slice(0, openIdx);
  241. }
  242. const thinking = thinkingParts.join("\n\n");
  243. const parts = withoutThink
  244. .split("\x00")
  245. .map((p: string) => p.trim())
  246. .filter(Boolean);
  247. if (parts.length === 0) return { leadIn: "", thinking, content: "" };
  248. const content = parts[parts.length - 1];
  249. const leadIn = parts.slice(0, -1).map(cleanAssistantLeadIn).filter(Boolean).join("\n\n");
  250. return { leadIn, thinking, content };
  251. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.