Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

3.7 KB
Raw Blame
/**
 * What raises an update notification badge, and what the anchor carrying it says.
 *
 * One gate lives here: the *software* update, actionable in the sidebar user menu. The other
 * four trails are all dismissible and live in `todo-badges.ts` — the Agent kernel one moved
 * there when its page grew a notice with a way down, since a gate that can be waved away has to
 * produce a signature and not just a boolean. The outermost chrome (the mobile menu button)
 * shows one dot for any of the five; `badgeNote` at the bottom is what every anchor covering
 * more than one of them speaks through.
 *
 * Every gate here is written as "is there a control the user can reach": a badge over a path
 * with nothing actionable at the end of it is worse than no badge. That is why the software
 * gate reads the update flow, whose mode is the session's — a browser signed into a
 * desktop-mode server can update neither the server nor that machine's app, and its flow
 * never offers anything, so no dot leads it to a modal with nothing to do.
 *
 * Pure decisions only (vitest runs node-only here, so nothing renders) — `use-update-badges.ts`
 * wires them to the live stores and turns a note into localized copy.
 */
import type { UpdateFlow } from "./update-flow";

/** A software update the user can act on: a release offered (download it), or one downloaded / installed (restart into it). */
export type SoftwareUpdate =
  | { kind: "available"; version: string }
  /** `version` is null when the backend did not name one. */
  | { kind: "ready"; version: string | null };

/**
 * The one software gate behind every dot on that trail, read off the update flow. A download
 * in flight is deliberately not one: the row shows its progress, but there is nothing for the
 * user to do until it lands, and a badge that cannot be cleared by acting on it is noise. The
 * mode gate is the flow's own: where this session can update nothing, the flow never leaves
 * `unknown`.
 */
export function softwareUpdate(flow: UpdateFlow): SoftwareUpdate | null {
  if (flow.kind === "available") return { kind: "available", version: flow.version };
  if (flow.kind === "ready") return { kind: "ready", version: flow.version };
  return null;
}

/**
 * One thing a dot can stand for. The first is the self-clearing trail above; the rest are the
 * dismissible ones in `todo-badges.ts`. Three of those carry a count because the anchors that
 * name them have room to say how many; `kernel` does not, because the Agents nav entry says
 * "kernel update available" without a number and always has.
 */
export type BadgeSource =
  | SoftwareUpdate
  | { kind: "kernel" }
  | { kind: "plugins"; count: number }
  | { kind: "models"; count: number }
  | { kind: "errors"; count: number };

/**
 * What an anchor says. A single source speaks for itself; several make it `mixed`, because an
 * anchor leading to all of them must not claim to be one — naming one of five would point the
 * user down the wrong trail.
 *
 * `updatesOnly` splits the two combined wordings apart. Four of the five sources ARE updates
 * and can be summed up as "something can be updated"; unexpected errors are not an update by
 * any reading, so a mix containing them needs the wider "something is waiting for you".
 */
export type UpdateBadgeNote =
  { kind: "none" } | BadgeSource | { kind: "mixed"; updatesOnly: boolean };

/** Classifies what one anchor over `sources` should say (see {@link UpdateBadgeNote}). */
export function badgeNote(sources: readonly BadgeSource[]): UpdateBadgeNote {
  if (sources.length === 0) return { kind: "none" };
  if (sources.length === 1) return sources[0]!;
  return { kind: "mixed", updatesOnly: sources.every((s) => s.kind !== "errors") };
}