@100xprompt/brain 0.1.2 → 0.1.4

package/src/settings/catalog.ts

@@ -0,0 +1,476 @@
+// The one list of brain's settings. The command line (`brain settings`), and later the dashboard, the background agent and
+// the local page, all go by it: a setting that is not here cannot be set from anywhere, and a value of the wrong type is
+// refused before anything changes ("settings, never commands").
+//
+// Settings come in families, so the list stays short with 40 tools: `tools.<tool>.gateway` is one family. Each family says
+// its type, the levels it can be set at, whether the dashboard may change it and what a team admin may do, how to read
+// its actual state on this computer (from the files themselves) and how to apply a value. Ways 1 and 2 (lean, memory) have
+// nothing to apply: brain reads them where it uses them (values.ts).
+import { AUTO_MODEL, AUTO_ROUTE, DEFAULT_MODEL, DEFAULT_ROUTE, DEFAULT_URL, EDIT_HEADER, type Env, type GatewaySettings, modelId, modelName, readKey } from "../gateway/common.ts"
+import { CONNECTORS, connect, connectionState, connectorFor, disconnect, hasKey, installedHere } from "../gateway/connect.ts"
+import { HOOK_TOOLS, hookToolHere, installHooks, uninstallHooks } from "../hooks.ts"
+import { installMcp, MCP_TOOLS, mcpEntry, mcpHasRun, uninstallMcp } from "../memory/mcp-install.ts"
+import { redact } from "../memory/redact.ts"
+import { readSettings as readDashboard, updateSettings as updateDashboard } from "../dashboard/state.ts"
+import { readOrgConfig } from "../org/config.ts"
+import { toolLabel } from "../brief.ts"
+import { DEFAULTS, LIMITS } from "./values.ts"
+import { type Effective, effective, type Level, type SettingsDoc, type Value } from "./store.ts"
+
+export type Type = { kind: "bool" } | { kind: "choice"; choices: string[] } | { kind: "number"; min: number; max: number; unit: string }
+
+export interface Ctx {
+  home: string
+  env: Env
+  doc: SettingsDoc
+}
+
+export interface Actual {
+  /** What this computer has now; null when it has none, or it cannot be told (`note` says why). */
+  value: Value | null
+  /** Nothing to have yet: a model for a tool that is not on the gateway (it is used once the tool is connected). */
+  idle?: boolean
+  /** Why it is not simply that value, or what else is true. */
+  note?: string
+}
+
+export interface ApplyResult {
+  ok: boolean
+  error?: string
+  notes?: string[]
+  /** The tool is not on this computer. */
+  missing?: boolean
+}
+
+export interface Family {
+  /** `tools.*.gateway`, or a plain id such as `lean.threshold`. */
+  key: string
+  label: string
+  help: string
+  type: Type
+  /** Where it can be set. A setting only this computer can have is ["computer"]. */
+  levels: Level[]
+  /** Whether the dashboard may change it. "no": only on this computer (privacy switches, and what a change from afar would break). */
+  remote: "yes" | "no"
+  /** What a team admin may do with it. */
+  team: "none" | "default" | "default-and-lock" | "lock-off"
+  /** A value the dashboard may not set without this computer confirming it (why), when there is one. */
+  remoteGuard?: (value: Value, ctx: Ctx) => string | undefined
+  /** brain's value when nothing is set. Without one, brain leaves the setting as it finds it until someone sets it. */
+  default?: Value
+  /** For tools.* families: the tools it exists for (brain's ids). */
+  tools?: string[]
+  present(ctx: Ctx, tool?: string): boolean
+  read(ctx: Ctx, tool?: string): Promise<Actual>
+  /** Makes it so on this computer. Absent: brain reads the value where it uses it, so there is nothing to do. */
+  apply?(ctx: Ctx, value: Value, tool?: string): Promise<ApplyResult>
+  /** Why what brain applied cannot work any more (its own entry is broken), so `brain sync` should apply it again. */
+  repair?(ctx: Ctx, tool?: string): string | undefined
+}
+
+// ---- values against a family ------------------------------------------------------------------------------------------
+
+/** Whether a value is of the setting's type (a hand-edited or newer file may hold anything). */
+export function checkValue(type: Type, v: Value): boolean {
+  if (type.kind === "bool") return typeof v === "boolean"
+  if (type.kind === "choice") return typeof v === "string" && type.choices.includes(v)
+  return typeof v === "number" && Number.isInteger(v) && v >= type.min && v <= type.max
+}
+
+/**
+ * Which stored values count for a family: of its type, at a level it can be set at, and a lock only where a team admin may
+ * lock it (any value for default-and-lock, only off for lock-off). Anything else in the file is passed over.
+ */
+export const accepts = (f: Family) => (from: "lock" | Level, v: Value) =>
+  checkValue(f.type, v) && (from === "lock" ? f.team === "default-and-lock" || (f.team === "lock-off" && v === false) : f.levels.includes(from))
+
+/**
+ * Text from a tool or a command, made safe to keep and show: no secrets (the gateway key, tokens, keys a tool's file
+ * held), no home folder path. Error text from connect can quote a file it could not change.
+ */
+export function cleanText(text: string, home: string): string {
+  let t = redact(text)
+  const key = readKey(home)
+  if (key) t = t.replaceAll(key, "<key>")
+  if (home) t = t.replaceAll(home, "~")
+  return t.length > 400 ? `${t.slice(0, 399)}…` : t
+}
+
+// ---- tool ids ---------------------------------------------------------------------------------------------------------
+
+/** What the MCP installer calls a tool, by brain's id (the same mapping the dashboard report uses). */
+const MCP_INSTALLER_ID: Record<string, string> = { "cursor-ide": "cursor", "gemini-cli": "gemini", "vscode-copilot": "vscode" }
+const fromInstaller = (id: string) => Object.entries(MCP_INSTALLER_ID).find(([, v]) => v === id)?.[0] ?? id
+const installerId = (tool: string) => MCP_INSTALLER_ID[tool] ?? tool
+/** brain's id for a tool the MCP installer names (cursor: cursor-ide). */
+export const toolOfMcpInstaller = fromInstaller
+/** Short names people type for a tool. */
+const ALIASES: Record<string, string> = { claude: "claude-code", cursor: "cursor-ide", gemini: "gemini-cli", vscode: "vscode-copilot", copilot: "copilot-cli" }
+
+/** brain's id for a tool as typed: an id, a short name, or a connector's label. */
+export function canonicalTool(given: string): string {
+  const t = given.trim().toLowerCase()
+  if (ALIASES[t]) return ALIASES[t]!
+  return connectorFor(t)?.id ?? t
+}
+
+export const toolName = (tool: string) => connectorFor(tool)?.label ?? MCP_TOOLS.find((t) => fromInstaller(t.id) === tool)?.label ?? toolLabel(tool)
+
+// ---- the gateway families ---------------------------------------------------------------------------------------------
+
+const BY_PRODUCT: Record<string, string> = { "100xprompt Pro": "pro", "100xprompt Flash": "flash", "100xprompt Auto": "auto" }
+/**
+ * pro, flash or auto for a gateway model id, by the product it is (every Flash model is flash), or "other" for a model the
+ * person named themselves. Never the id itself: people are not shown the gateway's model ids.
+ */
+export const modelAlias = (id: string | undefined) => (id === undefined ? undefined : (BY_PRODUCT[modelName(id)] ?? "other"))
+
+const gatewayHere = (ctx: Ctx, tool?: string) => {
+  const c = connectorFor(tool ?? "")
+  if (!c) return false
+  try {
+    return installedHere(c, ctx.home, ctx.env) || connectionState(ctx.home, c.id, ctx.env).state !== "not-connected"
+  } catch {
+    return false
+  }
+}
+
+const olderBrain = (tool: string) => `${toolName(tool)} was connected by an older brain, so its settings cannot be told: run \`brain gateway connect --tool ${tool}\` once`
+
+/**
+ * The settings a connect of `tool` uses: the tool's own model and context editing (set here, or as it was connected), its
+ * route and address, with `change` on top. The auto model goes with the auto route, so a route is passed only when
+ * neither side of the change is auto.
+ */
+function connectSettings(ctx: Ctx, tool: string, change: { model?: string; contextEdit?: boolean } = {}): Partial<GatewaySettings> {
+  const rec = connectionState(ctx.home, tool, ctx.env).settings
+  const m = change.model ?? resolveId(ctx.doc, `tools.${tool}.model`).value
+  const ce = change.contextEdit ?? (HEADER_TOOLS.includes(tool) ? resolveId(ctx.doc, `tools.${tool}.contextEdit`).value : undefined)
+  const out: Partial<GatewaySettings> = {}
+  if (rec?.url) out.url = rec.url
+  if (typeof m === "string") out.model = m
+  else if (rec?.model) out.model = rec.model
+  if (typeof ce === "boolean") out.contextEdit = ce
+  else if (rec) out.contextEdit = rec.contextEdit
+  const model = out.model ? modelId(out.model) : undefined
+  if (rec?.route && rec.route !== AUTO_ROUTE && model !== AUTO_MODEL) out.route = rec.route
+  return out
+}
+
+/**
+ * connect's notes ("an exported ANTHROPIC_API_KEY wins over the helper") and warnings (an account over its limit), for the
+ * person. A reconnect for a new model keeps only the warnings: the notes were said when the tool was connected.
+ */
+const notesOf = (lines: string[], home: string, kinds = /^(note|warning): /) => lines.filter((l) => kinds.test(l)).map((l) => cleanText(l.replace(/^(note|warning): /, ""), home))
+
+async function reconnect(ctx: Ctx, tool: string, change: { model?: string; contextEdit?: boolean }): Promise<ApplyResult> {
+  const cs = connectionState(ctx.home, tool, ctx.env)
+  if (cs.state === "not-connected") return { ok: true }
+  if (!cs.settings) return { ok: false, error: olderBrain(tool) }
+  if (!hasKey(ctx.home)) return { ok: false, error: "not signed in to the gateway (brain gateway login)" }
+  const r = await connect(ctx.home, tool, { settings: connectSettings(ctx, tool, change), probe: false, env: ctx.env })
+  return r.ok ? { ok: true, notes: notesOf(r.lines, ctx.home, /^warning: /) } : { ok: false, error: cleanText(r.lines.join("; "), ctx.home) }
+}
+
+const CONNECTOR_IDS = CONNECTORS.map((c) => c.id)
+/** The tools whose connection changes with context editing (the others cannot send the header that turns it on). */
+export const HEADER_TOOLS = CONNECTORS.filter((c) => {
+  try {
+    const base = { url: DEFAULT_URL, route: DEFAULT_ROUTE, model: DEFAULT_MODEL }
+    const h = "/nonexistent-brain-home"
+    return JSON.stringify(c.edits(h, { ...base, contextEdit: true }, {})) !== JSON.stringify(c.edits(h, { ...base, contextEdit: false }, {}))
+  } catch {
+    return false
+  }
+}).map((c) => c.id)
+
+const gateway: Family = {
+  key: "tools.*.gateway",
+  label: "On the 100xprompt gateway",
+  help: "The tool sends its requests through 100xprompt (brain gateway connect / disconnect).",
+  type: { kind: "bool" },
+  levels: ["computer", "person"],
+  remote: "yes",
+  // A member's traffic through the gateway is visible to the team admin, and the computer may be the person's own:
+  // only the person turns a tool on.
+  team: "none",
+  tools: CONNECTOR_IDS,
+  present: gatewayHere,
+  async read(ctx, tool) {
+    const cs = connectionState(ctx.home, tool!, ctx.env)
+    if (cs.state === "connected") return { value: true }
+    if (cs.state === "partial") return { value: "partly", note: cs.why! }
+    return { value: false, ...(cs.why ? { note: cs.why } : {}) }
+  },
+  async apply(ctx, value, tool) {
+    const c = connectorFor(tool!)!
+    if (value === false) {
+      const r = disconnect(ctx.home, c.id, { env: ctx.env })
+      const kept = r.lines.filter((l) => /left as it is/.test(l)).map((l) => cleanText(l.trim(), ctx.home))
+      return r.ok ? { ok: true, ...(kept.length ? { notes: kept } : {}) } : { ok: false, error: cleanText(r.lines.join("; "), ctx.home) }
+    }
+    if (!installedHere(c, ctx.home, ctx.env)) return { ok: false, missing: true, error: `${c.label} has not run on this computer` }
+    if (!hasKey(ctx.home)) return { ok: false, error: "not signed in to the gateway (brain gateway login)" }
+    // No network check: it works offline with the stored key (`brain gateway connect` checks the key first).
+    const r = await connect(ctx.home, c.id, { settings: connectSettings(ctx, c.id), probe: false, env: ctx.env })
+    return r.ok ? { ok: true, notes: notesOf(r.lines, ctx.home) } : { ok: false, error: cleanText(r.lines.join("; "), ctx.home) }
+  },
+}
+
+const model: Family = {
+  key: "tools.*.model",
+  label: "Model",
+  help: "Which 100xprompt model the tool uses on the gateway: pro, flash or auto (auto-routing).",
+  type: { kind: "choice", choices: ["pro", "flash", "auto"] },
+  levels: ["computer", "person", "team"],
+  remote: "yes",
+  team: "default",
+  tools: CONNECTOR_IDS,
+  present: gatewayHere,
+  async read(ctx, tool) {
+    const cs = connectionState(ctx.home, tool!, ctx.env)
+    if (cs.state === "not-connected") return { value: null, idle: true }
+    if (!cs.settings) return { value: null, note: olderBrain(tool!) }
+    const id = cs.settings.model
+    if (cs.changed?.some((v) => v.includes(id))) return { value: "partly", note: `the model in ${toolName(tool!)}'s files was changed since brain connected it` }
+    return { value: modelAlias(id)! }
+  },
+  apply: (ctx, value, tool) => reconnect(ctx, tool!, { model: String(value) }),
+}
+
+const contextEdit: Family = {
+  key: "tools.*.contextEdit",
+  label: "Context editing",
+  help: "The gateway clears old tool results from long requests when that saves money (way 6).",
+  type: { kind: "bool" },
+  levels: ["computer", "person", "team"],
+  remote: "yes",
+  team: "default",
+  tools: HEADER_TOOLS,
+  present: gatewayHere,
+  async read(ctx, tool) {
+    const cs = connectionState(ctx.home, tool!, ctx.env)
+    if (cs.state === "not-connected") return { value: null, idle: true }
+    if (!cs.settings) return { value: null, note: olderBrain(tool!) }
+    if (cs.changed?.some((v) => v.includes(EDIT_HEADER))) return { value: "partly", note: `the context-editing header in ${toolName(tool!)}'s files was changed since brain connected it` }
+    return { value: cs.settings.contextEdit }
+  },
+  apply: (ctx, value, tool) => reconnect(ctx, tool!, { contextEdit: value === true }),
+}
+
+// ---- MCP tools and hooks ----------------------------------------------------------------------------------------------
+
+const mcp: Family = {
+  key: "tools.*.mcp",
+  label: "brain tools",
+  help: "The tool can use brain_recall, brain_expand and brain_map (brain mcp install / uninstall).",
+  type: { kind: "bool" },
+  levels: ["computer", "person"],
+  remote: "yes",
+  team: "none",
+  tools: MCP_TOOLS.map((t) => fromInstaller(t.id)),
+  present: (ctx, tool) => mcpHasRun(ctx.home, installerId(tool!)) || mcpEntry(ctx.home, installerId(tool!)).installed,
+  async read(ctx, tool) {
+    const e = mcpEntry(ctx.home, installerId(tool!))
+    const note = e.broken ? `cannot start: ${e.broken}` : e.off ? `turned off in ${toolName(tool!)}'s settings` : undefined
+    return { value: e.installed && !e.broken && !e.off, ...(note ? { note } : {}) }
+  },
+  repair(ctx, tool) {
+    const e = mcpEntry(ctx.home, installerId(tool!))
+    return e.installed && e.broken ? e.broken : undefined
+  },
+  async apply(ctx, value, tool) {
+    const id = installerId(tool!)
+    if (value === true) {
+      // Any brain's working entry counts: it is left as it is, so two brains never keep rewriting each other's.
+      const e = mcpEntry(ctx.home, id)
+      if (e.installed && !e.broken && !e.off) return { ok: true }
+    }
+    const [c] = value === true ? installMcp([id], ctx.home) : uninstallMcp([id], ctx.home)
+    if (!c || c.action === "skipped") return { ok: false, ...(c?.why && /has not run/.test(c.why) ? { missing: true } : {}), error: cleanText(c?.why ?? "nothing to change", ctx.home) }
+    return { ok: true, ...(value === true && c.action === "installed" ? { notes: [`restart ${toolName(tool!)} for it to pick up the brain tools`] } : {}) }
+  },
+}
+
+const hooks: Family = {
+  key: "tools.*.hooks",
+  label: "Session-start hook",
+  help: "The tool receives a handoff by itself when a session starts (brain session hooks install / uninstall).",
+  type: { kind: "bool" },
+  // Codex trusts hooks by their place in the file: changing them from afar would make it ask again about the person's own.
+  levels: ["computer"],
+  remote: "no",
+  team: "none",
+  tools: HOOK_TOOLS,
+  present: (ctx, tool) => hookToolHere(tool!, ctx.home),
+  async read(ctx, tool) {
+    const [c] = await installHooks([tool!], ctx.home, { dryRun: true })
+    if (!c || c.action === "skipped") return { value: null, ...(c?.why ? { note: cleanText(c.why, ctx.home) } : {}) }
+    return { value: c.action === "already-installed" }
+  },
+  async apply(ctx, value, tool) {
+    const [c] = value === true ? await installHooks([tool!], ctx.home) : await uninstallHooks([tool!], ctx.home)
+    if (!c || c.action === "skipped") return { ok: false, ...(c?.why && /has not run/.test(c.why) ? { missing: true } : {}), error: cleanText(c?.why ?? "nothing to change", ctx.home) }
+    return { ok: true, ...(c.why ? { notes: [cleanText(c.why, ctx.home)] } : {}) }
+  },
+}
+
+// ---- ways 1 and 2, and reports ------------------------------------------------------------------------------------------
+
+/** A setting brain reads where it uses it: its actual value is the one that applies. */
+const internal = (key: string, f: Omit<Family, "key" | "present" | "read" | "default">): Family => ({
+  key,
+  ...f,
+  default: DEFAULTS[key],
+  present: () => true,
+  async read(ctx) {
+    return { value: resolveId(ctx.doc, key).value ?? null }
+  },
+})
+
+const ALL_LEVELS: Level[] = ["computer", "person", "team"]
+
+const leanAuto = internal("lean.auto", {
+  label: "Lean long sessions",
+  help: "A session moved to another tool is made lean by itself when it is long (way 1): big tool output becomes digests, the full text stays on this computer.",
+  type: { kind: "bool" },
+  levels: ALL_LEVELS,
+  remote: "yes",
+  team: "default-and-lock",
+})
+const leanThreshold = internal("lean.threshold", {
+  label: "Lean from",
+  help: "The size, in tokens, from which a session is made lean by itself.",
+  type: { kind: "number", ...LIMITS["lean.threshold"], unit: "tokens" },
+  levels: ALL_LEVELS,
+  remote: "yes",
+  team: "default-and-lock",
+})
+const leanMinChars = internal("lean.minChars", {
+  label: "Digest outputs over",
+  help: "In a lean session, tool output longer than this many characters is replaced by a digest (the first level of --budget too).",
+  type: { kind: "number", ...LIMITS["lean.minChars"], unit: "characters" },
+  levels: ALL_LEVELS,
+  remote: "yes",
+  team: "default-and-lock",
+})
+const memoryEnabled: Family = {
+  ...internal("memory.enabled", {
+    label: "Project memory",
+    help: "What sessions establish is kept per project and recalled in later briefs and by brain_recall (way 2).",
+    type: { kind: "bool" },
+    levels: ALL_LEVELS,
+    remote: "yes",
+    team: "lock-off",
+  }),
+  // With team memory (brain org login), memory sends items to the organisation's server: only this computer turns that on.
+  remoteGuard: (value, ctx) => (value === true && readOrgConfig(ctx.home) ? "this computer sends memory to your team's server (brain org): turn it on on the computer itself" : undefined),
+  async read(ctx) {
+    const v = resolveId(ctx.doc, "memory.enabled").value ?? true
+    const org = ctx.env.BRAIN_ORG !== "off" && readOrgConfig(ctx.home)
+    const notes = [org ? `kept on your team's server (${org.server})` : "", ctx.env.BRAIN_NO_MEMORY === "1" ? "BRAIN_NO_MEMORY is set here: no background memory sync" : ""].filter(Boolean)
+    return { value: v, ...(v === true && notes.length ? { note: notes.join("; ") } : {}) }
+  },
+}
+
+const reports: Family = {
+  key: "reports.enabled",
+  label: "Reports to your account",
+  help: "This computer sends its report (tools, gateway, conversions; never chat text) for the dashboard's Brain view (brain dashboard on / off).",
+  type: { kind: "bool" },
+  // A privacy switch the server could turn back on would not be one.
+  levels: ["computer"],
+  remote: "no",
+  team: "none",
+  present: () => true,
+  async read(ctx) {
+    const v = ctx.env.BRAIN_NO_REPORT
+    const envOff = v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false"
+    return { value: !readDashboard(ctx.home).off, ...(envOff ? { note: "BRAIN_NO_REPORT is set here, so nothing is sent while it is" } : {}) }
+  },
+  async apply(ctx, value) {
+    updateDashboard(ctx.home, (s) => {
+      if (value === true) delete s.off
+      else s.off = true
+    })
+    return { ok: true }
+  },
+}
+
+export const FAMILIES: Family[] = [gateway, model, contextEdit, mcp, hooks, leanAuto, leanThreshold, leanMinChars, memoryEnabled, reports]
+
+// ---- ids and values -----------------------------------------------------------------------------------------------------
+
+export interface SettingRef {
+  id: string
+  family: Family
+  tool?: string
+}
+
+/** A setting id as typed (`tools.cursor.mcp`, `lean.threshold`), or why there is no such setting. */
+export function parseId(given: string): SettingRef | { error: string } {
+  const raw = given.trim()
+  const m = /^tools\.(.+)\.([A-Za-z]+)$/.exec(raw)
+  if (m) {
+    const family = FAMILIES.find((f) => f.key === `tools.*.${m[2]}`)
+    if (!family) return { error: `no setting "${raw}": a tool's settings are ${FAMILIES.filter((f) => f.tools).map((f) => f.key.slice(8)).join(", ")}` }
+    const tool = canonicalTool(m[1]!)
+    if (!family.tools!.includes(tool)) return { error: `${family.key.replace("*", "<tool>")} exists for ${family.tools!.join(", ")}; not for "${m[1]}"` }
+    return { id: `tools.${tool}.${m[2]}`, family, tool }
+  }
+  const family = FAMILIES.find((f) => !f.tools && f.key.toLowerCase() === raw.toLowerCase())
+  if (!family) return { error: `no setting "${raw}"; \`brain settings ids\` lists them` }
+  return { id: family.key, family }
+}
+
+/** What applies for a setting, by the family's rules (accepts): the value brain uses and applies. */
+export function resolve(doc: SettingsDoc, ref: SettingRef): Effective {
+  return effective(doc, ref.id, ref.family.default, accepts(ref.family))
+}
+
+/** resolve() by id; nothing applies for an id that is not a setting. */
+export function resolveId(doc: SettingsDoc, id: string): Effective {
+  const ref = parseId(id)
+  return "error" in ref ? { from: "none" } : resolve(doc, ref)
+}
+
+/** A value as typed, checked against the type (on/off, a choice, a whole number in range: 50000, 50,000 or 50k). */
+export function parseValue(type: Type, given: string): { value: Value } | { error: string } {
+  const v = given.trim().toLowerCase()
+  if (type.kind === "bool") {
+    if (["on", "true", "yes", "1", "enabled"].includes(v)) return { value: true }
+    if (["off", "false", "no", "0", "disabled"].includes(v)) return { value: false }
+    return { error: `"${given}" is not on or off` }
+  }
+  if (type.kind === "choice") return type.choices.includes(v) ? { value: v } : { error: `"${given}" is not one of ${type.choices.join(", ")}` }
+  // Commas and underscores only as thousands separators (1,500 or 1_500; not 1,5k).
+  const m = /^(\d{1,3}(?:,\d{3})+|\d{1,3}(?:_\d{3})+|\d+)(k)?$/.exec(v.replace(/\s+/g, ""))
+  const n = m ? Number(m[1]!.replace(/[,_]/g, "")) * (m[2] ? 1_000 : 1) : NaN
+  if (!Number.isInteger(n)) return { error: `"${given}" is not a whole number` }
+  if (n < type.min || n > type.max) return { error: `${n.toLocaleString("en-US")} is outside ${type.min.toLocaleString("en-US")} to ${type.max.toLocaleString("en-US")} ${type.unit}` }
+  return { value: n }
+}
+
+/** A value for people: on/off, a number with its unit, a model by its short name. */
+export function showValue(type: Type, v: Value | null | undefined): string {
+  if (v === null || v === undefined) return "-"
+  if (v === "partly") return "partly"
+  if (type.kind === "bool") return v === true ? "on" : v === false ? "off" : String(v)
+  if (type.kind === "number" && typeof v === "number") return `${v.toLocaleString("en-US")} ${type.unit}`
+  if (type.kind === "choice" && typeof v === "string" && !type.choices.includes(v)) return "another model"
+  return String(v)
+}
+
+/** Every setting there can be on this computer: the families without tools, and each tool family for each tool here. */
+export function settingsHere(ctx: Ctx): SettingRef[] {
+  const out: SettingRef[] = []
+  for (const f of FAMILIES) {
+    if (!f.tools) out.push({ id: f.key, family: f })
+    else for (const t of f.tools) if (f.present(ctx, t)) out.push({ id: f.key.replace("*", t), family: f, tool: t })
+  }
+  return out
+}
+
+/** The catalog as data (for the dashboard sync and the check that the console knows every family). */
+export const describeCatalog = () =>
+  FAMILIES.map((f) => ({ key: f.key, label: f.label, type: f.type, levels: f.levels, remote: f.remote, team: f.team, ...(f.default !== undefined ? { default: f.default } : {}), ...(f.tools ? { tools: f.tools } : {}) }))