# AetherDesk Release Packaging

## Release Surface

AetherDesk is the standalone local AI desktop/browser-agent product. It should release from this repository, not from the older `SCBE-AETHERMOORE/aetherdesk` subtree.

## Local Gate

Run this before opening or merging a release PR:

```powershell
npm run release:check
```

That command runs:

- `npm test`
- `npm run build:react`

Before pushing, install and run the local pre-push gate:

```powershell
npm run hooks:install
npm run prepush:check
```

That gate checks whitespace (`git diff --check`), conflict markers, JavaScript syntax for tracked `.js/.cjs/.mjs` files, then the release check above.

For a fuller browser-agent smoke on a machine with Playwright Chromium installed:

```powershell
npm run release:check:agent
```

## Release Objects

| Object | Owner Files | Gate |
|---|---|---|
| Express desktop server | `aetherdesk/server.js` | `npm test` |
| DOM desktop shell | `aetherdesk/public/index.html` | `npm test` |
| React desktop shell | `react-desktop/src/main.jsx`, `react-desktop/src/styles.css` | `npm run build:react` |
| Browser sidebar agent | `extensions/playwright-sidebar-agent/*`, `scripts/playwright-sidebar-agent.js` | `npm run sidebar:agent:probe` |
| Prime Grid | `scripts/prime-grid.js`, `docs/PRIME_GRID.md` | `npm test` |
| AI Plugin+ MCP bridge | `scripts/aetherdesk-tool-mcp.js`, `docs/AETHERDESK_PLUGIN_PLUS.md` | `npm run aetherdesk:package:plugin` |

## GitHub Gate

`.github/workflows/ci.yml` runs `npm run release:check` on PRs and pushes to `main`, then uploads the React build as a workflow artifact.

## Packaging Rule

Do not claim a desktop release unless:

1. `npm run release:check` passes.
2. `npm run prepush:check` passes before pushing.
3. The React build artifact exists.
4. If the change touches the browser sidebar, `npm run release:check:agent` passes locally or the PR says why it was skipped.
5. The release notes name whether the shipped UI is the DOM shell, React shell, or both.

## Desktop Bundle Research

The user-facing target should be a single downloadable Windows artifact, not a claim that every runtime file is literally inside one executable.
Chrome, Edge, Electron apps, and most Windows desktop products ship as either an installer executable or an installed app folder with supporting
runtime resources. Treat "single file" as one of these release objects:

| Target | User sees | Best fit for AetherDesk | Notes |
|---|---|---|---|
| Setup installer | `AetherDesk-Setup.exe` | Primary product release | One file to download and run. Installs app files, shortcuts, and update hooks. |
| Portable zip | `AetherDesk-win-x64.zip` | Backup / power-user release | No installer. User extracts a folder and runs `AetherDesk.exe`. |
| Local server executable | `aetherdesk-server.exe` | Connector/server-only release | Starts the Express/MCP server, then opens the browser. Not a full desktop shell by itself. |
| True single executable desktop | `AetherDesk.exe` only | Not the first target | Hard to do honestly once Chromium/WebView, Playwright, assets, and native runtimes are included. |

### Current Stack Constraint

AetherDesk is currently:

- Node/Express backend: `aetherdesk/server.js`
- React/Vite UI artifact: `artifacts/aetherdesk-react-dist/`
- Classic DOM UI: `aetherdesk/public/index.html`
- Browser automation and web audit surfaces using Playwright
- MCP connector over HTTP: `/mcp`
- Plugin+ stdio MCP bridge: `npm run mcp:aetherdesk`

That means there are two real desktop-packaging routes.

### Route A: Electron Forge, Chromium Included

Use this when the goal is "works like a browser/desktop app even if the user does not have a runtime installed."

Electron packaging puts app code under Electron's runtime resources, commonly as an `app.asar`, and Forge can produce platform-specific
distributables such as installers or zips. This is the closest match to "like Chrome" because Chromium ships with the app.

Recommended AetherDesk shape:

