ls-release-litesuite

name	ls-release-litesuite
description	Lite Suite Release Pipeline. Use when releasing LiteSuite or LiteImage, updating litesuite.dev manifests, building release installers, creating GitHub releases, or performing gated Lite Suite release checks.

Lite Suite Release Pipeline

Full release pipeline with gated phases. Every phase requires explicit user confirmation before proceeding.

CRITICAL: This is a slow, deliberate process. Walk each repo carefully. Show the user exactly what you found. Ask for confirmation at EVERY gate. Never batch multiple phases together.

Apps

App	ID	Directory	Build Output	Repo	Package Mgr	Branch
LiteSuite	litesuite	<your-litesuite-dir>\LiteSuite	release/	<your-github-org>/LiteSuite	bun	develop
LiteImage	liteimage	<your-litesuite-dir>\LiteImage	release/	<your-github-org>/LiteImage	pnpm	main

Post-consolidation (2026-04-21): LiteSuite is a monorepo containing everything — LiteEditor, LiteDesign, LiteSpeak, LiteTerminal, LiteYT, LiteBench, LiteAgent, LiteGauntlet, plus workspace packages (lite-license, lite-ui, contracts, shared). LiteImage is the only separate app (GPU/CUDA). LiteEditor is frozen as the free open-source version.

