A local-first multi-agent app development platform, built on PenguinHarness
/**
* The Settings dialog's pages, and who may see each one.
*
* Server-global pages write through /api/admin/settings (or the admin user routes) and
* belong to admins alone; the personal pages are per-user preferences every signed-in user
* owns (the credits page is one of them, open to everyone). Two pages additionally depend on
* how this session runs: the account page only
* exists where a password can be changed (see offersChangePassword), and user management
* disappears in desktop mode, where the app is single-user. The profile page is neither — an
* avatar and a nickname are display data, so every signed-in session may set them. Updating
* is not a page here at all — both the server check and the desktop client's live in the
* sidebar user menu, under the entry that opens this dialog. The rules live here rather than
* inside the dialog because this package's vitest runs in Node with no DOM — a pure function
* is the only thing a test can pin directly — and because rail and content have to apply the
* same rule to avoid a visible-but-forbidden entry.
*
* A page the viewer may not open is dropped from the list entirely rather than rendered
* disabled: a greyed-out "Proxy" row still tells a non-admin the setting exists and that
* someone else can reach it.
*
* None of this is the boundary. The admin APIs answer a non-admin with 403 whatever the
* browser chose to render.
*/
import { offersChangePassword } from "./account-menu";
import type { AccountMenuSession } from "./account-menu";
/** A page of the Settings dialog. */
export type SettingsSectionKey =
| "profile"
| "general"
| "appearance"
| "shortcuts"
| "account"
| "credits"
| "proxy"
| "uploads"
| "speech"
| "company"
| "agentApi"
| "plugins"
| "storage"
| "users";
/** Rail heading a page sits under: the viewer's own preferences vs. the whole server's. */
export type SettingsGroupKey = "personal" | "server";
export interface SettingsSection {
readonly key: SettingsSectionKey;
readonly group: SettingsGroupKey;
}
/** Who is looking, and from where — the union of what the visibility rules consume. */
export interface SettingsViewer extends AccountMenuSession {
readonly isAdmin: boolean;
}
/**
* Every page in rail order, with its visibility rule. Pages of one group stay contiguous —
* the rail renders this list top to bottom and starts a heading wherever the group changes.
*/
const SECTION_RULES: ReadonlyArray<SettingsSection & { visible(viewer: SettingsViewer): boolean }> =
[
// Heads the personal group, and unlike the account page below it is visible in every
// session: a nickname and an avatar need no password to change, so the desktop shell's
// own window — which for some installs is the only session there is — keeps it.
{ key: "profile", group: "personal", visible: () => true },
{ key: "general", group: "personal", visible: () => true },
{ key: "appearance", group: "personal", visible: () => true },
// Keyboard shortcuts are the account's, and apply in every session of it.
{ key: "shortcuts", group: "personal", visible: () => true },
// The desktop shell's own window has no password to change; a password-established
// session against the same server still does. Same predicate as the old menu row.
{ key: "account", group: "personal", visible: (v) => offersChangePassword(v) },
// The bundled fonts and their licences. Every session, the desktop shell's own window
// included: MiSans's licence asks the app to credit it wherever it runs.
{ key: "credits", group: "personal", visible: () => true },
{ key: "proxy", group: "server", visible: (v) => v.isAdmin },
{ key: "uploads", group: "server", visible: (v) => v.isAdmin },
// Speech input: the key the server transcribes with is one per deployment, so this is the
// admin's page too — the microphone in every composer then works for every member.
{ key: "speech", group: "server", visible: (v) => v.isAdmin },
// The company-mode master switch: server-global like the proxy and upload limits.
{ key: "company", group: "server", visible: (v) => v.isAdmin },
// Whether any Agent's public API answers at all: server-global, like company mode.
{ key: "agentApi", group: "server", visible: (v) => v.isAdmin },
// The sandbox, and the options loaded plugins declare (server-global, like the plugins themselves).
{ key: "plugins", group: "server", visible: (v) => v.isAdmin },
// The data root's storage ledger: a server-global report an admin reads. Read-only, so unlike
// user management below it stays in the desktop shell's window too — that install has the same
// data root and the same admin, and nothing here can be written by opening it.
{ key: "storage", group: "server", visible: (v) => v.isAdmin },
// Single-user under the desktop shell: the server rejects the admin user routes there.
{ key: "users", group: "server", visible: (v) => v.isAdmin && !v.desktopMode },
];
/** The pages this viewer may open, in rail order. */
export function visibleSettingsSections(viewer: SettingsViewer): readonly SettingsSection[] {
return SECTION_RULES.filter((section) => section.visible(viewer)).map(({ key, group }) => ({
key,
group,
}));
}
/**
* The group headings to draw for `sections`, in order and without repeats. A viewer left
* with a single group gets one entry, which the rail takes as its cue to draw no heading
* at all — a lone "Personal" heading implies the other group.
*/
export function settingsGroups(sections: readonly SettingsSection[]): readonly SettingsGroupKey[] {
const seen: SettingsGroupKey[] = [];
for (const section of sections) if (!seen.includes(section.group)) seen.push(section.group);
return seen;
}
/**
* Requested page -> the page to render. An unknown request and one naming a page this
* viewer may not open resolve identically, to the first visible page: nothing about what a
* different account would have found there leaks. Null only when nothing is visible.
*/
export function resolveSettingsSection(
raw: string | null | undefined,
sections: readonly SettingsSection[],
): SettingsSectionKey | null {
if (sections.some((section) => section.key === raw)) return raw as SettingsSectionKey;
return sections[0]?.key ?? null;
}