@adea-ai/app-framework 0.38.0 → 0.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -79,12 +79,13 @@ test checks the file list against the exports.
79
79
  | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
80
80
  | Application and shell | `application`, `app-shell`, `app-utilities`, `app-settings`, `app-help`, `app-about`, `update-surface` (all _solid_), `service-registry`, `application-menu`, `application-command-client` |
81
81
  | Appearance | `appearance-host`, `appearance-preferences`, `appearance-surface`, `custom-theme-library`, `window-surface` (all _solid_) |
82
- | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-detection`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `open-url-channel`, `client-asset-manifest`, `client-assets` (source only) |
82
+ | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-detection`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `open-url-channel`, `client-asset-manifest`, `client-assets` (source only), `client-dev-proxy` |
83
83
  | Native windows and OS | `renderer-profile`, `secure-window`, `partitioned-window`, `window-options` (source only), `native-utilities`, `native-secret-store`, `app-bundle`, `sidecar`, `sidecar-services`, `desktop-build-hook`, `desktop-build`, `windows-runtime-patch`, `electrobun-types` (ambient types only) |
84
84
  | Native installers | `windows-extractor-build`, `installer-archive`, `window-surface-store` |
85
85
  | Updates | `desktop-updater`, `update-manager`, `update-inherited-launch-lease`, `packaged-launch-admission`, `packaged-update-startup`, `update-resume`, `channel-update-manager`, `update-channel-store`, `update-discovery`, `update-download`, `update-extraction`, `signed-release`, `release-feed`, `release-location`, `update-process-liveness`, `update-adapter` (_solid_), `release-version` (_solid_), `update-state` (source only), `update-helper.js` (bundled helper) |
86
86
  | Release tooling | `release-config`, `release-cut`, `release-steps`, `release-staging`, `release-artifact`, `release-assets-plan`, `release-descriptor-staging`, `release-publication`, `release-publish-command`, `release-promotion`, `retained-release-build`, `github-release-publisher`, `github-release-qualification`, `github-release-promotion`, `macos-dmg` |
87
87
  | Installer qualification | `installer-layout`, `installer-identity`, `installer-extraction`, `installed-payload`, `installer-observation`, `installer-qualification-command`, `installer-renderer-evidence` |
88
+ | Developer app | `developer-app` |
88
89
  | CI | `toolchain-identity` |
89
90
 
90
91
  Commands (package `bin` entries):
@@ -93,7 +94,8 @@ Commands (package `bin` entries):
93
94
  | --------------------------------- | --------------------------------------------------------------------------------------------------- |
94
95
  | `create-adea-app` | Generate an application from the starter template. |
95
96
  | `adea-update-app-framework` | Move an app's framework tarball, lockfile and workflow pins to a published release together. |
96
- | `adea-cut-release` | Cut a `dev` or `daily` release from trusted `main`. |
97
+ | `adea-cut-release` | Cut a `daily` release from trusted `main`. |
98
+ | `adea-developer-app` | Run the developer app from the checkout, or install its launcher (`run` / `install`). |
97
99
  | `adea-plan-release-assets` | Validate a dispatched release-assets run and resolve its source and version. |
98
100
  | `adea-release-step` | Run a per-platform step: `select-retained`, `stage-build`, `inspect`, `qualify`, `qualify-upgrade`. |
99
101
  | `adea-sign-release` | Sign one staged archive's release identity. |
@@ -625,22 +627,12 @@ and every release carries that version:
625
627
  - A daily (and later stable) release is the Release Please release `v<version>`.
626
628
  The framework resolves the tag's exact commit and requires the manifest at
627
629
  that commit to match the tag before building, publishing or qualifying it.
628
- - A dev release is `v<next>-dev.N`, cut from each push to `main`, where `<next>`
629
- is the next minor version after the manifest's. Release Please writes a
630
- version to the manifest only when it releases it, so the manifest always names
631
- the latest release and dev builds are numbered for the version after it. `N`
632
- starts at 1 for every next version and counts up until a release moves it:
633
- while the manifest says `0.111.0`, main cuts `v0.112.0-dev.1` … `v0.112.0-dev.15`;
634
- the commit that releases `v0.112.0` and those after it cut `v0.113.0-dev.1`. A
635
- patch release such as `v0.112.1` leaves the next minor in place, so the counter
636
- keeps rising. A rerun for the same commit reuses the newest dev release; a
637
- commit that does not descend from it and an existing tag without a trusted
638
- release are refused.
639
-
640
- Every dev release sorts above the latest release and below the release it leads
641
- to, so the dev channel moves from `v0.112.0` to `v0.113.0-dev.1` and the daily
642
- channel from `v0.112.0-dev.15` to `v0.112.0`. Versions order the same way on
643
- every channel. Calendar-tagged releases (`v2026.10.31-dev.1525`) from before
630
+ - There are no dev releases. Development runs the developer app from the checkout
631
+ (see "Developer app"); `adea-cut-release dev` is refused. Existing `-dev.N`
632
+ versions still parse and sort below the release they lead to, so an old dev
633
+ install can still read the feed.
634
+
635
+ Calendar-tagged releases (`v2026.10.31-dev.1525`) from before
644
636
  Release Please sort above every version and are never chosen as an upgrade