```text
electron/main.cjs
  - start the existing Express app on 127.0.0.1:0
  - create a BrowserWindow
  - load http://127.0.0.1:<port>/desktop
  - close server on app quit

electron/preload.cjs
  - expose only safe desktop APIs

forge.config.cjs
  - package app as asar
  - make Windows zip first
  - add Squirrel/MSI/NSIS installer after the app is stable
```

Pros:

- Most product-like path for AetherDesk.
- Bundles Chromium, so rendering is controlled.
- Lets us keep the current Node/Express code with minimal rewrite.
- Good fit for future real terminal/WebSocket/PTY surfaces.

Cons:

- Larger artifact.
- Needs code signing before serious public distribution.
- Still not literally one runtime-free `.exe`; it is an installer or app folder with resources.

### Route B: Tauri / WebView2, Smaller Windows App

Use this when the goal is "small Windows desktop shell that uses the system WebView."

Tauri can build Windows `.msi` installers or NSIS `-setup.exe` installers. On Windows, it uses WebView2. Microsoft documents that Windows 11
includes the Evergreen WebView2 Runtime, but apps should still detect/install it for machines where it is missing. Tauri also supports bundling
or checking WebView2 install modes.

Recommended only after the UI/API boundary is cleaner:

```text
src-tauri/
  - Rust shell app
  - either call the existing Node server as a sidecar
  - or port the small server APIs into Rust commands over time
```

Pros:

- Much smaller than Electron.
- More Windows-native feel.
- Good long-term path if AetherDesk becomes a tight local-first shell.

Cons:

- Requires Rust/Tauri toolchain.
- Node/Express and Playwright become sidecars or need rewrite.
- WebView2 runtime handling becomes part of release QA.

### Route C: Node SEA Server Executable

Use this for the connector/server-only lane, not for the main visual desktop.

Node's Single Executable Application feature can embed a bundled script into a Node binary and can include assets. For AetherDesk this could
produce:

```text
aetherdesk-server.exe
  - starts Express/MCP
  - serves `/desktop`
  - opens the user's default browser
```

This is useful for "install nothing, run local connector," but it is not the same as a full Chrome/Edge-like app because it depends on an
external browser for the UI.

### Recommendation

Build releases in this order:

1. `npm run build:react` remains the required web artifact gate.
2. Add Electron shell with no feature changes: it only hosts the existing server/UI.
3. Add `npm run package:desktop` to produce an unpacked Windows app.
4. Add `npm run make:desktop` to produce a Windows zip and setup installer.
5. Add a server-only `aetherdesk-server.exe` later using Node SEA or an equivalent bundler for connector deployments.
6. Evaluate Tauri only after Electron proves the product surface and the app boundary stabilizes.

### Source Notes

- Electron recommends Electron Forge for packaging and distribution, and describes distributables as OS-specific formats such as DMG,
  deb, MSI, and others: <https://electronjs.org/docs/latest/tutorial/tutorial-packaging>
- Electron's manual packaging model places app files or `app.asar` inside the Electron runtime resources:
  <https://electronjs.org/docs/latest/tutorial/application-distribution>
- Electron Forge makers generate platform-specific distributables such as Squirrel.Windows, MSI, ZIP, DMG, and other formats:
  <https://www.electronforge.io/config/makers>
- Electron ASAR bundles app source into a single archive for faster loading and cursory source concealment, but it is not an app installer
  by itself: <https://electronjs.org/docs/latest/tutorial/asar-archives>
- Tauri builds Windows apps as `.msi` or NSIS `-setup.exe` installers: <https://v2.tauri.app/distribute/windows-installer/>
- Microsoft WebView2 Evergreen Runtime is shared across apps, auto-updated, and recommended for most developers; fixed-version WebView2
  exists for strict compatibility requirements:
  <https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version>
- Microsoft's WebView2 distribution guidance covers Evergreen runtime deployment and app-side detection/installation:
  <https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution>
- Node SEA creates a single executable Node application by injecting a prepared blob into a Node binary and supports bundled assets:
  <https://nodejs.org/api/single-executable-applications.html>
