Skip to content

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

10.0 KB
Raw Blame
/**
 * Manual order of the sidebar's GROUPS — the Workspace folders and the Agents the
 * conversation list is cut into (pure decisions, unit tested). The row-level counterpart
 * is session-order.ts, whose sequence algebra this module reuses rather than restates:
 * `orderWithinPinPartitions` renders the order, `moveInSequence` performs a drop, and
 * `readStringArray` / `writeStringArray` are the storage body. What differs is the key
 * namespace, which modes may be ordered, that there is no sort-mode switch — and how a
 * drop is committed (commitGroupOrder, below).
 *
 * - **Implicit mode.** Dragging a group IS the intent — there is no second toggle beside
 *   the rows' `recent | manual` one. A Project+mode with nothing stored keeps the
 *   automatic sort untouched (an empty order is the identity), so a fresh profile looks
 *   exactly as it did.
 * - **Workspace and Agent modes only.** The time mode's buckets are a fixed
 *   chronological ladder: putting the older bucket above the newer one is not an order
 *   anyone can mean. isOrderableGroupMode is the single gate — the store refuses to read
 *   or write for "time", so the exclusion cannot be undone by forgetting a check at one
 *   call site.
 * - **One array per Project AND grouping mode**, exactly like the rows: the modes cut
 *   the list into different groups, so one shared array would let a drag in one mode
 *   scramble the other.
 * - **Unknown keys go to the TOP**, keeping their automatic order among themselves —
 *   the rule the rows use for new Sessions, so a Workspace used for the first time or a
 *   freshly created Agent surfaces instead of hiding at the bottom of a long list.
 *
 * **Stale keys are inert, and nothing prunes them.** A stored key that matches no group
 * is only ever a failed membership lookup (applyManualOrder), so it costs a map entry
 * and changes nothing on screen. Pruning was tried at the drop and removed: deciding a
 * group is *gone* needs the mode's complete live key set, and the client cannot prove
 * one. In Workspace mode the per-Agent `workspaceCounts` look like such a proof but
 * describe only the rows the server's index knew at fetch time, so a Workspace whose
 * Sessions arrive later (a boot-time adoption, an import) can be absent from a
 * complete-looking picture; in Agent mode `agentsLoading === false` is not
 * proof of a *successful* fetch, and an empty Agent list is indistinguishable from a
 * failed one. A wrong proof silently discards an arrangement the user cannot restore,
 * which is a bad trade against a few hundred short strings in localStorage. If a group
 * ever comes back under the same key it resumes its old place, which is the honest
 * reading of "same key, same group".
 *
 * Ordering composes with the group pins the same way the rows compose with theirs: the
 * pinned cluster renders first and the manual order applies within the pinned cluster
 * and within the rest independently, so a drag can never pin or unpin a group.
 *
 * Storage is injectable (model-group-expansion.ts convention: vitest runs in Node, no
 * localStorage); malformed values degrade to the defaults.
 */
import {
  moveInSequence,
  orderWithinPinPartitions,
  readStringArray,
  writeStringArray,
} from "./session-order";
import type { SessionOrderStorage } from "./session-order";
import type { GroupMode } from "../components/ui/group-list";

/**
 * The grouping modes whose groups can be dragged into a manual order. "time" is
 * deliberately absent — see the header.
 *
 * Deliberately NOT the same declaration as group-list.ts's `TreeGroupMode`, which names
 * the same two modes: that one exists because a Trace-file tree's rows carry no activity
 * timestamp to bucket on, this one because the time buckets are an order nobody can
 * mean. Same set today, different reasons — folding them together would let a change to
 * what a Traces tree can group by silently redefine what the sidebar may store.
 */
export const ORDERABLE_GROUP_MODES = ["workspace", "agent"] as const;
export type OrderableGroupMode = (typeof ORDERABLE_GROUP_MODES)[number];

/**
 * Whether a grouping mode's groups may be reordered at all (the one gate; time mode is
 * excluded). Derived from the list rather than restating it — a hand-written `||` chain
 * lets the exported array and "the single gate" drift, which is the exact failure this
 * gate exists to prevent.
 */
export function isOrderableGroupMode(mode: GroupMode): mode is OrderableGroupMode {
  return (ORDERABLE_GROUP_MODES as readonly GroupMode[]).includes(mode);
}

/** Minimal storage interface, shared with session-order.ts; tests inject an in-memory implementation. */
export type GroupOrderStorage = SessionOrderStorage;

/**
 * Storage key of one Project's manual GROUP order (sidebar key-naming convention,
 * `penguin.sessionOrder.<projectId>.<mode>` &c.), scoped by grouping mode for the same
 * reason the row order is: the modes have unrelated group lists.
 */
export const groupOrderKey = (projectId: string, mode: OrderableGroupMode): string =>
  `penguin.groupOrder.${projectId}.${mode}`;

