@gperezmz/bb-plugin-thread-glance 0.2.3 → 0.3.0

package/features/thread-list/testing/fixtures.ts

@@ -5,10 +5,10 @@ import type {
   PluginSidebarThread,
 } from "@get-bb/plugin-sdk/app";
 import { defaultPreferences, type Preferences } from "@/shared/preferences";
-import { buildForest, type Forest } from "../model/families";
+import { buildForest, type Forest } from "../model/trees";
 import { buildListView, type ListView, type Row } from "../model/view";
 import type { Targets } from "../model/expansion";
-import type { SectionFamily } from "../model/attention";
+import { pullRequestFact, type PullRequestState, type SettleInputs } from "../model/settled";
 
 export const T0 = 1_780_000_000_000;
 
@@ -109,10 +109,6 @@ export interface Scenario {
   sections?: PluginSidebarSection[];
   prefs?: Partial<Preferences>;
   activeThreadId?: string | null;
-  /** The root of the held family, held as it stands now. */
-  heldRootId?: string | null;
-  /** The held family as it was when opened; wins over `heldRootId`. */
-  held?: SectionFamily | null;
   targets?: Targets;
   finishedAt?: Record<string, number>;
   seenAt?: Record<string, number>;
@@ -120,6 +116,17 @@ export interface Scenario {
   draftIds?: string[];
   notes?: Record<string, import("@/shared/contract").ThreadNotes>;
   now?: number;
+  startedAt?: Record<string, number>;
+  /** Project id → default branch; "main" for every project when absent. */
+  defaultBranches?: Record<string, string | null>;
+  /** bb's primary machine; "host_1", the fixtures' own, when absent. */
+  primaryHostId?: string | null;
+  comfortable?: boolean;
+  needYouOnly?: boolean;
+  /** bb's default harness; "claude-code", the fixtures' own, when absent. */
+  defaultProviderId?: string | null;
+  /** Pull request lookups that answered, by thread id. */
+  pullRequests?: Record<string, PullRequestState | null>;
 }
 
 export function forestOf(scenario: Scenario): Forest {
@@ -145,19 +152,39 @@ export function viewOf(scenario: Scenario): ListView {
     sections: scenario.sections ?? [],
     prefs: { ...defaultPreferences(), ...scenario.prefs },
     activeThreadId: scenario.activeThreadId ?? null,
-    held: scenario.held ?? (scenario.heldRootId == null ? null : (forest.familyOf.get(scenario.heldRootId) ?? null)),
     targets: scenario.targets ?? new Map(),
+    settle: settleOf(scenario),
+    defaultProviderId: scenario.defaultProviderId === undefined ? "claude-code" : scenario.defaultProviderId,
+    primaryHostId: scenario.primaryHostId === undefined ? "host_1" : scenario.primaryHostId,
+    comfortable: scenario.comfortable ?? false,
+    needYouOnly: scenario.needYouOnly ?? false,
+    defaultBranchOf: (thread) =>
+      scenario.defaultBranches === undefined ? "main" : scenario.defaultBranches[thread.projectId],
   });
 }
 
+/** The settle inputs a scenario stands for. */
+export function settleOf(scenario: Scenario): SettleInputs {
+  const answers = new Map(Object.entries(scenario.pullRequests ?? {}));
+  const defaultBranchOf = (projectId: string) =>
+    scenario.defaultBranches === undefined ? "main" : scenario.defaultBranches[projectId];
+  return {
+    now: scenario.now ?? T0 + 60_000,
+    settleAfter: scenario.prefs?.settleAfter ?? defaultPreferences().settleAfter,
+    startedAt: scenario.startedAt ?? {},
+    finishedAt: scenario.finishedAt ?? {},
+    pullRequestOf: (thread) => pullRequestFact(thread, defaultBranchOf(thread.projectId), answers),
+  };
+}
+
 function idsOf(rows: readonly Row[]): string[] {
   return rows.map((row) =>
     row.type === "thread"
       ? row.info.thread.id
       : row.type === "older"
         ? `older:${row.count}`
-        : row.type === "left-out"
-          ? `+${row.count}`
+        : row.type === "settled"
+          ? `settled:${row.count}`
           : `env:${row.environmentId}`,
   );
 }
@@ -169,7 +196,9 @@ export function rowIds(view: ListView, groupId: string): string[] {
   return idsOf(group.rows);
 }
 