645
637
  source; their installations reinstall once. An unchanged version reuses the same daily tag,
646
638
  which is why the daily cadence can be any interval. Promotion orders qualified
@@ -662,6 +654,48 @@ with the tag, successful release-assets run ID and attempt number. Its own file
662
654
  name is not configured: finalization trusts only the qualified `assets` run. The retry
663
655
  rechecks the same qualification before changing release visibility.
664
656
 
657
+ ### Developer app
658
+
659
+ Development needs no release build and no dev channel: each app has one persistent
660
+ developer app that runs straight from the developer's checkout. With GitButler the
661
+ checkout is every applied branch merged together, so the window always shows the
662
+ combined state of all parallel work, and agents can drive it to test. Public apps
663
+ publish only daily and stable.
664
+
665
+ An app describes it in `developer-app.json` next to its Electrobun project (paths
666
+ resolve from the file's folder):
667
+
668
+ ```json
669
+ {
670
+ "name": "Example",
671
+ "identifier": "dev.example.app",
672
+ "shellDirectory": ".",
673
+ "watch": ["src"],
674
+ "ui": { "directory": "../web", "command": ["bun", "run", "dev"], "port": 5179, "warm": ["/"] },
675
+ "shellEnv": { "EXAMPLE_SHELL_PORT": "4799" },
676
+ "prepare": [["bun", "scripts/stage.ts"]],
677
+ "icon": "resources/developer-icon.png"
678
+ }
679
+ ```
680
+
681
+ - `adea-developer-app run` runs any `prepare` commands, starts the UI dev server,
682
+ waits for it, then runs `electrobun dev` with `ADEA_DEVELOPER_APP=1` and
683
+ `ADEA_CLIENT_DEV_URL` set. Shell source edits (`watch`) restart the shell.
684
+ - `adea-developer-app install` adds "<Name> (Dev).app" to `/Applications`
685
+ (`ADEA_DEVELOPER_APP_DIR` overrides): a launcher that runs `run` from the checkout
686
+ in a login shell and logs to `~/Library/Logs/<Name> (Dev).log`. Pass
687
+ `-- <command>` to launch a different command from the checkout root instead.
688
+ - In `electrobun.config.ts`, use `developerAppIdentity(app)` when `isDeveloperApp()`:
689
+ it names the app "<Name> (Dev)" with identifier `<identifier>.live`, builds into
690
+ `build.noindex` (out of Spotlight) and uses the staged icon. The framework build
691
+ hook (`desktop-build-hook`) renames the macOS bundle to match.
692
+ - A shell on `desktop-host` passes `clientDevOrigin: process.env.ADEA_CLIENT_DEV_URL`;
693
+ the host then proxies client requests to the dev server instead of serving the
694
+ built client. A shell with its own server uses `client-dev-proxy` directly.
695
+ Both refuse anything but a bare loopback http origin.
696
+ - `runDeveloperApp` and `installDeveloperAppLauncher` (`developer-app`) are the same
697
+ steps as a library, for an app whose run needs more than the config file says.
698
+
665
699
  ### Release feed and local release mode
666
700
 
667
701
  Apps publish to and update from an HTTPS release feed, named in the release
@@ -841,13 +875,12 @@ jobs:
841
875
 
842
876
  `desktop-release-control.yml` owns the release schedule every framework app
843
877
  shares, so callers pass only `app-directory` (and `release-config`,
844
- `install-command` or `bun-version` when they differ from the defaults). A push
845
- to `main` cuts a dev release. Each scheduled run builds the newest Release
878
+ `install-command` or `bun-version` when they differ from the defaults). Each scheduled run builds the newest Release
846
879
  Please version as a daily (doing nothing new when it is already built) and then
847
880
  promotes the newest qualified daily once `soakHours` (96 by default) have passed
848
881
  since the last stable, so stable moves about every four days. The caller's cron
849
882
  is the daily cadence: nothing assumes one run per day, so it can run every few
850
- hours. A manual dispatch runs one `operation`: `dev`, `daily` or `stable`.
883
+ hours. A manual dispatch runs one `operation`: `daily` or `stable`.
851
884
  `CI_BILLING_PAUSED=true` skips the push and schedule cuts;
852
885
  `STABLE_PROMOTION_HELD=true` holds promotion. To replace a bad stable without
853
886
  the soak, set the protected variable `STABLE_SOAK_BYPASS_TAG=<tag>` to one pending
