@jxsuite/studio 2.4.2 → 3.0.0

package/src/services/settings/definitions.ts

@@ -0,0 +1,164 @@
+/**
+ * The settings registry — every application setting Studio holds, declared once.
+ *
+ * Before this table the answer to "which settings roam, and what is each one's default" lived in
+ * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each `*-settings.ts`,
+ * a bespoke getter/setter pair beside it, and whatever the getter's `||` happened to fall back to.
+ * Adding a roaming setting meant editing all four and hoping; the key strings themselves were
+ * duplicated between the array and the module that owned them.
+ *
+ * Two properties of this table are load-bearing rather than tidy:
+ *
+ * 1.  **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting
+ *     roams because it says `scope: "user"` — not because someone remembered to add its key to a
+ *     second list. `device` is the honest name for the rest: panel geometry and a palette's MRU
+ *     describe *this window*, and a user with two windows open wants them to differ.
+ * 2.  **A default is not a value.** The default is what a *reader* sees when nothing is stored; it
+ *     is never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form
+ *     prefilled from it, and Save wrote the mask back — which is how an install whose owner had
+ *     configured an entirely different provider was left holding `jx.ai.model: "gpt-4o"` and
+ *     nothing else. {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two
+ *     functions for exactly this reason.
+ *
+ * @license MIT
+ */
+
+/**
+ * Where a setting lives.
+ *
+ * `user` follows the author — every window, every project, and (where the platform has a backend
+ * store) every browser profile the launcher hands out. `device` stays where it was written.
+ */
+export type SettingScope = "user" | "device";
+
+/** One setting, as the registry declares it. */
+export interface SettingDefinition {
+  /** The storage key, in both localStorage and the backend map. */
+  key: string;
+  scope: SettingScope;
+  /** What a reader sees when nothing is stored. Never written — see the module docblock. */
+  default: string;
+  /**
+   * Whether the value is a credential.
+   *
+   * Nothing in the kernel treats a secret differently; the flag is what lets a surface refuse to
+   * print one, a diagnostic dump refuse to include one, and the Accounts list report _that_ one is
+   * held rather than what it is (`specs/studio.md` §15 rule 1).
+   */
+  secret?: boolean;
+  /**
+   * Canonicalise an incoming value before it is stored. Total: it is handed raw user input.
+   *
+   * Applied on write only. A value already on disk is returned as it was found, so a normalizer
+   * that tightens later cannot silently rewrite what someone else stored.
+   */
+  normalize?: (raw: string) => string;
+}
+
+/** Trim, and drop trailing slashes — an endpoint is a base, not a path. */
+function normalizeBaseUrl(raw: string): string {
+  return raw.trim().replace(/\/+$/, "");
+}
+
+/** Trim. Credentials are pasted, and a paste carries whitespace. */
+function trimmed(raw: string): string {
+  return raw.trim();
+}
+
+/**
+ * Every setting, keyed by the name the rest of the app refers to it by.
+ *
+ * Declared `as const satisfies` so each entry keeps its literal `key` for callers while still being
+ * checked against {@link SettingDefinition}.
+ */
+export const SETTINGS = {
+  aiBaseUrl: {
+    default: "",
+    key: "jx.ai.baseUrl",
+    normalize: normalizeBaseUrl,
+    scope: "user",
+  },
+  /**
+   * The provider key. Stays in the settings store rather than moving to the launcher's credential
+   * store: the webview is its legitimate consumer — it sends the key itself as `X-Api-Key` — so
+   * withholding it and then transmitting it would be the same trust boundary with more parts. See
+   * `specs/desktop.md` §3.6, which draws that line.
+   */
+  aiOpenAiKey: {
+    default: "",
+    key: "jx.ai.openaiKey",
+    normalize: trimmed,
+    scope: "user",
+    secret: true,
+  },
+  /**
+   * `"gpt-4o"` is what a sender falls back to, NOT a stored choice. A surface that writes back must
+   * read through `readStoredSetting`, or it persists a model the user never picked.
+   */
+  aiModel: {
+    default: "gpt-4o",
+    key: "jx.ai.model",
+    normalize: trimmed,
+    scope: "user",
+  },
+  /**
+   * The author's rebindings, as a JSON object of `command id → chords`.
+   *
+   * Roams, so a keyboard learned once is the keyboard everywhere. `normalize` is why the field
+   * exists on {@link SettingDefinition}: an empty override map is the absence of an override, and
+   * storing `"{}"` would make every window think a layer had been authored.
+   */
+  keybindings: {
+    default: "",
+    key: "jx.keybindings",
+    normalize: (raw) => (raw.trim() === "{}" ? "" : raw.trim()),
+    scope: "user",
+  },
+  /**
+   * The chrome theme.
+   *
+   * Read at module evaluation, before the first paint — `shell.ts` says a mismatch with the theme
+   * `index.html` hard-codes flashes the shell. That is the reason the kernel keeps a synchronous
+   * cache rather than awaiting the backend.
+   */
+  theme: {
+    default: "",
+    key: "jx-studio-theme",
+    normalize: trimmed,
+    scope: "user",
+  },
+  cfAccountId: {
+    default: "",
+    key: "jx.cf.accountId",
+    normalize: trimmed,
+    scope: "user",
+  },
+  cfToken: {
+    default: "",
+    key: "jx.cf.token",
+    normalize: trimmed,
+    scope: "user",
+    secret: true,
+  },
+} as const satisfies Record<string, SettingDefinition>;
+
+/** The registry's own names — `SETTINGS.aiModel`, not `"jx.ai.model"`. */
+export type SettingName = keyof typeof SETTINGS;
+
+/** Every declared setting, in declaration order. */
+export const ALL_SETTINGS: readonly SettingDefinition[] = Object.values(SETTINGS);
+
+/**
+ * The settings that roam, derived from {@link SETTINGS}.
+ *
+ * This replaces the hand-maintained `PERSISTED_SETTINGS_KEYS`. A setting joins it by declaring
+ * `scope: "user"` and by no other means, so the list cannot fall behind the table it describes.
+ */
+export const USER_SETTINGS: readonly SettingDefinition[] = ALL_SETTINGS.filter(
+  (definition) => definition.scope === "user",
+);
+
+/** The roaming keys as strings — what a backend map is keyed by. */
+export const USER_SETTING_KEYS: readonly string[] = USER_SETTINGS.map(
+  (definition) => definition.key,
+);

