@adea-ai/app-framework 0.46.12 → 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.
Files changed (65) hide show
  1. package/README.md +2 -1
  2. package/dist/app/application.d.ts +2 -1
  3. package/dist/app/application.js +27 -16
  4. package/dist/app/create-application.js +6 -3
  5. package/dist/appearance/appearance-host.d.ts +2 -1
  6. package/dist/appearance/appearance-host.js +28 -21
  7. package/dist/appearance/editor.js +21 -3
  8. package/dist/framework-source.json +1 -1
  9. package/dist/shell/app-shell.d.ts +1 -1
  10. package/dist/shell/app-shell.js +97 -87
  11. package/dist/shell/app-utilities.d.ts +1 -1
  12. package/dist/shell/app-utilities.js +42 -23
  13. package/dist/shell/media-query.js +12 -10
  14. package/dist/shell/navigation-drawer.d.ts +1 -1
  15. package/dist/shell/navigation-drawer.js +6 -4
  16. package/dist/shell/poll.js +9 -11
  17. package/dist/shell/settings-sections.d.ts +1 -1
  18. package/dist/views/app-about.d.ts +1 -1
  19. package/dist/views/app-about.js +1 -1
  20. package/dist/views/app-appearance.d.ts +2 -1
  21. package/dist/views/app-appearance.js +4 -4
  22. package/dist/views/app-help.d.ts +1 -1
  23. package/dist/views/app-help.js +1 -1
  24. package/dist/views/app-settings.d.ts +2 -1
  25. package/dist/views/app-settings.js +15 -10
  26. package/dist/views/appearance-surface.d.ts +1 -1
  27. package/dist/views/appearance-surface.js +116 -91
  28. package/dist/views/update-surface.d.ts +1 -1
  29. package/dist/views/update-surface.js +1 -1
  30. package/dist/voice/voice-build.d.ts +62 -0
  31. package/dist/voice/voice-build.js +247 -0
  32. package/dist/voice/voice-client.d.ts +130 -0
  33. package/dist/voice/voice-client.js +405 -0
  34. package/dist/voice/voice-controls.d.ts +43 -0
  35. package/dist/voice/voice-controls.js +313 -0
  36. package/dist/voice/voice-host.d.ts +29 -0
  37. package/dist/voice/voice-host.js +248 -0
  38. package/dist/voice/voice-protocol.d.ts +127 -0
  39. package/dist/voice/voice-protocol.js +120 -0
  40. package/dist/voice/voice-settings.d.ts +15 -0
  41. package/dist/voice/voice-settings.js +1095 -0
  42. package/dist/voice/voice.d.ts +5 -0
  43. package/dist/voice/voice.js +5 -0
  44. package/package.json +32 -14
  45. package/src/app/application.tsx +28 -32
  46. package/src/appearance/appearance-host.tsx +30 -19
  47. package/src/appearance/editor.ts +25 -3
  48. package/src/shell/app-shell.tsx +46 -37
  49. package/src/shell/app-utilities.tsx +38 -40
  50. package/src/shell/media-query.ts +15 -10
  51. package/src/shell/navigation-drawer.tsx +1 -1
  52. package/src/shell/poll.ts +9 -10
  53. package/src/shell/settings-sections.ts +1 -1
  54. package/src/views/app-appearance.tsx +4 -3
  55. package/src/views/app-settings.tsx +2 -1
  56. package/src/views/appearance-surface.tsx +46 -35
  57. package/src/voice/voice-client.ts +579 -0
  58. package/src/voice/voice-controls.tsx +354 -0
  59. package/src/voice/voice-protocol.ts +189 -0
  60. package/src/voice/voice-settings.tsx +879 -0
  61. package/src/voice/voice.ts +13 -0
  62. package/templates/application/AGENTS.md +29 -0
  63. package/templates/application/src/web/main.tsx +2 -2
  64. package/templates/application/tsconfig.json +1 -1
  65. package/templates/application/vite.config.ts +1 -1
@@ -8,9 +8,9 @@ import { createAppearanceEditor } from "../appearance/editor.js";
8
8
  import { createThemeFileImporter } from "../appearance/theme-file-importer.js";
9
9
  import { createThemeLibraryActionFence } from "../appearance/theme-library-action-fence.js";