/**
 * Reads a Project+mode's manual group order. No Project, an unorderable mode, nothing
 * stored, or corrupted storage all degrade to empty — which is the identity for
 * orderGroups, i.e. today's automatic sort. Junk array elements are dropped.
 */
export function loadGroupOrder(
  projectId: string | null,
  mode: GroupMode,
  storage?: GroupOrderStorage,
): string[] {
  if (projectId === null || !isOrderableGroupMode(mode)) return [];
  return readStringArray(groupOrderKey(projectId, mode), storage);
}

/** Writes a Project+mode's manual group order on every drop; an unorderable mode writes nothing. */
export function saveGroupOrder(
  projectId: string | null,
  mode: GroupMode,
  order: readonly string[],
  storage?: GroupOrderStorage,
): void {
  if (projectId === null || !isOrderableGroupMode(mode)) return;
  writeStringArray(groupOrderKey(projectId, mode), order, storage);
}

/**
 * The group-ordering pipeline, mirroring orderSessionRows one axis up:
 *
 * 1. the caller's automatic order arrives as the input (Workspace groups by their newest
 *    Session with the temp group forced last, Agents in their configured order) — it
 *    decides where groups with no stored place sit, and IS the whole answer while
 *    nothing is stored;
 * 2. the pinned cluster first, then the stored order within the pinned cluster and
 *    within the rest independently (orderWithinPinPartitions), so a drag can never move
 *    a group across the pin boundary;
 * 3. `demote`, when the caller passes one: a stable partition applied LAST and within the
 *    unpinned cluster only, moving the groups it picks behind the rest.
 *
 * An empty `order` returns the pinned-first list unchanged, which is exactly what the
 * sidebar rendered before any group was ever dragged.
 *
 * Demotion is the sidebar's folder-only groups — the ones holding nothing but folded
 * conversations, which a single evaluation creates by the dozen. It runs after the manual
 * order rather than instead of it, so the arrangement still reads inside each of the two
 * resulting blocks: the demoted groups keep their relative order and so do the kept ones,
 * and a group that gains an active row simply rejoins the others where it was all along.
 * Pinned groups are never demoted — a pin is the user saying where a group goes, and it is
 * how someone who wants a folder-only group at the top of the list says so.
 */
export function orderGroups<T>(
  groups: readonly T[],
  keyOf: (group: T) => string,
  opts: {
    pinned: ReadonlySet<string>;
    order: readonly string[];
    /** Groups to send behind the rest of the unpinned cluster; absent = nothing is demoted. */
    demote?: (group: T) => boolean;
  },
): T[] {
  const ordered = orderWithinPinPartitions(groups, keyOf, opts.pinned, opts.order);
  const demote = opts.demote;
  if (demote === undefined) return ordered;
  const kept: T[] = [];
  const last: T[] = [];
  for (const group of ordered) {
    (!opts.pinned.has(keyOf(group)) && demote(group) ? last : kept).push(group);
  }
  return last.length === 0 ? ordered : [...kept, ...last];
}

/**
 * Commits one group drop into the stored order, as a SPLICE rather than a rewrite.
 *
 * The rows' applyManualReorder moves the dropped partition's sequence to the FRONT of
 * the stored array, which is sound for Sessions because a partition is one group's own
 * list and the ids it displaces are read only within *other* partitions. That does not
 * lift to the group axis: the Workspace sequence is only as complete as the last counts
 * fetch (a Workspace whose Sessions arrive later is absent until the next reload), so
 * the keys a group drop would displace can be peers not on screen, ordered against the
 * very groups being committed. Front-loading demoted every such Workspace to the tail,
 * and (because the two pin partitions share one array) it also flung a group the length
 * of the sidebar the moment it was pinned or unpinned.
 *
 * So: materialise the rendered keys into the stored array where they already RENDER —
 * unlisted ones at the front, which is where applyManualOrder puts them — then move the
 * dragged key next to its target inside that array. Keys that are stored but not
 * rendered keep their positions relative to everything else, so a group that has merely
 * not loaded comes back exactly where the user left it.
 *
 * Returns the INPUT array unchanged (same reference) when the drop moves nothing, so the
 * caller can skip the state update and the storage write.
 */
export function commitGroupOrder(
  order: readonly string[],
  rendered: readonly string[],
  dragKey: string,
  targetKey: string,
  after: boolean,
): readonly string[] {
  const stored = new Set(order);
  const materialised = [...rendered.filter((key) => !stored.has(key)), ...order];
  const next = moveInSequence(materialised, dragKey, targetKey, after);
  // moveInSequence hands back its input for every no-op (self-drop, missing key, or a
  // landing that changes nothing): nothing moved, so nothing is worth persisting.
  return next === materialised ? order : next;
}