package/src/services/settings/kernel.ts

@@ -0,0 +1,335 @@
+/// <reference lib="dom" />
+/**
+ * The settings kernel — one owner for every application setting's value.
+ *
+ * **The model.** The backend store is authoritative, `localStorage` is a synchronous cache of it,
+ * and every write is a per-key patch applied by whoever owns the file. What this replaces collapsed
+ * all three roles: `localStorage` was the truth, and it was mirrored to disk by whole-map replaces
+ * computed from whichever window happened to write last. On the chromium launcher — where every
+ * window is its own process with its own browser profile, and so its own `localStorage` — a window
+ * holding no settings could therefore overwrite the shared file with an almost empty map. Nothing
+ * told the other window it had happened.
+ *
+ * **Why a Map and not just localStorage.** Reads must be synchronous: the chrome theme is read
+ * before the first paint (`shell.ts` says so explicitly — a mismatch flashes the shell), and every
+ * credential gate reads on the render path. But the authoritative copy arrives asynchronously. An
+ * in-memory Map seeded from the cache at module evaluation gives both: correct on the first frame,
+ * and reconciled by {@link hydrateSettings} the moment the backend answers.
+ *
+ * **The one deletion path.** {@link setSetting} with `""` STORES an empty string;
+ * {@link clearSetting} is the only thing that removes. Blank used to mean delete, which read as a
+ * convenience until a form that blanked its own drafts on save called the setters with them — and
+ * pressing Save a second time revoked the credentials the first press had stored. Making blank
+ * unrepresentable as a deletion is what stops that whole class, rather than fixing the one caller.
+ *
+ * @license MIT
+ */
+
+import { getPlatform, hasPlatform } from "../../platform";
+import { notify } from "../notify";
+import { ALL_SETTINGS, USER_SETTINGS } from "./definitions";
+import type { SettingDefinition } from "./definitions";
+import { createWriteQueue } from "./write-queue";
+import type { SettingsPatch } from "./write-queue";
+
+/** The synchronous source of truth. Absent key means unset — which is not the same as `""`. */
+const values = new Map<string, string>();
+
+/** Mirror a value into the cache, so the next boot is correct before the backend answers. */
+function writeCache(key: string, value: string | null): void {
+  try {
+    if (value === null) {
+      globalThis.localStorage?.removeItem(key);
+    } else {
+      globalThis.localStorage?.setItem(key, value);
+    }
+  } catch {
+    /* Storage unavailable (private mode) — the Map still serves this session. */
+  }
+}
+
+/**
+ * Seed from the cache, at module evaluation and before anything can read.
+ *
+ * This is what makes the first frame correct: the chrome theme is read before the first paint, and
+ * `shell.ts` records that a mismatch with the theme `index.html` hard-codes flashes the shell. The
+ * backend's copy arrives later and reconciles through {@link hydrateSettings}.
+ *
+ * One `try` around the whole loop rather than one per key — storage that throws throws for all of
+ * them, and a private-mode window simply starts empty.
+ */
+try {
+  for (const definition of ALL_SETTINGS) {
+    const cached = globalThis.localStorage?.getItem(definition.key);
+    if (cached !== null && cached !== undefined) {
+      values.set(definition.key, cached);
+    }
+  }
+} catch {
+  /* Storage unavailable — the map starts empty, and hydration fills it. */
+}
+
+// ─── Reading ──────────────────────────────────────────────────────────────────
+
+/**
+ * The value the user actually chose — the ONLY read. A default never stands in for silence here.
+ *
+ * There is deliberately no default-masking sibling. One existed, and every bug in this area came
+ * from a caller taking the masked value for a chosen one: a form prefilled with `"gpt-4o"` and
+ * saved it, so an install whose owner had configured a different provider was left holding
+ * `jx.ai.model: "gpt-4o"` and nothing else. A consumer that needs a fallback composes it where the
+ * fallbacks are known — see `ai-models.ts`'s `preferredModel`, which asks the backend what it
+ * prefers before reaching for a name invented here.
+ *
+ * @returns The stored value, or "" when none is stored.
+ */
+export function readStoredSetting(definition: SettingDefinition): string {
+  return values.get(definition.key) ?? "";
+}
+
+/** Whether a value is stored — as distinct from stored-and-empty, or absent-with-a-default. */
+export function hasSetting(definition: SettingDefinition): boolean {
+  return (values.get(definition.key) ?? "") !== "";
+}
+
+// ─── Change notification ──────────────────────────────────────────────────────
+
+const listeners = new Set<(keys: readonly string[]) => void>();
+
+/**
+ * Subscribe to settings changes, local or remote. Returns the unsubscribe.
+ *
+ * This is the seam that lets a surface hold no copy of a setting: the composer's model picker, the
+ * Accounts list and the New Project gates all read through the kernel and repaint on this, rather
+ * than each caching a value that another window can invalidate.
+ */
+export function onSettingsChanged(listener: (keys: readonly string[]) => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Announce the keys that moved. Never called with an empty list. */
+function announce(keys: readonly string[]): void {
+  for (const listener of listeners) {
+    listener(keys);
+  }
+}
+
+// ─── Writing ──────────────────────────────────────────────────────────────────
+
+const queue = createWriteQueue({
+  onError(error: unknown) {
+    notify("error", "Your settings could not be saved.", {
+      detail: error instanceof Error ? error.message : String(error),
+      key: "settings-write",
+      source: "Settings",
+    });
+  },
+  async send(patch: SettingsPatch) {
+    if (!hasPlatform()) {
+      return;
+    }
+    const platform = getPlatform();
+    if (!platform.patchSettings) {
+      return;
+    }
+    /*
+     * Only the keys that actually moved go on the wire. A key this window never touched is one the
+     * backend leaves exactly as it found it — which is what stops a second window's settings being
+     * cleared by a window that happens to hold none of them.
+     *
+     * An empty value is sent as a REMOVAL. The store is what a fresh install reads back at boot, and
+     * `"jx.ai.model": ""` there would be a model choice rather than the absence of one.
+     */
+    const set: Record<string, string> = {};
+    const remove: string[] = [];
+    for (const [key, value] of Object.entries(patch)) {
+      if (value) {
+        set[key] = value;
+      } else {
+        remove.push(key);
+      }
+    }
+    await platform.patchSettings({ remove, set });
+  },
+});
+
+/** Resolves when every settings write made so far has been sent. */
+export function settingsSettled(): Promise<void> {
+  return queue.settled();
+}
+
+/**
+ * Apply a patch: `null` deletes, a string stores. Keys named by neither are untouched.
+ *
+ * Returns the keys that actually moved, so a no-op write announces nothing and schedules nothing.
+ */
+function apply(patch: SettingsPatch): string[] {
+  const moved: string[] = [];
+  for (const [key, next] of Object.entries(patch)) {
+    const before = values.get(key) ?? null;
+    if (before === next) {
+      continue;
+    }
+    if (next === null) {
+      values.delete(key);
+    } else {
+      values.set(key, next);
+    }
+    writeCache(key, next);
+    moved.push(key);
+  }
+  return moved;
+}
+
+/** Store a value. An empty string is a VALUE; {@link clearSetting} is the only deletion. */
+export function setSetting(definition: SettingDefinition, value: string): void {
+  const next = definition.normalize ? definition.normalize(value) : value;
+  const moved = apply({ [definition.key]: next });
+  if (moved.length > 0) {
+    queue.enqueue({ [definition.key]: next });
+    announce(moved);
+  }
+}
+
+/**
+ * Store several settings as one change — one announcement, one write.
+ *
+ * What a form's Save should call. Three separate `setSetting`s would coalesce into one write
+ * anyway, but they would announce three times, and each intermediate announcement describes a state
+ * the user never asked for.
+ */
+export function setSettings(entries: readonly [SettingDefinition, string][]): void {
+  const patch: SettingsPatch = {};
+  for (const [definition, value] of entries) {
+    patch[definition.key] = definition.normalize ? definition.normalize(value) : value;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    queue.enqueue(patch);
+    announce(moved);
+  }
+}
+
+/** Forget several settings as one change — the shape a Disconnect wants. */
+export function clearSettings(definitions: readonly SettingDefinition[]): void {
+  const patch: SettingsPatch = {};
+  for (const definition of definitions) {
+    patch[definition.key] = null;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    queue.enqueue(patch);
+    announce(moved);
+  }
+}
+
+// ─── Hydration ────────────────────────────────────────────────────────────────
+
+/**
+ * Reconcile with the backend store. Call once, after the platform is registered; a no-op on
+ * platforms without one (dev server, cloud), where the cache is all there is.
+ *
+ * Deliberately not awaited by the boot path — hydration must not block the first paint — which is
+ * safe because the Map is already serving cached values by then. Anything the backend holds wins;
+ * anything only this machine holds is pushed up once, so a user upgrading from a cache-only build
+ * does not lose what they had configured.
+ */
+export async function hydrateSettings(): Promise<void> {
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.getSettings) {
+    return;
+  }
+  let stored: Record<string, string>;
+  try {
+    stored = await platform.getSettings();
+  } catch {
+    return;
+  }
+  const incoming: SettingsPatch = {};
+  let needsMigration = false;
+  for (const definition of USER_SETTINGS) {
+    const backendValue = stored[definition.key];
+    if (backendValue) {
+      incoming[definition.key] = backendValue;
+    } else if (values.get(definition.key)) {
+      needsMigration = true;
+    }
+  }
+  const moved = apply(incoming);
+  if (moved.length > 0) {
+    announce(moved);
+  }
+  if (needsMigration) {
+    /* Push this machine's cache-only values up, through the same queue as any other write so it
+       cannot race one the user is making at the same moment. Only the keys the backend lacks — a
+       patch says nothing about the rest, so hydration cannot echo back what it just read. */
+    const push: SettingsPatch = {};
+    for (const definition of USER_SETTINGS) {
+      const value = values.get(definition.key);
+      if (value && !stored[definition.key]) {
+        push[definition.key] = value;
+      }
+    }
+    queue.enqueue(push);
+  }
+}
+
+/**
+ * Adopt the backend store as another window (or a hand-edit) left it.
+ *
+ * Applied and announced, but never written back: this is news, not an edit, and echoing it would
+ * have two windows writing the same value at each other. A key the store no longer holds is
+ * forgotten here too, so a Disconnect in one window reaches the others.
+ *
+ * Self-echo needs no filter. Our own write reaches us through the same watch, and by then the
+ * values already match — {@link apply} reports nothing moved, so nothing is announced.
+ */
+export function adoptRemoteSettings(stored: Record<string, string>): void {
+  const patch: SettingsPatch = {};
+  for (const definition of USER_SETTINGS) {
+    patch[definition.key] = stored[definition.key] ?? null;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    announce(moved);
+  }
+}
+
+/**
+ * Subscribe to the backend store, if this platform can push. A no-op where it cannot.
+ *
+ * Called once at boot. The returned unsubscribe is not used — Studio boots this module once per
+ * window and never unwinds it — so it is deliberately dropped rather than stored somewhere nothing
+ * would read it.
+ */
+export function watchRemoteSettings(): void {
+  if (!hasPlatform()) {
+    return;
+  }
+  getPlatform().subscribeSettings?.(adoptRemoteSettings);
+}
+
+/**
+ * Drop every value this kernel holds, cache included.
+ *
+ * The `?profile=fresh` startup profile's half of the story: clearing `localStorage` alone left the
+ * Map — and the backend store — untouched, so "fresh" was not fresh. This does not write to the
+ * backend, because a clean profile must not destroy credentials that belong to the user rather than
+ * to the profile.
+ */
+export function resetSettings(): void {
+  const moved = [...values.keys()];
+  values.clear();
+  for (const key of moved) {
+    writeCache(key, null);
+  }
+  if (moved.length > 0) {
+    announce(moved);
+  }
+}

