You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Every npm script in package.json, grouped by purpose. If you find yourself searching package.json
with Ctrl+F to figure out what to run, that's the signal to update this file instead.
Daily development
Script
What it does
When to use
npm run dev
Clean, build main+renderer (dev mode), launch Electron with logging
First-thing-in-the-morning launch
npm run dev:fast
Launch without rebuilding (assumes a previous dev build exists)
Iterating on main-process changes
npm run dev:cdp
dev:fast + --remote-debugging-port=9222
Driving the app over Chrome DevTools Protocol
npm run dev:demo
dev with STRATOSORT_REDACT_PATHS=1 (paths redacted in the UI)
Screenshots / recordings
npm start
Same as dev without the running-instance check and clean step
Slightly faster restart
npm run start:prod
Launch with NODE_ENV=production against existing build
Smoke-testing a prod-style binary locally
npm run start:debug
Launch existing dev build with --inspect (no rebuild)
Same, skipping the dist build and packaged-artifact checks (--skip-dist)
Quick sanity before a series of release attempts
Individual verify:* scripts
Useful to run individually when you broke one and want a fast loop. The In ci column marks the
twelve that npm run ci runs; the rest run in local:gate, release preflight, release workflows,
or on demand.
Script
What it verifies
In ci
verify:ipc-handlers
100% of IPC_CHANNELS have a registered handler
yes
verify:ipc-handler-schemas
Every handler that accepts input has a Zod schema (small allowlist for zero-arg)
yes
verify:ipc-contracts
Renderer/preload/main contract consistency
yes
verify:ipc-enforcement
Concurrency-limited / enforcement channel sets are consistent
yes
verify:ipc-event-schemas
Every main→renderer push event that is sent has a payload schema
yes
verify:mcp-contracts
MCP server interface consistency
yes
verify:ai-provider-contracts
AI provider interface consistency (BYOK contracts)
yes
verify:analysis-routing
Analysis dispatch correctness
yes
verify:electron-fuses-config
electron-builder.json declares the fuses and asarUnpack keeps app code in asar
yes
verify:env-docs
All STRATOSORT_* env vars are documented in docs/CONFIG.md
yes
verify:checkjs-ratchet
// @ts-check coverage never drops; new files in covered dirs must opt in
yes
verify:version-tag
package.json is not behind the latest v* tag (warns when ahead)
yes
verify:ipc-consumers
Every bridged electronAPI method is actually called from the renderer
no
verify:installed-electron
The installed Electron matches the pinned version (local:gate, predist:win)
no
verify:native-modules
Native modules load under the current Electron ABI (local:gate, preflight, CI)
no
verify:build-assets
Build outputs have expected files
no
verify:packaged-artifacts
Packaged installers/zips have expected contents
no
verify:packaged-linux
Linux variant of the above
no
verify:runtime-prereqs
Runtime binary prereqs (FFmpeg, etc.) are present where expected
no
verify:splash-csp
Splash screen CSP hash matches the hardcoded value (also run at the end of build)
no
verify:updater-metadata
electron-updater latest*.yml metadata is consistent
no
Setup (runtime assets)
Script
What it does
npm run setup:deps
Download default AI models automatically
npm run setup:models / :check
Download/verify GGUF models listed in modelRegistry.js
npm run setup:vision-runtime / :check
Download/verify llama-server vision runtime
npm run setup:ffmpeg-runtime / :check
Download/verify bundled FFmpeg
npm run setup:whisper-model / :check
Download/verify Whisper model
npm run setup:tessdata-runtime / :check
Download/verify bundled Tesseract language data
npm run setup:vc-redist / :check
Download/verify Microsoft's signed VC++ Redistributable (--arch=)
DMG (specific arch); regenerates branding (icon.icns) first
npm run dist:linux
Linux
AppImage + .deb
npm run dist:linux:x64 / :arm64
Linux
AppImage + .deb for a specific arch
npm run dist:all
all
Builds for all three (only works on macOS host with cross-compile)
Compliance / license
Script
What it does
npm run audit:production
npm audit --omit=dev (security advisories)
npm run audit:bundled
Full npm audit; fails on high/critical in bundled renderer deps
npm run licenses:production
Generate docs/licenses-production.json (gitignored) from the lock
npm run compliance:commercial:build
Regenerate the commercial compliance inventory
npm run compliance:commercial:verify
Gate: fails on high_risk or unknown licenses
npm run docs:env-audit
Find undocumented STRATOSORT_* env vars
Generators / one-offs
Script
What it does
npm run generate:channels
Print the generated preload IPC channel block from constants.js to stdout (no write)
npm run generate:channels:check
Check whether the generated file is up to date (CI uses this)
npm run generate:channels:update
Regenerate and write the preload IPC channel allowlist file in place
npm run generate:icons
Generate platform icon files from the source logo (assets/icons/StratoSortStackLogo.svg, legacy PNG fallback)
npm run generate:nsis
Generate NSIS installer assets
npm run generate:assets
generate:icons + generate:nsis
npm run audit:ipc-line-data
Regenerate (the previously-deleted) IPC line-by-line audit
npm run inventory:ipc-main-sends
List all main→renderer webContents.send() call sites
npm run tour:record
Record the how-to-use product tour (paths redacted); :library / :studio record single topics
npm run tour:compose
Compose walkthrough media from a recorded tour; :lessons builds the lesson clips
Stability / benchmarking
Script
What it does
npm run stability:fixtures
Generate the synthetic-corpus test fixtures under .tmp/stability/
npm run stability:smoke
Run the smoke suite (sanity test, fast)
npm run stability:benchmark:fixtures
Benchmark against the synthetic corpus
npm run stability:benchmark:e2e-batch
E2E batch-analysis benchmark
npm run stability:compare
Compare two SHAs against the baseline ledger
npm run stability:ledger
Generate / update the baseline ledger
npm run stability:check-thresholds
Check release-threshold drift
Diagnostics / monitoring
Script
What it does
npm run startup:check
Sanity check before launching the app
npm run diagnostics:real-models
Run the pipeline against real model files
npm run measure:embeddings
Offline embedding-quality probe (doc↔folder cosine scores, no Electron)
npm run monitor:batch
Live tail of batch-analysis progress
npm run monitor:batch:electron-node
Same, running under Electron-as-Node
Hooks / housekeeping
Script
What it does
npm run prepare
Husky install (run by npm install)
npm run postinstall
Rebuild native modules for the current Electron ABI
npm run upgrade
npm-check-updates -u && npm install (run with care; review the diff)
How to add a new script
Put it in package.json with a clear, hyphenated name. Prefix matters: verify:* for verifiers,
test:* for test runners, stability:* for the benchmark suite, etc. A verify:* prefix does
not wire it into CI by itself — see step 3.
Add a row in this file under the matching section.
If it should run in CI, append it to the ci script's chain.
If it creates files, add the output path to .gitignore.