-/** Thread ids in Needs attention, in order; "+N more" lines as `+N`. Empty when the section is absent. */
-export function attentionIds(view: ListView): string[] {
-  return idsOf(view.attention?.rows ?? []);
+/** Roots of the trees that need attention, in the forest's order. */
+export function attentionRootIds(scenario: Scenario): string[] {
+  return forestOf(scenario)
+    .trees.filter((tree) => tree.attentionFlags.size > 0)
+    .map((tree) => tree.root.thread.id);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gperezmz/bb-plugin-thread-glance",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "bb": ">=0.43",

package/server/cli.ts

@@ -38,7 +38,7 @@ export function createCli(store: PreferenceStore): PluginCliRegistration {
     name: "thread-glance",
     summary: "Inspect and change the Thread Glance sidebar's layout preferences",
     description:
-      "Organization, sort, group order, hidden and collapsed groups, child-thread folding and which child threads Needs attention counts, for the Thread Glance sidebar. Values are JSON; a bare word is read as a string.",
+      "Organization, sort, group order, hidden and collapsed groups, child-thread folding, settling and which child threads Needs attention counts, for the Thread Glance sidebar. Values are JSON; a bare word is read as a string.",
     commands: {
       "prefs list": cliCommand({
         summary: "List every preference and its current value",

package/server/import.ts

@@ -21,8 +21,9 @@ export interface ImportResult {
 }
 
 /**
- * Reads bb's preferences from its CLI and returns the parsed JSON, or null
- * when the command fails or prints something that is not JSON.
+ * Reads bb's preferences from its CLI, asking the server Thread Glance runs
+ * in, and returns the parsed JSON, or null when that server is unknown, the
+ * command fails or it prints something that is not JSON.
  */
 export type BbCliReader = () => Promise<unknown>;
 
@@ -66,28 +67,57 @@ export function bbCliPath(env: NodeJS.ProcessEnv = process.env): string {
   return configured ? configured : "bb";
 }
 
-/** Runs `bb thread-list prefs list --json` with a 5 s timeout. */
+/**
+ * Runs `bb thread-list prefs list --json` with a 5 s timeout against the bb
+ * server Thread Glance runs in.
+ *
+ * `ownServerUrl` returns that server's URL, which goes to the CLI as
+ * `BB_SERVER_URL`: without it the CLI asks the machine's default server, which
+ * is another bb when two run on one machine. Where `ownServerUrl` throws or
+ * returns nothing, the CLI does not run, so no other server is asked.
+ */
 export function createBbCliReader(
   log: BbPluginApi["log"],
+  ownServerUrl: () => string,
   env: NodeJS.ProcessEnv = process.env,
 ): BbCliReader {
   return () =>
     new Promise((resolve) => {
+      let serverUrl = "";
+      let reason = "it has no URL";
+      try {
+        serverUrl = ownServerUrl().trim();
+      } catch (error) {
+        reason = error instanceof Error ? error.message : String(error);
+      }
+      if (!serverUrl) {
+        log.warn(
+          `could not tell which bb server Thread Glance runs in (${reason}); ` +
+            "importing nothing from bb's CLI and asking no other server",
+        );
+        resolve(null);
+        return;
+      }
       const file = bbCliPath(env);
       execFile(
         file,
         ["thread-list", "prefs", "list", "--json"],
-        { timeout: CLI_TIMEOUT_MS, maxBuffer: CLI_MAX_BUFFER_BYTES, encoding: "utf8" },
+        {
+          env: { ...env, BB_SERVER_URL: serverUrl },
+          timeout: CLI_TIMEOUT_MS,
+          maxBuffer: CLI_MAX_BUFFER_BYTES,
+          encoding: "utf8",
+        },
         (error, stdout) => {
           if (error) {
-            log.warn(`could not run ${file} thread-list prefs list: ${error.message}`);
+            log.warn(`could not run ${file} thread-list prefs list against ${serverUrl}: ${error.message}`);
             resolve(null);
             return;
           }
           try {
             resolve(JSON.parse(stdout) as unknown);
           } catch {
-            log.warn(`${file} thread-list prefs list printed output that is not JSON`);
+            log.warn(`${file} thread-list prefs list against ${serverUrl} printed output that is not JSON`);
             resolve(null);
           }
         },

package/server/preference-store.ts

@@ -6,6 +6,7 @@ import {
   PREFERENCE_KEYS,
   defaultPreferences,
   parsePreference,
+  parseStoredPreference,
   preferenceDefault,
   type PreferenceKey,
   type Preferences,
@@ -59,7 +60,7 @@ export function createPreferenceStore(
   async function read<K extends PreferenceKey>(key: K): Promise<Preferences[K]> {
     const stored = await kv.get<unknown>(preferenceKvKey(key));
     if (stored === undefined) return preferenceDefault(key);
-    const parsed = parsePreference(key, stored);
+    const parsed = parseStoredPreference(key, stored);
     if (parsed.success) return parsed.value;
     bb.log.warn(`stored preference ${key} is invalid (${parsed.message}); using the default`);
     return preferenceDefault(key);

package/server.ts

@@ -25,7 +25,7 @@ export default function threadGlance(bb: BbPluginApi): void {
   const scheduled = createScheduledTracker({
     publish: (signal) => bb.realtime.publish(CHANNELS.scheduled, signal),
   });
-  const readBbCli = createBbCliReader(bb.log);
+  const readBbCli = createBbCliReader(bb.log, () => bb.server.loopbackBaseUrl);
   const importOnce = createSerialQueue();
 
   bb.rpc.register(rpcContract, {

package/shared/preferences.ts

@@ -9,8 +9,8 @@ const idListSchema = z.array(idSchema).max(MAX_ITEMS);
 export const organizationModeSchema = z.enum(["project", "chronological", "machine"]);
 export const sortFieldSchema = z.enum(["updated", "created", "alpha", "none"]);
 export const sortDirectionSchema = z.enum(["default", "ascending", "descending"]);
-export const lifecycleSchema = z.enum(["active", "archived"]);
-export const harnessIconSchema = z.enum(["muted", "colour", "hidden"]);
+export const harnessIconSchema = z.enum(["muted", "colour"]);
+export const settleAfterSchema = z.enum(["12h", "1d", "3d", "1w", "never"]);
 export const childAttentionSchema = z.enum(["blocked", "everything"]);
 
 const hiddenGroupsSchema = z
@@ -21,34 +21,33 @@ const hiddenGroupsSchema = z
 export type OrganizationMode = z.infer<typeof organizationModeSchema>;
 export type SortField = z.infer<typeof sortFieldSchema>;
 export type SortDirection = z.infer<typeof sortDirectionSchema>;
-export type Lifecycle = z.infer<typeof lifecycleSchema>;
 export type HarnessIcon = z.infer<typeof harnessIconSchema>;
 export type ChildAttention = z.infer<typeof childAttentionSchema>;
+export type SettleAfter = z.infer<typeof settleAfterSchema>;
 
 interface PreferenceDefinition<T> {
   schema: z.ZodType<T, unknown>;
   defaultValue: T;
   description: string;
+  /** Maps a value an earlier version stored, which the schema now refuses, onto a current one. */
+  readStored?: (stored: unknown) => unknown;
 }
 
 function define<T>(
   schema: z.ZodType<T, unknown>,
   defaultValue: T,
   description: string,
+  readStored?: (stored: unknown) => unknown,
 ): PreferenceDefinition<T> {
-  return { schema, defaultValue, description };
+  return { schema, defaultValue, description, ...(readStored ? { readStored } : {}) };
 }
 
 /** Server-side preferences, shared across windows and devices. */
 export const PREFERENCES = {
-  threadLifecycles: define(
-    z
-      .array(lifecycleSchema)
-      .min(1)
-      .max(2)
-      .refine((values) => new Set(values).size === values.length, "Lifecycles must be unique"),
-    ["active"] as Lifecycle[],
-    "Threads shown: [\"active\"], [\"archived\"] or both. At least one is required.",
+  showArchived: define(
+    z.boolean(),
+    false,
+    "Show archived threads: whether every group also lists archived threads, as each group's menu toggles.",
   ),
   organizationMode: define(
     organizationModeSchema,
@@ -107,36 +106,36 @@ export const PREFERENCES = {
     [] as string[],
     "Environment ids whose folder row is collapsed.",
   ),
-  foldOlder: define(
-    z.boolean(),
-    true,
-    "Collapse older threads: whether each group's quiet roots past its 5 newest fold behind an N older row.",
-  ),
-  workingFirst: define(
-    z.boolean(),
-    false,
-    "Working threads first: whether working threads sort first under Updated, as bb's list does.",
-  ),
   expandedOlder: define(
     idListSchema,
     [] as string[],
-    "Group ids and parent thread ids whose N older fold the user opened.",
+    "Parent thread ids whose \"N more child threads\" row the user opened, once that tree's children chip was open.",
+  ),
+  openSettledFolds: define(
+    idListSchema,
+    [] as string[],
+    "Group ids whose settled fold the user opened.",
+  ),
+  settleAfter: define(
+    settleAfterSchema,
+    "1d" as SettleAfter,
+    "Settle after: how long a quiet thread goes without activity before it settles into its group's settled fold: 12h, 1d, 3d, 1w or never.",
   ),
   expandedChildren: define(
     idListSchema,
     [] as string[],
     "Parent thread ids whose chip the user opened.",
   ),
-  showPullRequests: define(z.boolean(), true, "Whether rows show a pull request badge."),
   childAttention: define(
     childAttentionSchema,
     "blocked" as ChildAttention,
-    "Needs attention counts every child: blocked counts a child thread that waits on you, is offline or has an orphaned failure; everything also counts every failed or finished-unread child. The same children stay out of a family's older fold, as running ones do.",
+    "Needs attention counts every child: blocked counts a child thread that waits on you, is offline or has an orphaned failure; everything also counts every failed or finished-unread child. The same children stay out of an open tree's N more child threads fold, as running ones do.",
   ),
   harnessIcon: define(
     harnessIconSchema,
     "muted" as HarnessIcon,
-    "How rows draw the harness logo: muted (monochrome), colour (the provider's tint) or hidden.",
+    "How rows draw the harness logo, where a row draws one: muted (monochrome) or colour (the provider's tint). A stored hidden reads as muted.",
+    (stored) => (stored === "hidden" ? "muted" : stored),
   ),
 } as const;
 
@@ -176,6 +175,18 @@ export function parsePreference<K extends PreferenceKey>(
   return { success: false, message: result.error.issues.map((issue) => issue.message).join("; ") };
 }
 
+/**
+ * Parses a value read back from storage: what `parsePreference` accepts, and
+ * the values earlier versions stored that the key maps onto current ones.
+ */
+export function parseStoredPreference<K extends PreferenceKey>(
+  key: K,
+  stored: unknown,
+): ParseResult<Preferences[K]> {
+  const definition: PreferenceDefinition<unknown> = PREFERENCES[key];
+  return parsePreference(key, definition.readStored ? definition.readStored(stored) : stored);
+}
+
 /**
  * Reads a whole preference object, falling back to the default for each key
  * that is missing or invalid. Used for the localStorage mirror.
@@ -186,7 +197,7 @@ export function coercePreferences(raw: unknown): Preferences {
   const record = raw as Record<string, unknown>;
   for (const key of PREFERENCE_KEYS) {
     if (!(key in record)) continue;
-    const parsed = parsePreference(key, record[key]);
+    const parsed = parseStoredPreference(key, record[key]);
     if (parsed.success) (result as Record<string, unknown>)[key] = parsed.value;
   }
   return result;

package/skills/thread-glance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thread-glance
-description: "Reads and changes the Thread Glance sidebar's layout preferences with `bb thread-glance prefs`: grouping, sort, group order, hidden and collapsed groups, child-thread folding, which child threads Needs attention counts, harness icons. Use when asked to change how the Thread Glance sidebar lists, groups, sorts, hides, collapses or folds threads or draws their harness icon."
+description: "Reads and changes the Thread Glance sidebar's layout preferences with `bb thread-glance prefs`: grouping, sort, group order, hidden and collapsed groups, child-thread folding, when threads settle, archived threads, which child threads Needs attention counts, harness icons. Use when asked to change how the Thread Glance sidebar lists, groups, sorts, hides, collapses, folds or settles threads or draws their harness icon."
 ---
 
 # Thread Glance preferences
@@ -20,7 +20,7 @@ bb thread-glance prefs reset <key> [--json]
 
 ```sh
 bb thread-glance prefs set sortDirection ascending
-bb thread-glance prefs set threadLifecycles '["active","archived"]'
+bb thread-glance prefs set settleAfter 3d
 bb thread-glance prefs set hiddenGroups '["threads","project:<project-id>"]'
 ```
 
@@ -38,7 +38,7 @@ and `bb environment list`; a thread id is a `thr_…` id.
 
 | Key | Values | Default |
 | --- | --- | --- |
-| `threadLifecycles` | `active`, `archived`, or both; at least one | `["active"]` |
+| `showArchived` | `true` lists archived threads in every group | `false` |
 | `organizationMode` | `project`, `chronological` (custom sections) or `machine` | `project` |
 | `environmentGrouping` | `true` folds sibling threads sharing a worktree into a folder row | `false` |
 | `chronologicalSort` | `updated`, `created` or `alpha`; `none` reads as `updated` | `updated` |
@@ -52,17 +52,16 @@ and `bb environment list`; a thread id is a `thr_…` id.
 | `collapsedThreadSections` | Custom section keys, `section:<id>` | `[]` |
 | `collapsedMachines` | Machine ids | `[]` |
 | `collapsedEnvironments` | Environment ids of collapsed folder rows | `[]` |
-| `foldOlder` | Collapse older threads: `true` folds a group's quiet top-level threads past its 5 newest behind an "N older" row | `true` |
-| `workingFirst` | `true` sorts working threads first under `updated` | `false` |
-| `expandedOlder` | Group ids and parent thread ids whose "N older" or "N more child threads" row is open | `[]` |
+| `settleAfter` | Settle after: how long a quiet thread goes without activity before its tree can settle into the group's "Settled (N)" fold: `12h`, `1d`, `3d`, `1w` or `never` (then only a merged or closed pull request settles it) | `1d` |
+| `openSettledFolds` | Group ids whose settled fold is open | `[]` |
+| `expandedOlder` | Parent thread ids whose "N more child threads" row is open, once that tree's children chip is open | `[]` |
 | `expandedChildren` | Parent thread ids whose chip is open | `[]` |
-| `showPullRequests` | `true` shows a pull request badge on rows | `true` |
-| `childAttention` | Needs attention counts every child. Which child threads need attention (the Needs attention section, counters, auto-reveal) and stay out of a family's "N more child threads" fold alongside running ones: `blocked` counts a child that waits on you, is offline, or has an orphaned failure (its parent thread idle since); `everything` also counts every failed or unread child | `blocked` |
-| `harnessIcon` | How rows draw the harness logo: `muted` (monochrome), `colour` (the provider's tint) or `hidden` | `muted` |
+| `childAttention` | Needs attention counts every child. Which child threads need attention (collapsed groups, the need-you filter, counters, auto-reveal) and stay out of a tree's "N more child threads" fold alongside running ones: `blocked` counts a child that waits on you, is offline, or has an orphaned failure (its parent thread idle since); `everything` also counts every failed or unread child | `blocked` |
+| `harnessIcon` | How rows that draw a harness logo draw it: `muted` (monochrome) or `colour` (the provider's tint). A row draws one only where its harness differs from bb's default (a root) or its parent thread's (a child) | `muted` |
 
-Row density is kept per browser, and the CLI cannot read or change it. No
-preference filters the list: families that need attention always move into the
-Needs attention section.
+Row density and the need-you filter are kept per browser window, and the CLI
+cannot read or change them. A tree that needs attention always stays in its
+group, drawn even when the group is collapsed.
 
 Sections themselves and the section a thread is in are bb core state: use
 `bb thread section` and `bb thread update`.

package/features/thread-list/data/useAttentionHold.ts

@@ -1,19 +0,0 @@
-// Which family Needs attention holds, as it was when opened, and which family is open, while one of its
-// threads is open. Diffed render to render, as auto-expansion is; nothing here is persisted.
-import { useRef } from "react";
-import type { Forest } from "../model/families";
-import { holdAttention, NO_HOLD, type AttentionHold, type SectionFamily } from "../model/attention";
-
-export function useAttentionHold(forest: Forest | null, activeThreadId: string | null): SectionFamily | null {
-  const hold = useRef<AttentionHold>(NO_HOLD);
-  const lastForest = useRef<Forest | null>(null);
-  const lastActive = useRef<string | null | undefined>(undefined);
-  // Derived during render, so the family never leaves for a frame. Idempotent:
-  // a repeated render with the same inputs keeps what it stored.
-  if (forest !== null && (forest !== lastForest.current || activeThreadId !== lastActive.current)) {
-    hold.current = holdAttention(hold.current, forest, activeThreadId);
-    lastForest.current = forest;
-    lastActive.current = activeThreadId;
-  }
-  return hold.current.held;
-}