10
10
  import { DEFAULT_CUSTOM_ACCENT, allThemeRecords, appearanceThemeForPreview, normalizeCustomAccent } from "../appearance/theme-record-adapter.js";
11
- import { createComponent, effect, insert, mergeProps, setAttribute, template } from "solid-js/web";
12
- import { For, Show, batch, createEffect, createMemo, createSignal, onCleanup, onMount, untrack } from "solid-js";
13
- import { MonitorCog } from "lucide-solid";
11
+ import { createComponent, effect, insert, memo, mergeProps, setAttribute, template } from "@solidjs/web";
12
+ import { For, Show, createEffect, createMemo, createSignal, onCleanup, onSettled, untrack } from "solid-js";
13
+ import { MonitorCog } from "@lucide/solid";
14
14
  import { defaultPreferenceStorage } from "@adea-ai/ui/lib/preference-store";
15
15
  import { isThemeAccentId } from "@adea-ai/ui/lib/themes";
16
16
  import { accents, getAccent } from "@adea-ai/ui/lib/accent-presets";
@@ -21,12 +21,12 @@ import { AppearanceEditor, AppearancePopover } from "@adea-ai/ui/components/comp
21
21
  import { Button } from "@adea-ai/ui/components/ui/button";
22
22
  import { Input } from "@adea-ai/ui/components/ui/input";
23
23
  // src/views/appearance-surface.tsx
24
- var _tmpl$ = /*#__PURE__*/ template(`<p class="text-sm text-muted-foreground"role=status>`);
25
- var _tmpl$2 = /*#__PURE__*/ template(`<ul class="flex flex-col gap-2">`);
26
- var _tmpl$3 = /*#__PURE__*/ template(`<div class="flex flex-col gap-4">`);
27
- var _tmpl$4 = /*#__PURE__*/ template(`<footer class="flex justify-end">`);
28
- var _tmpl$5 = /*#__PURE__*/ template(`<section aria-label=Appearance class="grid gap-4"><header class="flex items-start gap-3"><div><p>Changes preview immediately. Save keeps them; leaving this section without saving restores your previous appearance.`);
29
- var _tmpl$6 = /*#__PURE__*/ template(`<li class="flex items-center gap-2"><span class=font-medium></span><span class="text-sm text-muted-foreground"> · imported `);
24
+ var _tmpl$ = /* @__PURE__ */ template(`<div class="flex flex-col gap-4"><!><!><!>`);
25
+ var _tmpl$2 = /* @__PURE__ */ template(`<footer class="flex justify-end">`);
26
+ var _tmpl$3 = /* @__PURE__ */ template(`<section aria-label=Appearance class="grid gap-4"><header class="flex items-start gap-3"><div><p>Changes preview immediately. Save keeps them; leaving this section without saving restores your previous appearance.`);
27
+ var _tmpl$4 = /* @__PURE__ */ template(`<p class="text-sm text-muted-foreground"role=status>`);
28
+ var _tmpl$5 = /* @__PURE__ */ template(`<ul class="flex flex-col gap-2">`);
29
+ var _tmpl$6 = /* @__PURE__ */ template(`<li class="flex items-center gap-2"><span class=font-medium></span><span class="text-sm text-muted-foreground"> · imported <!>`);
30
30
  var appearanceAccentOptions = Object.freeze(accents.map((accent) => ({ ...accent })));