@@ -1243,6 +1276,16 @@ for a fresh verified download. The preserved `.legacy-<uuid>` sibling is not
1243
1276
  automatically deleted; unknown layouts remain recovery-required. A bounded,
1244
1277
  ownership-aware retention policy remains unfinished.
1245
1278
 
1279
+ Retiring a completed exchange re-proves the installed tree's content digest.
1280
+ That proof tolerates regular files with extra hard links, because backup, dedup
1281
+ and packaging tools can add one to an installed file without changing its
1282
+ bytes; staged candidate proofs still refuse them. If a completed generation
1283
+ still cannot be retired (for example, the app was reinstalled at another
1284
+ version), no retirement record exists yet, and the displaced previous tree is
1285
+ intact, resume renames the staging directory to a `.stale-<uuid>` sibling
1286
+ instead of returning `recovery-required`, so the next update can stage. That
1287
+ sibling is not automatically deleted.
1288
+
1246
1289
  The host can query `updater.pendingHealthAcknowledgement()` for the exact
1247
1290
  installed generation and version, then call `updater.acknowledgeHealthy(token)`
1248
1291
  only after app-owned readiness checks pass. The query retries helper retirement
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env bash
2
- # adea-desktop-release: publish a desktop release from a GitLab release tag pipeline with the
3
- # framework's local release mode. It builds this machine's platform (macOS arm64 or Linux x64),
2
+ # adea-desktop-release: publish a desktop release from a release tag pipeline (GitLab CI, CircleCI or
3
+ # GitHub Actions) with the framework's local release mode. It builds this machine's platform (macOS arm64 or Linux x64),
4
4
  # signs the channel descriptors, uploads the staged tree to the app's release feed (an
5
5
  # S3-compatible bucket such as Cloudflare R2) in plan order with the channel pointers last,
6
6
  # verifies the feed and links every published file on the GitLab release.
@@ -17,12 +17,17 @@
17
17
  # release:extend-plan <channel> <tag> <platform> <out> <source-sha>
18
18
  # adds app files to the staged plan
19
19
  #
20
- # Environment (protected, masked GitLab CI variables reach only protected tags):
20
+ # The tag, commit and run id come from GitLab's CI variables, else CircleCI's or GitHub Actions'.
21
+ #
22
+ # Environment (protected CI variables or contexts):
21
23
  # DESKTOP_RELEASE_APP_DIR the app directory, relative to the repository (default .)
22
24
  # DESKTOP_UPDATE_SIGNING_KEY_B64 base64 of the Ed25519 update key PEM (daily; refused when missing)
23
25
  # R2_ENDPOINT or CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY bucket credentials
24
26
  # R2_BUCKET (default adea-releases), STABLE_PROMOTION_HELD (true holds promotion)
25
27
  # DESKTOP_RELEASE_DRY_RUN=1 cut and plan only: builds, signs and uploads nothing
28
+ # GITLAB_RELEASE_TOKEN links the files on the GitLab release outside GitLab CI (which
29
+ # uses CI_JOB_TOKEN); GITLAB_PROJECT overrides the project path
30
+ # taken from the origin remote
26
31
  # The update key is decoded into the signing process's environment only, never to disk.
27
32
  set -euo pipefail
28
33
  channel=${1:?daily|stable}
@@ -30,12 +35,19 @@ case "$channel" in daily|stable) ;; *) echo "channel must be daily or stable"; e
30
35
  dry=${DESKTOP_RELEASE_DRY_RUN:-}
31
36
  bucket=${R2_BUCKET:-adea-releases}
32
37
  say() { printf '%s\n' "$*"; }
38
+ if [ -z "${CI_COMMIT_TAG:-}" ]; then
39
+ CI_COMMIT_TAG=${CIRCLE_TAG:-}
40
+ [ -n "$CI_COMMIT_TAG" ] || [ "${GITHUB_REF_TYPE:-}" != tag ] || CI_COMMIT_TAG=${GITHUB_REF_NAME:-}
41
+ fi
42
+ CI_COMMIT_SHA=${CI_COMMIT_SHA:-${CIRCLE_SHA1:-${GITHUB_SHA:-}}}
43
+ CI_PIPELINE_ID=${CI_PIPELINE_ID:-${CIRCLE_WORKFLOW_ID:-${GITHUB_RUN_ID:-}}}
33
44
  sha256() { if command -v shasum >/dev/null; then shasum -a 256 "$1"; else sha256sum "$1"; fi | cut -d' ' -f1; }
34
45
  b64d() { printf '%s' "$1" | base64 -d 2>/dev/null || printf '%s' "$1" | base64 -D; }
35
46
 
36
47
  root=$(git rev-parse --show-toplevel)
37
48
  cd "$root"
