@adea-ai/app-framework 0.47.0 → 0.48.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
@@ -117,6 +117,7 @@ fails if a library module gains a top-level statement.
117
117
  | Appearance | `appearance-host`, `appearance-preferences`, `appearance-surface`, `custom-theme-library`, `window-surface` (all _solid_) |
118
118
  | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-detection`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `bounded-body`, `open-url-channel`, `client-asset-manifest`, `client-assets` (source only), `client-dev-proxy` |
119
119
  | 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`, `electrobun-types` (ambient types only) |
120
+ | Voice | `voice` (_solid_: the voice client, the Voice settings section, dictation and read-aloud controls), `voice-host` (the shell service over `@adea-ai/voice/desktop`), `voice-build` (stage and verify the pinned Voice helpers) |
120
121
  | Native installers | `windows-extractor-build`, `installer-archive`, `window-surface-store` |
121
122
  | 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`, `update-adapter` (_solid_), `release-version` (_solid_), `update-state` (source only), `update-helper.js` (bundled helper) |
122
123
  | 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` |
@@ -1 +1 @@
1
- {"version":"0.47.0","commit":"1ccaa0f561b66ed102c8102ae750584c685fb16d"}
1
+ {"version":"0.48.0","commit":"b96e5139ca262974cd8958271ee60c72b5287c1c"}
@@ -0,0 +1,62 @@
1
+ import { type DesktopHelperPaths, type HelperName, type HelperTarget, type StagedHelperRecord } from '@adea-ai/voice/desktop';
2
+ export declare const VOICE_HELPER_LOCK = "voice-helpers.lock.json";
3
+ /** Written instead of helpers when a development build could not stage them. */
4
+ export declare const VOICE_UNAVAILABLE_RECORD = "voice-unavailable.json";
5
+ export type StageAppVoiceOptions = Readonly<{
6
+ /** The desktop app root that holds `voice-helpers.lock.json`. */
7
+ appRoot: string;
8
+ /** The shell build input the bundle copies (for example `build/voice-helpers`). */
9
+ outDir: string;
10
+ mode: 'release' | 'development';
11
+ target?: HelperTarget;
12
+ helpers?: readonly HelperName[];
13
+ cacheDir?: string;
14
+ env?: Readonly<Record<string, string | undefined>>;
15
+ log?: (message: string) => void;
16
+ }>;
17
+ export type StageAppVoiceResult = Readonly<{
18
+ status: 'staged';
19
+ record: StagedHelperRecord;
20
+ }> | Readonly<{
21
+ status: 'unavailable';
22
+ reason: string;
23
+ }> | Readonly<{
24
+ status: 'skipped';
25
+ reason: string;
26
+ }>;
27
+ export declare function stageAppVoiceHelpers(options: StageAppVoiceOptions): Promise<StageAppVoiceResult>;
28
+ /** Every symlink under `dir`, relative to it. */
29
+ export declare function voiceHelperSymlinks(dir: string): string[];
30
+ /**
31
+ * The release gate over the packaged directory. Throws `HelperLockError` on any difference.
32
+ *
33
+ * Signature-independent: the app build signs the helpers again, and the SDK compares their code
34
+ * digest with the lock (or the staged record) instead of the file sha256. It also refuses
35
+ * symlinks and flattened framework files, and launches each helper on a matching machine
36
+ * (`handshake`, default on), requiring the lock's release.
37
+ */
38
+ export declare function verifyAppVoiceHelpers(options: {
39
+ appRoot: string;
40
+ dir: string;
41
+ target?: HelperTarget;
42
+ handshake?: boolean;
43
+ }): void;
44
+ /**
45
+ * The release gate over a built app archive (`stable-macos-<arch>-<App>.app.tar.zst`): extracts
46
+ * `<App>.app/Contents/Resources/app/voice-helpers` and runs `verifyAppVoiceHelpers` on it. The
47
+ * archive is the full app; the stable `build/` app is the self-extracting wrapper. A symlink entry
48
+ * fails the gate before anything is extracted. Returns how many entries were checked.
49
+ */
50
+ export declare function verifyArchivedVoiceHelpers(options: {
51
+ appRoot: string;
52
+ archive: string;
53
+ /** The bundle name, e.g. `Adea` for `Adea.app`. */
54
+ appName: string;
55
+ target?: HelperTarget;
56
+ handshake?: boolean;
57
+ env?: NodeJS.ProcessEnv;
58
+ }): number;
59
+ /** Where the running shell finds its helpers, and why voice is off when they are absent. */
60
+ export declare function resolveVoiceHelperPaths(dir: string): DesktopHelperPaths & {
61
+ unavailable?: string;
62
+ };
@@ -0,0 +1,247 @@
1
+ import { join, relative, resolve } from "node:path";
2
+ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
3
+ import { spawnSync } from "node:child_process";
4
+ import { tmpdir } from "node:os";
5
+ import { HelperLockError, currentHelperTarget, readHelperLock, stageVoiceHelpers, verifyStagedVoiceHelpers } from "@adea-ai/voice/desktop";
6
+ // src/voice/voice-build.ts
7
+ /**
8
+ * Build-time voice helpers for a framework app: stage the helpers its lock pins into the shell's
9
+ * build input, and gate a release on the packaged copy. The lock, artifact format and digest
10
+ * checks are `@adea-ai/voice/desktop`'s; this adds the app conventions:
11
+ *
12
+ * - the lock is `voice-helpers.lock.json` in the desktop app's root;
13
+ * - a release build stages from the lock or fails (no fallback, no compiling speech code);
14
+ * - a development build that cannot stage (offline, an unreleased pin) stages nothing and records
15
+ * why, so the running shell reports voice as explicitly unavailable instead of guessing;
16
+ * - `ADEA_VOICE_HELPER_DIR` points a development build at locally packaged helpers
17
+ * (`scripts/package-release-helpers.sh` in the voice repo); a release refuses them;
18
+ * - a staged helper tree must hold no symlinks: Electrobun's copy stage turns each one into an
19
+ * empty file, so a helper that needs one (a framework's `Versions/Current`) cannot start in the
20
+ * packaged app. A release fails on one; a development build says so loudly.
21
+ *
22
+ * The release gate (`verifyAppVoiceHelpers`, `verifyArchivedVoiceHelpers`) is the SDK's: the
23
+ * packaged helpers are signed again by the app build, so it compares their signature-independent
24
+ * code digest, not the file sha256, and it launches each one (`--version`) to require the pinned
25
+ * release.
26
+ */
27
+ var VOICE_HELPER_LOCK = "voice-helpers.lock.json";
28
+ /** Written instead of helpers when a development build could not stage them. */
29
+ var VOICE_UNAVAILABLE_RECORD = "voice-unavailable.json";
30
+ async function stageAppVoiceHelpers(options) {
31
+ const log = options.log ?? (() => void 0);
32
+ const outDir = resolve(options.outDir);
33
+ const target = options.target ?? currentHelperTarget();
34
+ rmSync(outDir, {
35
+ recursive: true,
36
+ force: true
37
+ });
38
+ if (!target) return {
39
+ status: "skipped",
40
+ reason: "no voice helpers are published for this platform"
41
+ };
42
+ const lockPath = join(options.appRoot, VOICE_HELPER_LOCK);
43
+ const localDir = options.env?.ADEA_VOICE_HELPER_DIR;
44
+ if (localDir && options.mode === "release") throw new HelperLockError("ADEA_VOICE_HELPER_DIR is set: a release never packages a local helper");
45
+ if (!existsSync(lockPath) && localDir) {
46
+ const helpers = (options.helpers ?? [
47
+ "adea-voice-helper",
48
+ "adea-transcribe-helper",
49
+ "adea-tts-helper"
50
+ ]).filter((name) => existsSync(join(localDir, name)));
51
+ const record = await stageVoiceHelpers({
52
+ lock: {
53
+ schema: 1,
54
+ version: "0.0.0",
55
+ base: "https://localhost/",
56
+ helpers: {}
57
+ },
58
+ target,
59
+ outDir,
60
+ helpers,
61
+ localDir,
62
+ log
63
+ });
64
+ assertNoSymlinks(outDir, options.mode, log);
65
+ return {
66
+ status: "staged",
67
+ record
68
+ };
69
+ }
70
+ if (!existsSync(lockPath)) {
71
+ if (options.mode === "release") throw new HelperLockError(`${lockPath} is missing: a release must pin its Voice helpers`);
72
+ const reason = `no ${VOICE_HELPER_LOCK} in ${options.appRoot}`;
73
+ mkdirSync(outDir, { recursive: true });
74
+ writeFileSync(join(outDir, VOICE_UNAVAILABLE_RECORD), `${JSON.stringify({
75
+ target,
76
+ reason
77
+ }, null, 2)}\n`);
78
+ log(`voice helpers unavailable in this development build: ${reason}`);
79
+ return {
80
+ status: "unavailable",
81
+ reason
82
+ };
83
+ }
84
+ const lock = readHelperLock(lockPath);
85
+ const pinned = Object.keys(lock.helpers).filter((name) => lock.helpers[name]?.[target] !== void 0);
86
+ const helpers = options.helpers ?? pinned;
87
+ if (helpers.length === 0) return {
88
+ status: "skipped",
89
+ reason: `the lock pins no helper for ${target}`
90
+ };
91
+ try {
92
+ const record = await stageVoiceHelpers({
93
+ lock,
94
+ target,
95
+ outDir,
96
+ helpers,
97
+ ...options.cacheDir ? { cacheDir: options.cacheDir } : {},
98
+ ...localDir ? { localDir } : {},
99
+ log
100
+ });
101
+ assertNoSymlinks(outDir, options.mode, log);
102
+ return {
103
+ status: "staged",
104
+ record
105
+ };
106
+ } catch (error) {
107
+ if (options.mode === "release") throw error;
108
+ const reason = error instanceof Error ? error.message : String(error);
109
+ mkdirSync(outDir, { recursive: true });
110
+ writeFileSync(join(outDir, VOICE_UNAVAILABLE_RECORD), `${JSON.stringify({
111
+ version: lock.version,
112
+ target,
113
+ reason
114
+ }, null, 2)}\n`);
115
+ log(`voice helpers unavailable in this development build: ${reason}`);
116
+ return {
117
+ status: "unavailable",
118
+ reason
119
+ };
120
+ }
121
+ }
122
+ /** Every symlink under `dir`, relative to it. */
123
+ function voiceHelperSymlinks(dir) {
124
+ const found = [];
125
+ const walk = (current) => {
126
+ for (const name of readdirSync(current)) {
127
+ const path = join(current, name);
128
+ const stat = lstatSync(path);
129
+ if (stat.isSymbolicLink()) found.push(relative(dir, path));
130
+ else if (stat.isDirectory()) walk(path);
131
+ }
132
+ };
133
+ if (existsSync(dir)) walk(dir);
134
+ return found.toSorted();
135
+ }
136
+ /**
137
+ * The bundle's copy stage does not keep symlinks, so a staged helper tree with one ships broken.
138
+ * A release throws (the staging catch then removes nothing a release could package: it rethrows);
139
+ * a development build logs it loudly and keeps the helpers that do not need them.
140
+ */
141
+ function assertNoSymlinks(outDir, mode, log) {
142
+ const links = voiceHelperSymlinks(outDir);
143
+ if (links.length === 0) return;
144
+ const message = `the staged voice helpers contain symlinks, which the app bundle's copy turns into empty files (a helper that needs one will not start): ${links.join(", ")}`;
145
+ if (mode === "release") {
146
+ rmSync(outDir, {
147
+ recursive: true,
148
+ force: true
149
+ });
150
+ throw new HelperLockError(`${message}. Pin a Voice release that ships without symlinks (0.2.1 or later)`);
151
+ }
152
+ log(`WARNING: ${message}`);
153
+ }
154
+ /**
155
+ * The release gate over the packaged directory. Throws `HelperLockError` on any difference.
156
+ *
157
+ * Signature-independent: the app build signs the helpers again, and the SDK compares their code
158
+ * digest with the lock (or the staged record) instead of the file sha256. It also refuses
159
+ * symlinks and flattened framework files, and launches each helper on a matching machine
160
+ * (`handshake`, default on), requiring the lock's release.
161
+ */
162
+ function verifyAppVoiceHelpers(options) {
163
+ const target = options.target ?? currentHelperTarget();
164
+ if (!target) return;
165
+ const lock = readHelperLock(join(options.appRoot, VOICE_HELPER_LOCK));
166
+ const helpers = Object.keys(lock.helpers).filter((name) => lock.helpers[name]?.[target] !== void 0);
167
+ if (existsSync(join(options.dir, "voice-unavailable.json"))) throw new HelperLockError(`${options.dir} has no voice helpers: ${readUnavailable(options.dir) ?? "not staged"}`);
168
+ verifyStagedVoiceHelpers({
169
+ lock,
170
+ target,
171
+ dir: options.dir,
172
+ helpers,
173
+ ...options.handshake !== void 0 ? { handshake: options.handshake } : {}
174
+ });
175
+ }
176
+ /**
177
+ * The release gate over a built app archive (`stable-macos-<arch>-<App>.app.tar.zst`): extracts
178
+ * `<App>.app/Contents/Resources/app/voice-helpers` and runs `verifyAppVoiceHelpers` on it. The
179
+ * archive is the full app; the stable `build/` app is the self-extracting wrapper. A symlink entry
180
+ * fails the gate before anything is extracted. Returns how many entries were checked.
181
+ */
182
+ function verifyArchivedVoiceHelpers(options) {
183
+ const prefix = `${options.appName}.app/Contents/Resources/app/voice-helpers/`;
184
+ const tar = (args) => {
185
+ const result = spawnSync("tar", ["--zstd", ...args], {
186
+ encoding: "utf8",
187
+ maxBuffer: 536870912,
188
+ timeout: 12e4,
189
+ ...options.env ? { env: options.env } : {}
190
+ });
191
+ if (result.error || result.status !== 0) throw new HelperLockError(`cannot read ${options.archive}: ${result.error?.message ?? result.stderr}`);
192
+ return result.stdout;
193
+ };
194
+ const members = tar(["-tf", options.archive]).split(/\r?\n/).filter(Boolean).filter((entry) => entry.replace(/^\.\//, "").startsWith(prefix));
195
+ if (members.length === 0) throw new HelperLockError(`${options.archive} has no voice helpers (${prefix})`);
196
+ const links = tar([
197
+ "-tvf",
198
+ options.archive,
199
+ ...members
200
+ ]).split(/\r?\n/).filter((line) => line.startsWith("l"));
201
+ if (links.length > 0) throw new HelperLockError(`${options.archive} packages symlinks among the voice helpers: ${links.join("; ")}`);
202
+ const scratch = mkdtempSync(join(tmpdir(), "adea-voice-archive-"));
203
+ try {
204
+ tar([
205
+ "-xf",
206
+ options.archive,
207
+ "-C",
208
+ scratch,
209
+ ...members
210
+ ]);
211
+ verifyAppVoiceHelpers({
212
+ appRoot: options.appRoot,
213
+ dir: join(scratch, prefix),
214
+ ...options.target ? { target: options.target } : {},
215
+ ...options.handshake !== void 0 ? { handshake: options.handshake } : {}
216
+ });
217
+ } finally {
218
+ rmSync(scratch, {
219
+ recursive: true,
220
+ force: true
221
+ });
222
+ }
223
+ return members.length;
224
+ }
225
+ /** Where the running shell finds its helpers, and why voice is off when they are absent. */
226
+ function resolveVoiceHelperPaths(dir) {
227
+ const at = (name) => {
228
+ const path = join(dir, name);
229
+ return existsSync(path) ? path : null;
230
+ };
231
+ const unavailable = readUnavailable(dir);
232
+ return {
233
+ voice: at("adea-voice-helper"),
234
+ transcribe: at("adea-transcribe-helper"),
235
+ tts: at("adea-tts-helper"),
236
+ ...unavailable ? { unavailable } : {}
237
+ };
238
+ }
239
+ function readUnavailable(dir) {
240
+ try {
241
+ const record = JSON.parse(readFileSync(join(dir, VOICE_UNAVAILABLE_RECORD), "utf8"));
242
+ return typeof record.reason === "string" ? record.reason : "the voice helpers were not staged";
243
+ } catch {
244
+ return;
245
+ }
246
+ }
247
+ export { VOICE_HELPER_LOCK, VOICE_UNAVAILABLE_RECORD, resolveVoiceHelperPaths, stageAppVoiceHelpers, verifyAppVoiceHelpers, verifyArchivedVoiceHelpers, voiceHelperSymlinks };
@@ -0,0 +1,130 @@
1
+ /**
2
+ * The renderer's voice client: one interface the shared Voice view, the dictation button and the
3
+ * read-aloud action use, whether the app runs in the desktop shell (the helpers, over the voice
4
+ * services) or in a browser (`@adea-ai/voice/web`). The person's choices live in a per-device
5
+ * settings store; every call sends the current settings, so the shell never caches a stale choice.
6
+ */
7
+ import { type VoiceProviderAvailability, type VoiceProviderKind, type VoiceRoutingDecision } from '@adea-ai/voice/contract';
8
+ import { type VoiceSettingsStorage, type VoiceSettingsStore } from '@adea-ai/voice/settings';
9
+ import { type VoiceServiceName, type VoiceSpeechVoice } from './voice-protocol';
10
+ export type VoicePlatformKind = 'desktop' | 'web';
11
+ export type VoicePermission = Readonly<{
12
+ state: 'granted' | 'denied' | 'prompt' | 'unavailable';
13
+ microphone: string;
14
+ speech: string;
15
+ }>;
16
+ export type VoiceProviderStatus = Readonly<{
17
+ id: string;
18
+ displayName: string;
19
+ kind: VoiceProviderKind;
20
+ bundled: boolean;
21
+ availability: VoiceProviderAvailability;
22
+ }>;
23
+ export type VoiceLocalModel = Readonly<{
24
+ path: string;
25
+ architecture: string;
26
+ variant: string;
27
+ languages: readonly string[];
28
+ streaming: boolean;
29
+ }>;
30
+ export type VoiceCapabilitiesView = Readonly<{
31
+ platform: VoicePlatformKind;
32
+ speechToText: VoiceRoutingDecision;
33
+ textToSpeech: VoiceRoutingDecision;
34
+ providers: readonly VoiceProviderStatus[];
35
+ permission: VoicePermission;
36
+ localModels: readonly VoiceLocalModel[];
37
+ }>;
38
+ export type VoiceInfo = Readonly<{
39
+ id: string;
40
+ name: string;
41
+ locale: string;
42
+ quality: string;
43
+ provider: string;
44
+ }>;
45
+ export type LocaleAssetView = Readonly<{
46
+ locale: string;
47
+ status: string;
48
+ canInstall: boolean;
49
+ }>;
50
+ /** What removing a language's model did, and the state the system reports afterwards. */
51
+ export type ReleasedAssetView = Readonly<{
52
+ locale: string;
53
+ /** The model's own locale (`es-MX` for `es-419`). */
54
+ modelLocale: string;
55
+ /** False when this app held no claim on the model. */
56
+ released: boolean;
57
+ /** Usually `notInstalled`; a model shared with system dictation can stay `installed`. */
58
+ status: string;
59
+ canInstall: boolean;
60
+ }>;
61
+ export type DictationHandle = Readonly<{
62
+ /** Resolves with the final text; rejects with a `VoiceError` (`cancelled`, `no_speech`, …). */
63
+ result: Promise<string>;
64
+ end(): Promise<void>;
65
+ cancel(): Promise<void>;
66
+ }>;
67
+ export type SpeechHandle = Readonly<{
68
+ id: string;
69
+ /**
70
+ * Resolves when audio starts, with the voice speaking when the shell reports it; undefined when
71
+ * the utterance ended before it started. Desktop only.
72
+ */
73
+ started?: Promise<Readonly<{
74
+ voice?: VoiceSpeechVoice;
75
+ }> | undefined>;
76
+ /** Resolves when the utterance finishes or is cancelled; rejects with a `VoiceError`. */
77
+ done: Promise<'finished' | 'cancelled'>;
78
+ cancel(): Promise<void>;
79
+ }>;
80
+ export type InstallHandle = Readonly<{
81
+ done: Promise<void>;
82
+ cancel(): Promise<void>;
83
+ }>;
84
+ export interface VoiceClient {
85
+ readonly platform: VoicePlatformKind;
86
+ readonly settings: VoiceSettingsStore;
87
+ capabilities(locale?: string): Promise<VoiceCapabilitiesView>;
88
+ permission(request?: boolean): Promise<VoicePermission>;
89
+ dictate(options?: {
90
+ readonly onPartial?: (text: string) => void;
91
+ readonly locale?: string;
92
+ }): Promise<DictationHandle>;
93
+ speak(text: string, options?: {
94
+ readonly locale?: string;
95
+ }): Promise<SpeechHandle>;
96
+ stopSpeaking(): Promise<void>;
97
+ voices(locale?: string): Promise<readonly VoiceInfo[]>;
98
+ /** Apple's installable dictation languages (desktop macOS); empty elsewhere. */
99
+ locales(): Promise<readonly LocaleAssetView[]>;
100
+ installAssets(locale: string, onProgress?: (fraction: number | null) => void): Promise<InstallHandle>;
101
+ /**
102
+ * Removes an installed Apple dictation language (desktop macOS): this app releases its claim on
103
+ * the model and the OS may delete it. `unavailable` elsewhere.
104
+ */
105
+ releaseAssets(locale: string): Promise<ReleasedAssetView>;
106
+ /** Folder picker for BYOM model folders, when the host has one. */
107
+ readonly pickFolder?: () => Promise<string | undefined>;
108
+ dispose(): void;
109
+ }
110
+ /** What a desktop shell transport provides: invoke a named service, get its value or a typed error. */
111
+ export type VoiceTransport = Readonly<{
112
+ invoke(name: VoiceServiceName, input: unknown): Promise<unknown>;
113
+ }>;
114
+ /**
115
+ * A renderer client over a desktop shell. `transport.invoke` must reject with an error whose
116
+ * `code` is the shell's typed error code (a framework `ServiceError` result, or Adea's command
117
+ * error); it is normalised into `VoiceError`.
118
+ */
119
+ export declare function createDesktopVoiceClient(options: {
120
+ readonly transport: VoiceTransport;
121
+ readonly storage?: VoiceSettingsStorage;
122
+ readonly pickFolder?: () => Promise<string | undefined>;
123
+ }): VoiceClient;
124
+ /**
125
+ * A renderer client for a browser build: on-device browser dictation (the network service only
126
+ * with the person's consent and never in offline-only mode) and platform voices for read-aloud.
127
+ */
128
+ export declare function createWebVoiceClient(options?: {
129
+ readonly storage?: VoiceSettingsStorage;
130
+ }): VoiceClient;