31
31
  function customAccentValue(accent) {
32
32
  return accent === "theme" || getAccent(accent) || isThemeAccentId(accent) ? "" : accent;
@@ -42,15 +42,14 @@ function AppearanceHost(props) {
42
42
  const appearance = useTheme();
43
43
  const editor = createAppearanceEditor();
44
44
  let catalogueRequested = false;
45
- createEffect(() => {
46
- if (!catalogueRequested && (!props.popover || props.popover.open)) {
45
+ createEffect(() => !props.popover || props.popover.open, (visible) => {
46
+ if (!catalogueRequested && visible) {
47
47
  catalogueRequested = true;
48
48
  appearance.loadCatalogue?.();
49
49
  }
50
50
  });
51
51
  const draftSurface = createMemo(() => editor.draft().surface);
52
- createEffect(() => {
53
- const surface = draftSurface();
52
+ createEffect(draftSurface, (surface) => {
54
53
  mirrorWindowSurface(surface === "translucent" ? "theme" : surface);
55
54
  });
56
55
  const [customAccent, setCustomAccent] = createSignal("");
@@ -58,9 +57,9 @@ function AppearanceHost(props) {
58
57
  const [accentStatus, setAccentStatus] = createSignal("");
59
58
  const [libraryOpen, setLibraryOpen] = createSignal(false);
60
59
  const [library, setLibrary] = createSignal(readCustomThemeLibrary(defaultPreferenceStorage()));
61
- onMount(() => {
60
+ onSettled(() => {
62
61
  setLibrary(readCustomThemeLibrary(defaultPreferenceStorage()));
63
- onCleanup(subscribeCustomThemes(() => setLibrary(customThemes())));
62
+ return subscribeCustomThemes(() => setLibrary(customThemes()));
64
63
  });
65
64
  const themes = createMemo(() => {
66
65
  library();
@@ -79,7 +78,7 @@ function AppearanceHost(props) {
79
78
  const previewPair = createMemo(() => ({
80
79
  lightThemeId: lightThemeId(),
81
80
  darkThemeId: darkThemeId()
82
- }), void 0, { equals: (left, right) => left.lightThemeId === right.lightThemeId && left.darkThemeId === right.darkThemeId });
81
+ }), { equals: (left, right) => left.lightThemeId === right.lightThemeId && left.darkThemeId === right.darkThemeId });
83
82
  const lightPreview = createMemo(() => appearanceThemeForPreview(miniatures().light, draftAccent(), previewPair()));
84
83
  const darkPreview = createMemo(() => appearanceThemeForPreview(miniatures().dark, draftAccent(), previewPair()));
85
84
  const [importStatus, setImportStatus] = createSignal("");
@@ -140,8 +139,12 @@ function AppearanceHost(props) {
140
139
  };
141
140
  });
142
141
  const sampleVariant = () => {
143
- const variants = miniatures();
144
- const mode = editor.draft().mode;
142
+ const draft = editor.draft();
143
+ const variants = draftVariants({
144
+ lightThemeId: draft.lightThemeId,
145
+ darkThemeId: draft.darkThemeId
146
+ });
147
+ const mode = draft.mode;
145
148
  if (mode === "light") return variants.light;
146
149
  if (mode === "dark") return variants.dark;
147
150
  return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-color-scheme: dark)").matches ? variants.dark : variants.light;
@@ -181,7 +184,7 @@ function AppearanceHost(props) {
181
184
  setAccentStatus("");
182
185
  setDraft({ accent: validation.value });
183
186
  };
184
- const onChange = (patch) => batch(() => {
187
+ const onChange = (patch) => {
185
188
  const { accent, surface, ...rest } = patch;
186
189
  const otherChanges = {
187
190
  ...rest,
@@ -192,7 +195,7 @@ function AppearanceHost(props) {
192
195
  return;
193
196
  }
194
197
  setDraft(otherChanges);
195
- });
198
+ };
196
199
  const save = () => {
197
200
  if (accentStatus()) return;
198
201
  if (!editor.dirty()) {
@@ -221,8 +224,10 @@ function AppearanceHost(props) {
221
224
  setAccentStatus("");
222
225
  closeLibrary();
223
226
  };
224
- onMount(openDraft);
225
- onCleanup(revertDraft);
227
+ onSettled(() => {
228
+ openDraft();
229
+ return revertDraft;
230
+ });
226
231
  const editorProps = {
227
232
  get draft() {
228
233
  return publishedDraft();
@@ -276,17 +281,18 @@ function AppearanceHost(props) {
276
281
  return props.popover;
277
282
  },
278
283
  get fallback() {
279
- return (() => {
280
- var _el$5 = _tmpl$5(), _el$6 = _el$5.firstChild, _el$7 = _el$6.firstChild, _el$8 = _el$7.firstChild;
281
- insert(_el$6, createComponent(MonitorCog, { "aria-hidden": "true" }), _el$7);
282
- insert(_el$7, createComponent(Heading, {
283
- as: "h3",
284
- size: "card",
285
- children: "Appearance"
286
- }), _el$8);
287
- insert(_el$5, createComponent(AppearanceEditor, editorProps), null);
288
- return _el$5;
289
- })();
284
+ var _el$6 = _tmpl$3();
285
+ var _el$7 = _el$6.firstChild;
286
+ var _el$8 = _el$7.firstChild;
287
+ var _el$9 = _el$8.firstChild;
288
+ insert(_el$7, createComponent(MonitorCog, { "aria-hidden": "true" }), _el$8);
289
+ insert(_el$8, createComponent(Heading, {
290
+ as: "h3",
291
+ size: "card",
292
+ children: "Appearance"
293
+ }), _el$9);
294
+ insert(_el$6, createComponent(AppearanceEditor, editorProps), null);
295
+ return _el$6;
290
296
  },
291
297
  children: (control) => createComponent(AppearancePopover, mergeProps(editorProps, {
292
298
  triggerVariant: "toolbar",
@@ -325,18 +331,21 @@ function AppearanceHost(props) {
325
331
  onClose: closeLibrary,
326
332
  title: "Manage themes",
327
333
  description: "Import a theme file. Imported themes appear in the Light and Dark theme menus and stay on this device.",
328
- "class": "max-h-full w-full max-w-104 overflow-y-auto",
334
+ class: "max-h-full w-full max-w-104 overflow-y-auto",
329
335
  get children() {
330
336
  return [(() => {
331
- var _el$ = _tmpl$3();
337
+ var _el$ = _tmpl$();
338
+ var _el$2 = _el$.firstChild;
339
+ var _el$3 = _el$2.nextSibling;
340
+ var _el$4 = _el$3.nextSibling;
332
341
  insert(_el$, createComponent(Button, {
333
342
  as: "label",
334
- "class": "w-full",
343
+ class: "w-full",
335
344
  get children() {
336
345
  return [createComponent(Input, {
337
346
  type: "file",
338
347
  accept: ".json,application/json",
339
- "class": "sr-only",
348
+ class: "sr-only",
340
349
  onChange: (event) => {
341
350
  const file = event.currentTarget.files?.[0];
342
351
  event.currentTarget.value = "";
@@ -344,68 +353,84 @@ function AppearanceHost(props) {
344
353
  }
345
354
  }), "Import a theme file (.json)"];
346
355
  }
347
- }), null);
348
- insert(_el$, createComponent(Show, {
349
- get when() {
350
- return importStatus();
351
- },
352
- get children() {
353
- var _el$2 = _tmpl$();
354
- insert(_el$2, importStatus);
355
- effect(() => setAttribute(_el$2, "aria-busy", importPending()));
356
- return _el$2;
357
- }
358
- }), null);
359
- insert(_el$, createComponent(Show, {
360
- get when() {
356
+ }), _el$2);
357
+ insert(_el$, (() => {
358
+ var _c$ = memo(() => {
359
+ return !!importStatus();
360
+ });
361
+ return () => {
362
+ return _c$() ? (() => {
363
+ var _el$10 = _tmpl$4();
364
+ insert(_el$10, importStatus);
365
+ effect(() => importPending() ? "true" : "false", (_v$) => {
366
+ setAttribute(_el$10, "aria-busy", _v$);
367
+ });
368
+ return _el$10;
369
+ })() : void 0;
370
+ };
371
+ })(), _el$3);
372
+ insert(_el$, (() => {
373
+ var _c$2 = memo(() => {
361
374
  return library().length > 0;
362
- },
363
- get children() {
364
- var _el$3 = _tmpl$2();
365
- insert(_el$3, createComponent(For, {
366
- get each() {
367
- return library();
368
- },
369
- children: (theme) => (() => {
370
- var _el$9 = _tmpl$6(), _el$0 = _el$9.firstChild, _el$1 = _el$0.nextSibling, _el$10 = _el$1.firstChild;
371
- insert(_el$0, () => theme.name);
372
- insert(_el$1, () => theme.appearance, _el$10);
373
- insert(_el$1, () => new Date(theme.importedAt).toLocaleDateString(), null);
374
- insert(_el$9, createComponent(Button, {
375
- type: "button",
376
- size: "sm",
377
- variant: "ghost",
378
- onClick: async () => {
379
- const action = themeActionFence.begin();
380
- themeImporter.cancel();
381
- setImportPending(false);
382
- themeActionFence.report(action, "");
383
- const storage = defaultPreferenceStorage();
384
- if (!storage) {
385
- themeActionFence.report(action, "The theme could not be removed. Check your storage and try again.");
386
- return;
387
- }
388
- const result = await removeCustomThemeAtomically(theme.id, storage);
389
- themeActionFence.report(action, result.ok ? result.recovered ? CUSTOM_THEME_LIBRARY_RECOVERED : "" : result.error);
390
- },
391
- children: "Remove"
392
- }), null);
393
- return _el$9;
394
- })()
395
- }));
396
- return _el$3;
397
- }
398
- }), null);
375
+ });
376
+ return () => {
377
+ return _c$2() ? (() => {
378
+ var _el$11 = _tmpl$5();
379
+ insert(_el$11, createComponent(For, {
380
+ get each() {
381
+ return library();
382
+ },
383
+ children: (theme) => (() => {
384
+ var _el$12 = _tmpl$6();
385
+ var _el$13 = _el$12.firstChild;
386
+ var _el$14 = _el$13.nextSibling;
387
+ var _el$15 = _el$14.firstChild;
388
+ var _el$16 = _el$15.nextSibling;
389
+ insert(_el$13, () => {
390
+ return theme.name;
391
+ });
392
+ insert(_el$14, () => {
393
+ return theme.appearance;
394
+ }, _el$15);
395
+ insert(_el$14, () => {
396
+ return new Date(theme.importedAt).toLocaleDateString();
397
+ }, _el$16);
398
+ insert(_el$12, createComponent(Button, {
399
+ type: "button",
400
+ size: "sm",
401
+ variant: "ghost",
402
+ onClick: async () => {
403
+ const action = themeActionFence.begin();
404
+ themeImporter.cancel();
405
+ setImportPending(false);
406
+ themeActionFence.report(action, "");
407
+ const storage = defaultPreferenceStorage();
408
+ if (!storage) {
409
+ themeActionFence.report(action, "The theme could not be removed. Check your storage and try again.");
410
+ return;
411
+ }
412
+ const result = await removeCustomThemeAtomically(theme.id, storage);
413
+ themeActionFence.report(action, result.ok ? result.recovered ? CUSTOM_THEME_LIBRARY_RECOVERED : "" : result.error);
414
+ },
415
+ children: "Remove"
416
+ }), null);
417
+ return _el$12;
418
+ })()
419
+ }));
420
+ return _el$11;
421
+ })() : void 0;
422
+ };
423
+ })(), _el$4);
399
424
  return _el$;
400
425
  })(), (() => {
401
- var _el$4 = _tmpl$4();
402
- insert(_el$4, createComponent(Button, {
426
+ var _el$5 = _tmpl$2();
427
+ insert(_el$5, createComponent(Button, {
403
428
  type: "button",
404
429
  variant: "outline",
405
430
  onClick: () => closeLibrary(),
406
431
  children: "Close"
407
432
  }));
408
- return _el$4;
433
+ return _el$5;
409
434
  })()];
410
435
  }
411
436
  })];
@@ -29,4 +29,4 @@ export type ApplicationUpdateSurfaceProps = {
29
29
  restoreFocusRef?: Accessor<HTMLElement | undefined>;
30
30
  };
31
31
  /** The shared Version & updates dialog, with an optional release-channel control. */
32
- export declare function ApplicationUpdateSurface(props: ApplicationUpdateSurfaceProps): import("solid-js").JSX.Element;
32
+ export declare function ApplicationUpdateSurface(props: ApplicationUpdateSurfaceProps): import("@solidjs/web").JSX.Element;
@@ -1,5 +1,5 @@
1
1
  import { mirrorUpdateState, updateChannelStore } from "../updates/update-adapter.js";
2
- import { createComponent } from "solid-js/web";
2
+ import { createComponent } from "@solidjs/web";
3
3
  import { createMemo } from "solid-js";
4
4
  import { UpdateChannelControl, UpdateDialog } from "@adea-ai/ui/components/composites/update-dialog";
5
5
  // src/views/update-surface.tsx
@@ -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 };