Official
settings
Built-in settings UI (JavaScript UI plugin).
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/settings@0.2.7
Permissions in 0.2.7
Files
views/plugins.tsx10.3 KB
// The Plugins section: one row per plugin with its state, badges, grants
// and the review card that only the native enable flow can open.
// HTM whitespace is significant; keep these templates out of Prettier's HTML formatter.
import type { EffectViewContext } from "divergence/effect";
import type { PermissionEntry, PluginSummary, Risk } from "divergence";
import { PERMISSIONS, RISK_NAMES } from "../model.ts";
import type { SettingsPage } from "../controller.ts";
import { DOT, TITLE_LINE, besideTitle, card, listRow, section, setting, column, fill, row } from "./layout.tsx";
// The risk dot: muted for low, softened warning for medium, warning for
// high, danger for dangerous and unsafe.
const RISK_TONES: Record<Risk, { tone: "muted" | "warning" | "danger"; opacity?: number }> = {
always: { tone: "muted" },
low: { tone: "muted" },
medium: { tone: "warning", opacity: 0.75 },
high: { tone: "warning" },
dangerous: { tone: "danger" },
unsafe: { tone: "danger" },
reserved: { tone: "muted" },
};
function pluginBadges(plugin: PluginSummary) {
return [
// Official is the ordinary case in this list; only the exceptions get
// a badge (the review card still names it).
plugin.claimsOfficial ? <badge variant="warning">Claims an official id</badge> : null,
!plugin.official && plugin.source === "local" ? <badge>Local</badge> : null,
plugin.source === "marketplace" ? <badge>Marketplace</badge> : null,
plugin.basedOn ? <badge>{`Mod of ${plugin.basedOn.id}@${plugin.basedOn.version}`}</badge> : null,
// No OS sandbox holds its code on this system (Windows for now):
// only the permission checks do. Its enable card is held for 2 s.
!plugin.official && plugin.sandboxed === false ? <badge variant="danger">Sandbox not available</badge> : null,
// The OS sandbox holds part of what its grants ask (`enforcement`,
// from the runtime's launcher): the rows below say what it does not.
plugin.sandboxed !== false && enforcementOf(plugin)?.level === "partial"
? <badge variant="warning">Partly sandboxed</badge>
: null,
];
}
type Enforcement = {
level: "sandboxed" | "partial" | "unsandboxed";
mechanism: string;
unenforced?: { area: string; detail: string }[];
reason?: string;
};
// What the OS sandbox holds for the plugin's runtime: a field this view's
// generated summary type does not have yet.
function enforcementOf(plugin: PluginSummary): Enforcement | undefined {
return (plugin as PluginSummary & { enforcement?: Enforcement }).enforcement;
}
// The sandbox status under a plugin's grants: what holds, and each
// restriction it asks for that the OS does not enforce here.
function sandboxRows(plugin: PluginSummary) {
const enforcement = enforcementOf(plugin);
if (!enforcement) return null;
const summary =
enforcement.level === "sandboxed"
? `Sandboxed (${enforcement.mechanism}): every native restriction its grants ask for holds.`
: enforcement.level === "partial"
? `Partly sandboxed (${enforcement.mechanism}): what does not hold is listed.`
: `Not sandboxed: ${enforcement.reason ?? "this system has no plugin sandbox"}. Native file, network and program access is not restricted.`;
return (
<div {...column} gap="small" padding="small">
<text style="body" size="xs" tone={enforcement.level === "sandboxed" ? "muted" : enforcement.level === "partial" ? "warning" : "danger"}>{summary}</text>
{(enforcement.unenforced ?? []).map(
(item) => <text style="body" size="xs" tone="muted">{`${item.area}: ${item.detail}`}</text>,
)}
</div>
);
}
// Failed and waiting states are badges; the quiet ones are a word.
function pluginState(plugin: PluginSummary) {
// `waiting` arrived after the generated type was written; compare the
// widened state so the badge survives without a cast.
const state: string = plugin.state;
if (state === "failed") return <badge variant="danger">Failed</badge>;
if (state === "waiting") return <badge variant="warning">Waiting</badge>;
if (plugin.enabled && plugin.pending.length) return <badge variant="warning">Needs review</badge>;
if (state === "reload_pending") return <badge variant="warning">Reload pending</badge>;
// On or off is the switch's to say; only a plugin that has none yet (it
// is enabled from its review card) says it in words.
return plugin.enabled || state === "disabled"
? null
: <text style="body" size="xs" tone="faint">Not enabled</text>;
}
function grantRow(
ctx: EffectViewContext<object>,
actions: SettingsPage["Service"],
plugin: PluginSummary,
entry: PermissionEntry,
) {
// A permission only official plugins can have is never granted to
// another; it shows faint, with the reason why.
const blocked = entry.risk === "reserved" && !plugin.official;
const risk = { ...RISK_TONES[entry.risk], label: RISK_NAMES[entry.risk] };
const label = PERMISSIONS[entry.permission].label;
const revocable = entry.granted && !plugin.official && entry.risk !== "always";
return (
<div {...row} gap="small" padding="small" paddingY="small" alignItems="start">
<div {...column} gap="small" padding="small" paddingY={6}>
<div {...column} gap="small" padding="small" width={7} flexShrink={0} height={7} opacity={risk.opacity} background={DOT[risk.tone]} borderRadius="full" />
</div>
<div {...column} {...fill} padding="small">
<div {...row} gap="small" padding="small" flexWrap="wrap">
<text style="body" size="sm" weight={560} tone={blocked ? "faint" : "foreground"}>{label}</text>
{entry.scope ? <text style="mono" size="xs" tone={blocked ? "faint" : "muted"}>{entry.scope}</text> : null}
</div>
<text style="body" size="xs" tone="muted">{blocked ? "Only official plugins can have this" : (entry.reason ?? "")}</text>
</div>
<text style="body" size="xs" tone={blocked || !entry.granted ? "faint" : risk.tone}>{blocked ? "Refused" : entry.granted ? risk.label : "Not granted"}</text>
{revocable
? <button id={`revoke-${plugin.name}-${entry.permission}-${entry.scope ?? ""}`} label="Revoke" variant="ghost" small onClick={() => ctx.run(actions.revoke(plugin.name, entry))} />
: null}
</div>
);
}
function pluginRow(ctx: EffectViewContext<object>, actions: SettingsPage["Service"], plugin: PluginSummary) {
const state = actions.state;
const open = !!state.openPermissions[plugin.name];
// A plugin never enabled, or turned off with something new to review,
// is enabled from its card. A switch is for the rest.
const reviewFirst = !plugin.enabled && (plugin.state === "not_enabled" || plugin.pending.length > 0);
const togglePermissions = () => {
state.openPermissions = { ...state.openPermissions, [plugin.name]: !open };
ctx.update();
};
const reviewButtons = [
reviewFirst
? <button id={`review-${plugin.name}`} label="Review and enable…" small variant="primary" onClick={() => ctx.run(actions.review(plugin.name))} />
: null,
plugin.enabled && plugin.pending.length
? <button id={`review-${plugin.name}`} label="Review permissions…" small variant="primary" onClick={() => ctx.run(actions.review(plugin.name))} />
: null,
].filter(Boolean);
// An official plugin's id is `divergence/<name>`; any other id is worth
// reading, so it follows the version.
const ownId = plugin.official && plugin.id === `divergence/${plugin.name}`;
// Two lines: what it is and its controls, then what it does. Permissions
// and reload are icon buttons on the title line; the permission list
// opens under the description.
return listRow(
besideTitle(
reviewFirst
? null
: <switch id={`plugin-${plugin.name}`} label="" checked={plugin.enabled} onChange={(e: { value: boolean }) => ctx.run(actions.setPluginEnabled(plugin.name, e.value))} />,
36,
),
(
<div {...column} {...fill} gap={2}>
<div {...row} gap="small" height={TITLE_LINE}>
<text style="body" size="sm" bold>{plugin.name}</text>
<text style="body" size="xs" tone="faint">{plugin.version}</text>
{ownId ? null : <text style="mono" size="xs" tone="faint">{plugin.id}</text>}
{pluginBadges(plugin)}
<spacer />
{pluginState(plugin)}
</div>
{plugin.description ? <text style="body" size="xs" tone="muted">{plugin.description}</text> : null}
{plugin.error ? <code>{plugin.error}</code> : null}
{reviewButtons.length ? <div {...row} gap="small" paddingY={4}>{reviewButtons}</div> : null}
{open
? (
<panel marginTop={6}>
{plugin.permissions.map((entry) => grantRow(ctx, actions, plugin, entry))}
{sandboxRows(plugin)}
</panel>
)
: null}
</div>
),
besideTitle(
(
<div {...row} gap={2}>
{plugin.permissions.length
? <button id={`permissions-${plugin.name}`} icon="shield-check" variant="ghost" small active={open} tooltip={open ? "Hide permissions" : `Permissions (${plugin.permissions.filter((entry) => entry.granted).length} of ${plugin.permissions.length} granted)`} onClick={togglePermissions} />
: null}
<button id={`reload-${plugin.name}`} icon="rotate-cw" variant="ghost" small tooltip="Reload" onClick={() => ctx.run(actions.reload(plugin.name))} />
</div>
),
),
);
}
export function renderPlugins(ctx: EffectViewContext<object>, actions: SettingsPage["Service"]) {
const p = actions.state.data.plugins;
if (!p) return <empty>Loading…</empty>;
const providesAgents = (plugin: PluginSummary) =>
plugin.permissions.some((entry) => entry.permission === "agents.provide");
const services = p.filter(providesAgents);
const others = p.filter((plugin) => !providesAgents(plugin));
return (
<div {...column} gap="large" padding="small">
{section("Interface", "Plugins live in the Plugins workspace. Edit them there; they reload on save. A new plugin runs only once you enable it here.", card(others.map((plugin) => pluginRow(ctx, actions, plugin))))}
{services.length ? section("Agents", "Each brings the agents it names.", card(services.map((plugin) => pluginRow(ctx, actions, plugin)))) : null}
</div>
);
}Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.8latest | Nov 21, 2026 | >=5 <6 | 68.5 KB | 7 permissions | Listed |
| 0.2.7 | Nov 18, 2026 | >=5 <6 | 68 KB | 7 permissions | Listed |
| 0.2.6 | Nov 16, 2026 | >=5 <6 | 66.3 KB | 7 permissions | Listed |
| 0.2.5 | Nov 11, 2026 | >=5 <6 | 63.6 KB | 7 permissions | Listed |
| 0.2.4 | Nov 9, 2026 | >=5 <6 | 61.6 KB | 7 permissions | Listed |
| 0.2.3 | Oct 27, 2026 | >=2 <4 | 46.8 KB | 7 permissions | Listed |
No comments yet.