38
- sha=${CI_COMMIT_SHA:-$(git rev-parse HEAD)}
49
+ sha=${CI_COMMIT_SHA:-}
50
+ [ -n "$sha" ] || sha=$(git rev-parse HEAD)
39
51
  [ "$sha" = "$(git rev-parse HEAD)" ] || { say "refusing: checkout is not at $sha"; exit 1; }
40
52
  # Provenance is checked against origin/main of this project (the framework records the GitLab
41
53
  # project as owner/name). The runner's insteadOf rewrite can still put its job token into
@@ -113,19 +125,31 @@ upload() {
113
125
  # Links every published file of <tag> on its GitLab release (creating the release when release
114
126
  # tooling has not), pointing at the feed. Links that already exist are kept.
115
127
  link_release() { # <tag>
116
- [ -z "$dry" ] && [ -n "${CI_JOB_TOKEN:-}" ] && [ -n "${CI_API_V4_URL:-}" ] || { say "GitLab release links skipped"; return 0; }
117
- bun -e '
118
- const [api, project, token, tag, base, app, outDir] = process.argv.slice(1)
128
+ local header= token= project=${CI_PROJECT_ID:-}
129
+ if [ -n "${CI_JOB_TOKEN:-}" ]; then header=JOB-TOKEN token=$CI_JOB_TOKEN
130
+ elif [ -n "${GITLAB_RELEASE_TOKEN:-}" ]; then header=PRIVATE-TOKEN token=$GITLAB_RELEASE_TOKEN; fi
131
+ [ -z "$dry" ] && [ -n "$header" ] || { say "GitLab release links skipped"; return 0; }
132
+ if [ -z "$project" ]; then
133
+ # The origin remote's path (https://host/<path>.git or git@host:<path>.git), URL-encoded.
134
+ project=${GITLAB_PROJECT:-$(git -C "$root" remote get-url origin)}
135
+ project=${project%.git}
136
+ case "$project" in git@*:*) project=${project#*:} ;; *://*) project=${project#*://}; project=${project#*/} ;; esac
137
+ project=${project//\//%2F}
138
+ fi
139
+ # The token reaches bun through its environment, never its arguments.
140
+ LINK_TOKEN="$token" LINK_HEADER="$header" bun -e '
141
+ const [api, project, tag, base, app, outDir] = process.argv.slice(1)
142
+ const auth = { [process.env.LINK_HEADER]: process.env.LINK_TOKEN }
119
143
  const fs = require("node:fs")
120
144
  const release = JSON.parse(fs.readFileSync(`${outDir}/${app}/${tag}/release.json`, "utf8"))
121
145
  const url = `${api}/projects/${project}/releases/${encodeURIComponent(tag)}`
122
146
  const call = (method, path, body) => fetch(url + path, { method,
123
- headers: { "JOB-TOKEN": token, "content-type": "application/json" },
147
+ headers: { ...auth, "content-type": "application/json" },
124
148
  body: body && JSON.stringify(body) })
125
149
  let res = await call("GET", "")
126
150
  if (res.status === 404) {
127
151
  res = await fetch(`${api}/projects/${project}/releases`, { method: "POST",
128
- headers: { "JOB-TOKEN": token, "content-type": "application/json" },
152
+ headers: { ...auth, "content-type": "application/json" },
129
153
  body: JSON.stringify({ tag_name: tag, name: tag, description: `Desktop release ${tag}.` }) })
130
154
  if (!res.ok) throw new Error(`creating release ${tag}: ${res.status} ${await res.text()}`)
131
155
  res = await call("GET", "")
@@ -139,7 +163,7 @@ link_release() { # <tag>
139
163
  link_type: /\.(json)$/.test(name) ? "other" : "package" })
140
164
  if (!link.ok) throw new Error(`linking ${name}: ${link.status} ${await link.text()}`)
141
165
  console.log(` linked ${name}`)
142
- }' "$CI_API_V4_URL" "$CI_PROJECT_ID" "$CI_JOB_TOKEN" "$1" "$feed_base" "$repo" "$out"
166
+ }' "${CI_API_V4_URL:-https://gitlab.com/api/v4}" "$project" "$1" "$feed_base" "$repo" "$out"
143
167
  }
144
168
 
145
169
  if [ "$channel" = stable ]; then
@@ -202,24 +202,15 @@ async function createApplication(options, dependencies = {}) {
202
202
  "windows-x64": [`${options.slug}-{tag}-windows-x64-Setup.zip`, `${options.slug}-{tag}-windows-x64.tar.zst`],
203
203
  "linux-x64": [`${options.slug}-{tag}-linux-x64-Setup.tar.gz`, `${options.slug}-{tag}-linux-x64.tar.zst`]
204
204
  };
205
- const devDiscoveryAssets = Object.keys(platforms).map((platform) => `dev-${platform}.json`);
206
205
  const dailyDiscoveryAssets = Object.keys(platforms).map((platform) => `daily-${platform}.json`);