Supporting repos (check for dirty state but don't build):

Repo	Directory	Branch
litesuite.dev	<your-litesuite-dir>\litesuite.dev	master
docs	<your-litesuite-dir>\docs	main

When Invoked

Ask whether to release LiteSuite, LiteImage, or both. Then walk through every phase in order. Never skip a phase. Never proceed without user confirmation.

---

Phase 0: Pre-Flight — Repo Survey

Goal: Walk every repo and report its state. No changes made.

For EACH app directory (and supporting repos), run and report:

1. Branch: What branch is it on? LiteSuite should be on develop, LiteImage on main
2. Worktrees: Are there any active git worktrees? (git worktree list)
3. Dirty files: Any uncommitted changes? (git status — never use -uall)
4. Unpushed commits: Is it ahead of origin? (git log origin/<branch>..HEAD --oneline)
5. Version: Current version from package.json (LiteSuite: apps/desktop/package.json)

Present a summary table:

| App | Branch | Worktrees | Dirty | Unpushed | Version |
|-----|--------|-----------|-------|----------|---------|
| LiteSuite | develop | 0 | clean | 0 | 0.0.13 |
| LiteImage | main | 0 | clean | 0 | 1.0.0 |
| litesuite.dev | master | 0 | clean | 0 | — |

Flag any repo that has worktrees, dirty files, or unpushed commits.

Security pre-flight: license token verification

For any release that includes LiteSuite or LiteImage, verify the license JWT/HMAC secret path before building. packages/lite-license/src/constants.ts warns when JWT_VERIFICATION_SECRET is still __REPLACE_AT_BUILD_TIME__; a release with that warning means token verification is disabled and must be blocked.

Run:

cd <your-litesuite-dir>\LiteSuite
rg -n "JWT_VERIFICATION_SECRET|LITESUITE_JWT_SECRET|__REPLACE_AT_BUILD_TIME__|define:" packages/lite-license/src apps/desktop/tsdown.config.ts scripts/build-desktop-artifact.ts

Report whether the build actually injects LITESUITE_JWT_SECRET at build time. Do not treat a release-shell environment variable by itself as sufficient for a double-click packaged Electron app; the packaged app must not depend on the user's runtime environment for this secret.

If there is no build-time replacement/define path, stop the release and tell the user the release pipeline needs a code fix first. If a build-time injection path exists, verify the release shell has a non-placeholder secret without printing it:

$secret = $env:LITESUITE_JWT_SECRET
if ([string]::IsNullOrWhiteSpace($secret) -or $secret -eq "__REPLACE_AT_BUILD_TIME__") {
  throw "LITESUITE_JWT_SECRET is missing or still the placeholder. Do not release."
}
if ($secret.Length -lt 32) {
  throw "LITESUITE_JWT_SECRET is unexpectedly short. Do not release."
}
"LITESUITE_JWT_SECRET configured: true; length=$($secret.Length); value=[redacted]"

GATE: Show the table. Ask: "Any repos need attention before we proceed? Should I clean up worktrees/branches, or are they intentional?"

---

Phase 1: Worktree & Branch Cleanup

Goal: Merge or remove any worktrees/branches that should be folded in.

For each repo the user confirms needs cleanup:

1. List the worktree branches and their status
2. Show the diff/log of what the branch contains
3. Ask: "Merge this branch, or delete it?"
4. If merge: git merge <branch>, then git worktree remove <path>
5. If delete: git worktree remove <path> then git branch -D <branch>

GATE: "All worktrees resolved. Ready to handle uncommitted changes?"

---

Phase 2: Commit & Push

Goal: Get every repo clean and pushed.

For each repo with dirty files or unpushed commits:

1. Show git status and git diff --stat
2. Ask: "Commit these changes? If yes, what should the commit message be?"
3. Stage relevant files (never git add -A — be specific)
4. Commit with user-approved message
5. Push to origin

For repos that are already clean and pushed, report "already clean" and skip.

GATE: Show updated table (all repos should now be clean + pushed). Ask: "All repos are clean and pushed. Ready to bump versions?"

---

Phase 3: Version Bump

Goal: Coordinate version numbers across apps being released.

For each app being released:

1. Show current version:
   • LiteSuite: apps/desktop/package.json (also apps/server/package.json)
   • LiteImage: package.json
2. Ask: "What version should this be? (current: X.Y.Z)"
3. Update the version field(s)
4. Commit: chore: bump version to X.Y.Z
5. Push

GATE: Show version table. Ask: "All versions correct? Ready to build?"

---

Phase 4: Build

LiteSuite

The build uses an Effect-TS build script with CLI flags. Must specify --target nsis for the installer (default is dir on Windows which only produces an unpacked directory).

cd <your-litesuite-dir>/LiteSuite

# Full build (compiles desktop + server + web, then packages):
node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64

# If artifacts are already compiled, skip the build step:
node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64 --skip-build

Build script internals (know these for debugging):

• Stages a temp directory with a synthetic package.json containing only runtime deps
• workspace:* deps are filtered out (bundled by tsdown via noExternal in apps/desktop/tsdown.config.ts)
• catalog: deps are resolved via scripts/lib/resolve-catalog.ts
• Runs bun install --production in the staging dir
• Rebuilds better-sqlite3 for Electron via @electron/rebuild
• Then runs electron-builder with dynamically generated config

Environment variables (optional overrides):

• LITESUITE_DESKTOP_TARGET — dir | nsis | dmg | AppImage
• LITESUITE_DESKTOP_PLATFORM — win | mac | linux
• LITESUITE_DESKTOP_ARCH — x64 | arm64
• LITESUITE_DESKTOP_SKIP_BUILD — true to skip turbo build step
• LITESUITE_DESKTOP_KEEP_STAGE — true to inspect staging dir
• LITESUITE_DESKTOP_VERBOSE — true to see subprocess output

Output: release/litesuite-<version>-x64.exe (~470MB)

LiteImage

cd <your-litesuite-dir>/LiteImage
pnpm run dist

Standard electron-builder with NSIS config inline in package.json.

Dependencies: LiteImage references lite-license and lite-ui as file:../LiteSuite/packages/lite-license and file:../LiteSuite/packages/lite-ui. These must resolve — LiteSuite repo must be present as a sibling directory of LiteImage.

Output: release/LiteImage Setup <version>.exe (~1.5GB — includes sd-cli, ffmpeg, CUDA DLLs, Python backends)

Build both in parallel when possible. LiteImage takes longer.

After all builds complete, verify each exe exists and report sizes.

Before reporting success, scan compiled JavaScript artifacts for the placeholder and runtime-only secret access:

cd <your-litesuite-dir>\LiteSuite
rg -n "__REPLACE_AT_BUILD_TIME__|Token verification is DISABLED|process\.env\[[\"']LITESUITE_JWT_SECRET[\"']\]" apps/desktop/dist-electron

This command should return no matches for a production release. If it finds the placeholder, disabled-verification warning, or a runtime process.env["LITESUITE_JWT_SECRET"] access in packaged code, stop and fix the build-time injection before continuing.

GATE: Show build results table (app, exe path, size). Ask: "All builds successful? Ready to compute hashes?"

---

Phase 5: Compute Hashes

For each built app, compute SHA-256 and file size of the portable .zip (NOT the NSIS .exe):

# LiteSuite zip is auto-generated alongside the exe
# LiteImage zip is auto-generated alongside the exe
Get-Item <zip-paths> | ForEach-Object {
  $hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $_.FullName).Hash.ToLowerInvariant()
  "{0} | size={1} | sha256={2}" -f $_.Name, $_.Length, $hash
}