package/src/services/settings/write-queue.ts

@@ -0,0 +1,116 @@
+/**
+ * A coalescing, serializing write queue.
+ *
+ * The defect it exists to make unrepresentable: saving a provider mutates three settings through
+ * three setters, and each setter used to fire its own whole-map write. Three overlapping writes went
+ * out against one file, each reading storage at a different moment, with no ordering between them —
+ * so whichever landed last won. That was observed in the wild as a settings file holding
+ * `{"jx.ai.model": "gpt-4o"}`: the SECOND of three snapshots, landing last, a state storage itself
+ * never rested in.
+ *
+ * Two rules, and they are different guarantees:
+ *
+ * 1.  **Coalesce.** Every mutation in one synchronous burst merges into a single patch, sent once
+ *     the burst has finished. N setters produce one write, not N.
+ * 2.  **Serialize.** At most one send is in flight. A mutation made while one is out waits for it
+ *     rather than racing it, so the order the app made changes in is the order the store sees them.
+ *
+ * Generic over the transport so the kernel can hand it a platform call and a test can hand it an
+ * array. `schedule` is injectable for the same reason.
+ *
+ * @license MIT
+ */
+
+/**
+ * A set of changes to apply. `null` DELETES the key; a key named by neither map is left alone.
+ *
+ * That is the whole difference from the whole-map replace this supersedes: a writer that says
+ * nothing about a key cannot destroy it, so a window with a stale or empty view of settings can no
+ * longer clear a sibling window's.
+ */
+export type SettingsPatch = Record<string, string | null>;
+
+export interface WriteQueueOptions {
+  /** Deliver one merged patch. Rejection is reported through {@link WriteQueueOptions.onError}. */
+  send: (patch: SettingsPatch) => Promise<void>;
+  /** Called with the failure and the patch that did not land. */
+  onError?: (error: unknown, patch: SettingsPatch) => void;
+  /**
+   * Defer to the end of the current burst. Defaults to `queueMicrotask`.
+   *
+   * A microtask rather than a timer: the burst is synchronous, so the patch goes out in the same
+   * turn the user acted in, and nothing can observe a half-applied save.
+   */
+  schedule?: (run: () => void) => void;
+}
+
+export interface WriteQueue {
+  /** Merge `patch` into the pending one, scheduling a send if none is pending. */
+  enqueue: (patch: SettingsPatch) => void;
+  /** Resolves when everything enqueued so far has been sent (or has failed and been reported). */
+  settled: () => Promise<void>;
+}
+
+/**
+ * Create a queue over `send`.
+ *
+ * @param {WriteQueueOptions} opts
+ * @returns {WriteQueue}
+ */
+export function createWriteQueue(opts: WriteQueueOptions): WriteQueue {
+  const schedule = opts.schedule ?? queueMicrotask;
+
+  /** Merged changes not yet handed to `send`; null when nothing is waiting. */
+  let pending: SettingsPatch | null = null;
+
+  /**
+   * The chain every send is appended to.
+   *
+   * Always resolved — each link ends in a handler — so one failed write cannot poison the writes
+   * queued behind it.
+   */
+  let tail: Promise<void> = Promise.resolve();
+
+  /**
+   * Resolves when the most recently scheduled burst has been sent.
+   *
+   * Tracked explicitly rather than inferred from {@link tail}: a caller that enqueues and then
+   * awaits would otherwise be awaiting the tail as it stood BEFORE its own patch joined it, and
+   * whether that happens to work depends on how many turns the scheduler takes.
+   */
+  let idle: Promise<void> = Promise.resolve();
+
+  /** Hand the merged burst to `send`, appended to the chain. */
+  function flush(): Promise<void> {
+    const patch = pending;
+    pending = null;
+    if (!patch) {
+      return tail;
+    }
+    tail = tail
+      .then(() => opts.send(patch))
+      .catch((error: unknown) => {
+        opts.onError?.(error, patch);
+      });
+    return tail;
+  }
+
+  return {
+    enqueue(patch: SettingsPatch) {
+      if (pending) {
+        Object.assign(pending, patch);
+        return;
+      }
+      pending = { ...patch };
+      idle = new Promise<void>((resolve) => {
+        schedule(() => {
+          void flush().then(resolve);
+        });
+      });
+    },
+
+    settled() {
+      return idle;
+    },
+  };
+}