207
206
  const stableDiscoveryAssets = Object.keys(platforms).map((platform) => `stable-${platform}.json`);
208
- const releaseAssets = [
209
- ...dailyDiscoveryAssets,
210
- ...stableDiscoveryAssets,
211
- ...devDiscoveryAssets
212
- ];
207
+ const releaseAssets = [...dailyDiscoveryAssets, ...stableDiscoveryAssets];
213
208
  const targets = {
214
209
  "macos-arm64": ["darwin", "arm64"],
215
210
  "windows-x64": ["win32", "x64"],
216
211
  "linux-x64": ["linux", "x64"]
217
212
  };
218
- const descriptors = Object.fromEntries([
219
- "dev",
220
- "daily",
221
- "stable"
222
- ].flatMap((channel) => Object.entries(targets).map(([platform, [os, arch]]) => [`${channel}-${platform}.json`, {
213
+ const descriptors = Object.fromEntries(["daily", "stable"].flatMap((channel) => Object.entries(targets).map(([platform, [os, arch]]) => [`${channel}-${platform}.json`, {
223
214
  channel,
224
215
  platform: os,
225
216
  arch,
@@ -251,7 +242,6 @@ async function createApplication(options, dependencies = {}) {
251
242
  releaseAssets,
252
243
  dailyDiscoveryAssets,
253
244
  stableDiscoveryAssets,
254
- devDiscoveryAssets,
255
245
  releaseSigningKeys: {},
256
246
  descriptors
257
247
  }, null, 2) + "\n");
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env bun
2
+ export {};
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env bun
2
+ import { installDeveloperAppLauncher, readDeveloperAppConfig, runDeveloperApp } from "../developer-app/developer-app.js";
3
+ import { redactedErrorMessage, runCli } from "./cli-runner.js";
4
+ import { dirname, resolve } from "node:path";
5
+ import { execFileSync } from "node:child_process";
6
+ import { fileURLToPath } from "node:url";
7
+ // src/cli/developer-app-cli.ts
8
+ var [action, ...rest] = process.argv.slice(2);
9
+ var split = rest.indexOf("--");
10
+ var args = split === -1 ? rest : rest.slice(0, split);
11
+ var command = split === -1 ? void 0 : rest.slice(split + 1);
12
+ await runCli((error) => `developer app: ${redactedErrorMessage(error)}`, async () => {
13
+ if (action !== "run" && action !== "install" || args.length > 1) throw new Error("Usage: adea-developer-app <run|install> [developer-app.json] [-- command]");
14
+ const path = resolve(args[0] ?? "developer-app.json");
15
+ const config = readDeveloperAppConfig(path);
16
+ if (action === "run") {
17
+ if (command?.length) throw new Error("run takes no command");
18
+ await runDeveloperApp(config);
19
+ return;
20
+ }
21
+ const checkout = execFileSync("git", ["rev-parse", "--show-toplevel"], {
22
+ cwd: dirname(path),
23
+ encoding: "utf8"
24
+ }).trim();
25
+ const self = fileURLToPath(import.meta.url);
26
+ const installed = installDeveloperAppLauncher({
27
+ config,
28
+ checkout,
29
+ command: command?.length ? command : [
30
+ "bun",
31
+ self,
32
+ "run",
33
+ path
34
+ ],
35
+ directory: process.env.ADEA_DEVELOPER_APP_DIR
36
+ });
37
+ process.stdout.write(`Installed ${installed.app}. Logs: ${installed.log}\n`);
38
+ });
@@ -7,7 +7,8 @@ import { readJsonFile, redactedErrorMessage, runCli } from "./cli-runner.js";
7
7
  var local = process.argv[2] === "--local";
8
8
  await runCli((error) => `Unable to cut the release: ${redactedErrorMessage(error)}. Check the trusted workflow or local checkout and release configuration.`, async () => {
9
9
  const [kind, path, sourceSha, ...extra] = process.argv.slice(local ? 3 : 2);
10
- if (kind !== "daily" && kind !== "dev" || !path || extra.length || !sourceSha !== !local) throw new Error("Invalid workflow invocation");
10
+ if (kind === "dev") throw new Error("Dev releases are retired; run the developer app from the checkout");
11
+ if (kind !== "daily" || !path || extra.length || !sourceSha !== !local) throw new Error("Invalid workflow invocation");
11
12
  const config = await readJsonFile(path, 65536);
12
13
  if (typeof config !== "object" || config === null || typeof config.appName !== "string") throw new Error("Missing app name");
13
14
  const result = local ? await runLocalReleaseCut({
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Developer app: the shell serves the client from a UI dev server (Vite) instead of
3
+ * the built client, so edits in the checkout reach the open window through hot module
4
+ * replacement. The window still loads the trusted shell origin: the shell forwards
5
+ * every client request to the dev server, and the HMR socket connects to the dev
6
+ * server's own port directly.
7
+ */
8
+ /** The variable the developer app runner sets to the UI dev server origin. */
9
+ export declare const CLIENT_DEV_URL_VARIABLE = "ADEA_CLIENT_DEV_URL";
10
+ /**
11
+ * The dev server origin to proxy the client to, or undefined when it is not set.
12
+ * Only a bare loopback http origin is accepted, and never for a release build.
13
+ */
14
+ export declare function resolveClientDevOrigin(value: string | undefined, releaseBuild: boolean, name?: string): string | undefined;
15
+ /** Forward one client request to the dev server, optionally rewriting HTML responses. */
16
+ export declare function proxyClientDevRequest(request: Request, devOrigin: string, transformHtml?: (html: string, request: Request) => string, fetchImpl?: typeof fetch): Promise<Response>;
@@ -0,0 +1,84 @@
1
+ // src/desktop/client-dev-proxy.ts
2
+ /**
3
+ * Developer app: the shell serves the client from a UI dev server (Vite) instead of
4
+ * the built client, so edits in the checkout reach the open window through hot module
5
+ * replacement. The window still loads the trusted shell origin: the shell forwards
6
+ * every client request to the dev server, and the HMR socket connects to the dev
7
+ * server's own port directly.
8
+ */
9
+ var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
10
+ "127.0.0.1",
11
+ "localhost",
12
+ "[::1]"
13
+ ]);
14
+ /** Headers that never travel between the shell and the dev server. */
15
+ var DROPPED_REQUEST_HEADERS = [
16
+ "accept-encoding",
17
+ "connection",
18
+ "host",
19
+ "keep-alive",
20
+ "upgrade"
21
+ ];
22
+ var DROPPED_RESPONSE_HEADERS = [
23
+ "connection",
24
+ "content-encoding",
25
+ "content-length",
26
+ "keep-alive",
27
+ "transfer-encoding"
28
+ ];
29
+ /** The variable the developer app runner sets to the UI dev server origin. */
30
+ var CLIENT_DEV_URL_VARIABLE = "ADEA_CLIENT_DEV_URL";
31
+ /**
32
+ * The dev server origin to proxy the client to, or undefined when it is not set.
33
+ * Only a bare loopback http origin is accepted, and never for a release build.
34
+ */
35
+ function resolveClientDevOrigin(value, releaseBuild, name = CLIENT_DEV_URL_VARIABLE) {
36
+ if (!value) return void 0;
37
+ if (releaseBuild) throw new Error(`${name} is refused for a release build`);
38
+ let url;
39
+ try {
40
+ url = new URL(value);
41
+ } catch {
42
+ throw new Error(`${name} must be a loopback http origin`);
43
+ }
44
+ if (url.protocol !== "http:" || !LOOPBACK_HOSTS.has(url.hostname)) throw new Error(`${name} must be a loopback http origin`);
45
+ if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new Error(`${name} must be a bare origin`);
46
+ return url.origin;
47
+ }
48
+ /** Forward one client request to the dev server, optionally rewriting HTML responses. */
49
+ async function proxyClientDevRequest(request, devOrigin, transformHtml, fetchImpl = fetch) {
50
+ const source = new URL(request.url);
51
+ const target = new URL(source.pathname + source.search, devOrigin);
52
+ const headers = new Headers(request.headers);
53
+ for (const name of DROPPED_REQUEST_HEADERS) headers.delete(name);
54
+ const hasBody = request.method !== "GET" && request.method !== "HEAD";
55
+ let upstream;
56
+ try {
57
+ upstream = await fetchImpl(target, {
58
+ method: request.method,
59
+ headers,
60
+ body: hasBody ? await request.arrayBuffer() : void 0,
61
+ redirect: "manual"
62
+ });
63
+ } catch {
64
+ return new Response("<!doctype html><meta http-equiv=\"refresh\" content=\"2\"><p>Waiting for the UI dev server…</p>", {
65
+ status: 502,
66
+ headers: { "content-type": "text/html; charset=utf-8" }
67
+ });
68
+ }
69
+ const responseHeaders = new Headers(upstream.headers);
70
+ for (const name of DROPPED_RESPONSE_HEADERS) responseHeaders.delete(name);
71
+ const type = responseHeaders.get("content-type") ?? "";
72
+ if (transformHtml && type.startsWith("text/html") && request.method !== "HEAD") {
73
+ const html = transformHtml(await upstream.text(), request);
74
+ return new Response(html, {
75
+ status: upstream.status,
76
+ headers: responseHeaders
77
+ });
78
+ }
79
+ return new Response(request.method === "HEAD" ? null : upstream.body, {
80
+ status: upstream.status,
81
+ headers: responseHeaders
82
+ });
83
+ }
84
+ export { CLIENT_DEV_URL_VARIABLE, proxyClientDevRequest, resolveClientDevOrigin };
@@ -28,6 +28,11 @@ export type DesktopRoute = {
28
28
  /** Bind an isolated client server and open a window with a per-window channel. */
29
29
  type DesktopHostOptions<Principal, Window extends NativeWindow> = {
30
30
  clientRoot: string;
31
+ /**
32
+ * Developer app only: a loopback UI dev server origin to proxy client requests to,
33
+ * instead of serving `clientRoot` (see client-dev-proxy.ts). Never set it for a release.
34
+ */
35
+ clientDevOrigin?: string;
31
36
  /** Stream only when the client root is immutable; defaults to buffered snapshots. */
32
37
  streamClientAssets?: boolean;
33
38
  /** Streamed asset files held open at once (1-1024, default 32); later readers wait. */
@@ -1,6 +1,7 @@
1
+ import { proxyClientDevRequest, resolveClientDevOrigin } from "./client-dev-proxy.js";
1
2
  import { errorCode } from "../app/value-guards.js";
2
- import { publishDesktopPort } from "./desktop-port-file.js";
3
3
  import { createClientAssetFileLimit, createClientAssetVerificationCache } from "./client-asset-stream.js";
4
+ import { publishDesktopPort } from "./desktop-port-file.js";
4
5
  import { createClientAssetResolver } from "./client-assets.js";
5
6
  import { createChannelAuthority } from "./channel-handshake.js";
6
7
  import { createDesktopGateway } from "./desktop-gateway.js";
@@ -78,6 +79,8 @@ function createDesktopHost(options, lifecycle) {
78
79
  immutableAssets: options.immutableClientAssets,
79
80
  verificationCache: clientAssetVerificationCache
80
81
  }, options.retainedClientAssets);
82
+ const clientDevOrigin = resolveClientDevOrigin(options.clientDevOrigin, false, "clientDevOrigin");
83
+ const serveClientRequest = clientDevOrigin ? (request) => proxyClientDevRequest(request, clientDevOrigin) : serveAssets;
81
84
  const configuredRoutes = options.routes ?? [];
82
85
  if (!Array.isArray(configuredRoutes) || configuredRoutes.length > 32 || configuredRoutes.some((route) => !route || typeof route.prefix !== "string" || !/^\/[a-zA-Z0-9][a-zA-Z0-9._-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/.test(route.prefix) || route.prefix.length > 200 || route.prefix === "/__framework" || route.prefix.startsWith("/__framework/") || typeof route.handle !== "function" || route.websocket !== void 0 && (typeof route.websocket !== "object" || route.websocket === null || [
83
86
  "open",
@@ -171,7 +174,7 @@ function createDesktopHost(options, lifecycle) {
171
174
  reportRequest(kind);
172
175
  let result;
173
176
  try {
174
- result = lifecycle ? await lifecycle.tracker.handle(() => serveAssets(request)) : await serveAssets(request);
177
+ result = lifecycle ? await lifecycle.tracker.handle(() => serveClientRequest(request)) : await serveClientRequest(request);
175
178
  } catch (error) {
176
179
  if (error instanceof ClientResponseLifecycleClosedError) return new Response(null, { status: 503 });
177
180
  throw error;
@@ -0,0 +1,113 @@
1
+ /**
2
+ * The developer app: one persistent, hot-reloading desktop app per framework app that
3
+ * runs straight from the developer's checkout. With GitButler the checkout is every
4
+ * applied branch merged together, so the window always shows the combined state of all
5
+ * parallel work, with no build or publish step. It replaces dev releases: a public app
6
+ * ships only daily and stable.
7
+ *
8
+ * - The UI comes from the app's dev server (Vite), proxied by the shell, so client
9
+ * edits hot-reload in place (see `client-dev-proxy.ts`).
10
+ * - Shell source edits restart the shell process.
11
+ * - It is its own app: "<Name> (Dev)", identifier "<identifier>.live", its own data
12
+ * folder and port, so it runs beside an installed copy of the public app.
13
+ * - `installDeveloperAppLauncher` adds a small launcher app (Spotlight, Launchpad,
14
+ * Dock) that starts it from the checkout.
15
+ */
16
+ import { type ChildProcess } from 'node:child_process';
17
+ /** Set for every developer app build and run; the build hook and the shell read it. */
18
+ export declare const DEVELOPER_APP_VARIABLE = "ADEA_DEVELOPER_APP";
19
+ /** The developer app's display name, for the build hook's bundle naming. */
20
+ export declare const DEVELOPER_APP_NAME_VARIABLE = "ADEA_DEVELOPER_APP_NAME";
21
+ export type DeveloperAppConfig = {
22
+ /** The public app's name; the developer app is "<name> (Dev)". */
23
+ name: string;
24
+ /** The public app's bundle identifier; the developer app adds ".live". */
25
+ identifier: string;
26
+ /** The Electrobun project (where electrobun.config.ts lives). */
27
+ shellDirectory: string;
28
+ /** Shell source folders whose edits restart the shell (relative to shellDirectory). */
29
+ watch?: readonly string[];
30
+ /** The UI dev server: run in `directory`, serving `port` on 127.0.0.1. */
31
+ ui: {
32
+ directory: string;
33
+ command: readonly string[];
34
+ port: number;
35
+ /** Paths fetched once before the window opens, so the first compile happens early. */
36
+ warm?: readonly string[];
37
+ env?: Readonly<Record<string, string>>;
38
+ };
39
+ /** Extra environment for the shell; the runner adds the developer app variables. */
40
+ shellEnv?: Readonly<Record<string, string>>;
41
+ /** Commands to run in shellDirectory before the shell starts (staging, codegen). */
42
+ prepare?: readonly (readonly string[])[];
43
+ /** A square PNG (at least 512 px) used as the developer app and launcher icon. */
44
+ icon?: string;
45
+ };
46
+ export type DeveloperAppIdentity = {
47
+ name: string;
48
+ identifier: string;
49
+ /** `.noindex` keeps Spotlight from listing the build as a second app. */
50
+ buildFolder: string;
51
+ /** The iconset the runner stages from `icon`, relative to shellDirectory. */
52
+ icons: string;
53
+ };
54
+ /** Check a developer app config, resolving its paths against `base`. */
55
+ export declare function parseDeveloperAppConfig(value: unknown, base: string): DeveloperAppConfig;
56
+ /** Read and check a developer app config file (JSON); paths resolve from its folder. */
57
+ export declare function readDeveloperAppConfig(path: string): DeveloperAppConfig;
58
+ /** The developer app's own identity, kept apart from the public app's. */
59
+ export declare function developerAppIdentity(app: {
60
+ name: string;
61
+ identifier: string;
62
+ }): {
63
+ name: string;
64
+ identifier: string;
65
+ buildFolder: string;
66
+ icons: string;
67
+ };
68
+ /** Whether this process builds or runs the developer app. */
69
+ export declare const isDeveloperApp: (env?: Record<string, string | undefined>) => boolean;
70
+ /**
71
+ * Electrobun names a non-stable bundle `${name}-${channel}.app` and cannot be told
72
+ * otherwise. This moves the bundle to "<Name> (Dev).app" (the name macOS shows in
73
+ * Finder, Activity Monitor and permission prompts) and leaves a relative symlink at the
74
+ * channel path, which `electrobun dev` launches and rebuilds through. Returns the
75
+ * bundle path, or undefined when there is no bundle.
76
+ */
77
+ export declare function nameDeveloperBundle(buildDir: string, appName: string, displayName: string): string | undefined;
78
+ /** The build hook's developer app step (macOS): bundle and Info.plist named "<Name> (Dev)". */
79
+ export declare function finishDeveloperBundle(env?: Record<string, string | undefined>): string | undefined;
80
+ /**
81
+ * Debounced shell restarts: a shell source edit restarts the running shell. An edit
82
+ * before the shell's first start is ignored, because that start builds current files.
83
+ */
84
+ export declare function createShellRestarter(options: {
85
+ currentShell: () => ChildProcess | undefined;
86
+ /** Stop `shell` and start a new one; resolves once the replacement has started. */
87
+ restart: (shell: ChildProcess) => Promise<void>;
88
+ delayMs?: number;
89
+ log?: (message: string) => void;
90
+ }): (file: string | null) => void;
91
+ /** The shell environment for a developer app run. */
92
+ export declare function developerAppShellEnv(config: DeveloperAppConfig, env?: Record<string, string | undefined>): Record<string, string | undefined>;
93
+ /**
94
+ * Run the developer app from the checkout until its window closes or the process is
95
+ * stopped: the UI dev server first, then the shell once the dev server answers.
96
+ */
97
+ export declare function runDeveloperApp(config: DeveloperAppConfig, options?: {
98
+ log?: (line: string) => void;
99
+ }): Promise<never>;
100
+ /**
101
+ * Install the developer app's launcher (macOS): "<Name> (Dev).app" in `directory`
102
+ * (default /Applications), which runs `command` from `checkout` in a login shell, so it
103
+ * finds bun on the same PATH as a terminal. Output goes to ~/Library/Logs/<Name> (Dev).log.
104
+ */
105
+ export declare function installDeveloperAppLauncher(options: {
106
+ config: DeveloperAppConfig;
107
+ checkout: string;
108
+ command: readonly string[];
109
+ directory?: string;
110
+ }): {
111
+ app: string;
112
+ log: string;
113
+ };