If no .zip was generated, create one from the .exe + README:

cd <release-dir>
powershell -Command "Compress-Archive -Path '<exe>','README.txt' -DestinationPath '<app>-<version>.zip' -Force"

Present hash table.

GATE: "Hashes computed. Ready to update the manifest?"

---

Phase 6: Update Manifest

Edit <your-litesuite-dir>\litesuite.dev\public\manifest.json:

• Update updatedAt to today's ISO date
• For each rebuilt app: update version, size, sha256, downloadUrl
• downloadUrl format: https://litesuite.dev/api/download/app?id=<appId>&v=<version>
• Leave comingSoon apps untouched

Show the diff of manifest changes.

GATE: "Manifest updated. Review the diff above. Ready to push GitHub releases?"

---

Phase 7: Push GitHub Releases

For each app, upload the portable .zip as the release asset:

cd <app-dir>
VERSION=$(node -p "require('./package.json').version")
TAG="v$VERSION"
gh release delete "$TAG" --yes 2>/dev/null
gh release create "$TAG" "<release-dir>/<ProductName>-${VERSION}-win.zip" \
  --title "<ProductName> $VERSION" \
  --notes "Release build" \
  --latest

The download endpoint at litesuite.dev/api/download/app/route.ts takes release.assets[0] — the zip MUST be the only or first asset.

Do each app one at a time. Report success/failure after each.

GATE: "All releases pushed. Ready to deploy the manifest?"

---

Phase 8: Deploy Manifest

litesuite.dev deploys via git push (CI/CD). NEVER manually build/deploy.

cd <your-litesuite-dir>/litesuite.dev
git add public/manifest.json
git commit -m "Update manifest: <summary of version changes>"
git push

GATE: "Manifest deployed. Ready for post-release checks?"

---

Phase 9: Post-Release

1. Update install-state.json in your LiteSuite install directory with new versions
2. Verify the manifest is live: curl -s https://litesuite.dev/manifest.json | python -m json.tool | head -20
3. Verify one download URL works: pick an app and confirm the redirect resolves
4. Check admin dashboard for launch_count — verify the counter is incrementing for active users

GATE: "Release complete. Summary of what was released:"

---

Phase 10 (Optional): Clean-Room Install Test via VirtualBox

We have cli-anything-virtualbox installed — a CLI wrapper around VBoxManage for automated VM management. Use it to spin up a disposable Windows VM, install the release, and verify it launches on a fresh machine.

Prerequisites: VirtualBox 7.x installed and on PATH (cli-anything-virtualbox resolves via your shell), a Windows 11 ISO or existing base VM with a "clean-baseline" snapshot.

Requirements: Install VirtualBox from https://www.virtualbox.org/wiki/Downloads and the cli-anything-virtualbox CLI wrapper.

Setup (one-time — create a reusable test VM)