package/src/settings/preferences-accounts.ts

@@ -20,15 +20,9 @@
  */
 
 import { clearGithubToken, githubTokenLocation, githubTokenStored } from "../github/github-auth";
-import { getCfAccountId, getCfToken, setCfAccountId, setCfToken } from "../services/cf-settings";
-import {
-  getBaseUrl,
-  getModel,
-  hasOpenAiKey,
-  setBaseUrl,
-  setModel,
-  setOpenAiKey,
-} from "../services/ai-settings";
+import { clearCfConnection, getCfAccountId, getCfToken } from "../services/cf-settings";
+import { clearAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
+import { preferredModel } from "../services/ai-models";
 
 /** One stored credential, as the Accounts section renders it. */
 export interface AccountRecord {
@@ -53,7 +47,7 @@ export function listAccounts(): AccountRecord[] {
   const githubToken = githubTokenStored();
   const cfToken = getCfToken();
   const cfAccount = getCfAccountId();
-  const model = getModel();
+  const model = preferredModel();
   const endpoint = getBaseUrl();
   return [
     {
@@ -74,11 +68,7 @@ export function listAccounts(): AccountRecord[] {
         ? `Key stored. Model ${model}${endpoint ? ` via ${endpoint}` : ""}.`
         : "No key stored. The Assistant section is where one is entered.",
       connected: hasOpenAiKey(),
-      revoke: () => {
-        setOpenAiKey("");
-        setBaseUrl("");
-        setModel("");
-      },
+      revoke: clearAiProvider,
     },
     {
       id: "cloudflare",
@@ -87,10 +77,7 @@ export function listAccounts(): AccountRecord[] {
         ? `Connected${cfAccount ? ` — account ${cfAccount}` : ""}.`
         : "Not connected. Publishing will ask when it needs it.",
       connected: Boolean(cfToken),
-      revoke: () => {
-        setCfToken("");
-        setCfAccountId("");
-      },
+      revoke: clearCfConnection,
     },
   ];
 }