cli-anything-virtualbox vm create -n "LiteSuite-TestBed" --ostype Windows11_64 --cpus 4 --memory 8192
cli-anything-virtualbox storage create-disk -f <your-vms-dir>\litesuite-testbed.vdi -s 51200
cli-anything-virtualbox storage add-controller LiteSuite-TestBed -n SATA --type sata
cli-anything-virtualbox storage attach LiteSuite-TestBed --controller SATA --medium <your-vms-dir>\litesuite-testbed.vdi --type hdd
# Install Windows, take a clean snapshot:
cli-anything-virtualbox snapshot take LiteSuite-TestBed -n "clean-baseline" -d "Fresh Windows 11 install"

Per-release test flow

# 1. Restore to clean state
cli-anything-virtualbox snapshot restore LiteSuite-TestBed "clean-baseline"

# 2. Start headless
cli-anything-virtualbox vm start LiteSuite-TestBed --type headless

# 3. Copy the installer into the guest
cli-anything-virtualbox guest copyto LiteSuite-TestBed \
  --source "<your-litesuite-dir>\LiteSuite\release\litesuite-<version>-x64.exe" \
  --target "C:\Users\TestUser\Desktop\litesuite-setup.exe" \
  --username TestUser --password <pw>

# 4. Run the installer silently (NSIS /S flag)
cli-anything-virtualbox guest run LiteSuite-TestBed \
  --exe "C:\Users\TestUser\Desktop\litesuite-setup.exe" \
  --username TestUser --password <pw> \
  --args "/S"

# 5. Verify it installed
cli-anything-virtualbox guest run LiteSuite-TestBed \
  --exe "C:\Windows\System32\cmd.exe" \
  --username TestUser --password <pw> \
  --args "/c dir C:\Users\TestUser\AppData\Local\LiteSuite"

# 6. Take a screenshot to verify launch (optional)
cli-anything-virtualbox vm screenshot LiteSuite-TestBed -o release-test-screenshot.png

# 7. Power off — snapshot remains for next release
cli-anything-virtualbox vm stop LiteSuite-TestBed --force

For LiteImage, repeat the same flow — copy the LiteImage installer, run /S, verify the exe landed.

Windows Sandbox (sandbox.wsb) is also available for quick detonation tests without the full VM setup — but VirtualBox gives GPU passthrough, persistence, and true E2E verification.

GATE: "Clean-room install test passed? Ready to finalize?"

Show final summary table:

| App | Version | Exe Size | Zip Size | SHA256 (first 12) | GitHub Release |
|-----|---------|----------|----------|-------------------|----------------|

---

Troubleshooting

"Workspace dependency not found" during LiteSuite build

The staging package.json includes workspace:* deps that can't resolve outside the monorepo. Fix: ensure resolveDesktopRuntimeDependencies() in scripts/build-desktop-artifact.ts filters them out. They're bundled by tsdown via noExternal — they should never be in the staging deps.

"lite-license not found" during LiteImage build

LiteImage references file:../LiteSuite/packages/lite-license. Ensure LiteSuite repo exists as a sibling directory of LiteImage. If the relative path changed, update package.json and run pnpm install.

ESM/CJS module errors at runtime

Some npm packages (like youtube-transcript) are ESM-only. They must be added to noExternal in apps/desktop/tsdown.config.ts so tsdown bundles them at compile time instead of loading from node_modules at runtime.

Build produces dir instead of NSIS .exe

Windows default target is dir. You MUST pass --target nsis to the build script, or set LITESUITE_DESKTOP_TARGET=nsis.

---

Rules

• LiteSuite uses bun, LiteImage uses pnpm — never mix them
• Use python not python3 on Windows
• Both apps output to release/ directory
• Hash the .zip files, NEVER the NSIS .exe installers
• Block the release if JWT_VERIFICATION_SECRET remains __REPLACE_AT_BUILD_TIME__, if LITESUITE_JWT_SECRET is missing/placeholder, or if packaged artifacts still depend on runtime process.env["LITESUITE_JWT_SECRET"]
• litesuite.dev deploys via git push — never manually build or deploy
• Always verify the exe exists in release/ before proceeding to hashes
• LiteSuite's build script requires --target nsis for the installer
• NEVER skip a gate. ALWAYS wait for user confirmation.
• NEVER batch multiple repos into one action without showing each.
• When in doubt, show more detail, not less