@omercnet/paseo-beads 0.1.0-next.72.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.1.0](https://github.com/omercnet/paseo-plugins/compare/paseo-beads-v0.0.1...paseo-beads-v0.1.0) (2026-09-11)
+
+
+### Features
+
+* **paseo-beads:** add workspace bead viewer ([#13](https://github.com/omercnet/paseo-plugins/issues/13)) ([96e02e5](https://github.com/omercnet/paseo-plugins/commit/96e02e5521521b738cf11e8240d3926849898c3e))
+
+## 0.0.1 (2026-09-11)
+
+### Features
+
+- add a read-only, workspace-scoped Beads Explorer panel and Command Center entry
+- group active issues into Ready frontier, In progress, Blocked, and Other lanes using an
+  authoritative `bd list --ready` snapshot
+- add virtualized issue lists, search, and All, P0–P1, and Assigned filters
+- add responsive issue details with context, acceptance criteria, dependencies, and dependents
+- bound CLI output and RPC payloads while keeping unexpected CLI details out of client-facing errors
+- add descriptive accessibility labels and focus restoration for compact list/detail navigation
+- poll list and selected detail data every 10 seconds through read-only `bd` CLI calls
+- report unavailable, uninitialized, empty, failed, missing-detail, and truncated states

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Paseo Beads
+
+A dependency-aware Beads work queue for every Paseo workspace. Paseo Beads turns active issues into
+a read-only delivery view that makes the ready frontier, work in progress, and blockers immediately
+visible.
+
+It adds a workspace-scoped **Beads** Explorer panel and an **Open Beads** Command Center item.
+
+## Screenshots
+
+Issue IDs, titles, assignees, labels, and issue details in these screenshots are synthetic. They do
+not contain data from a real Beads project.
+
+### Wide
+
+![Paseo Beads wide work queue](docs/images/paseo-beads-wide.png)
+
+### Compact
+
+![Paseo Beads compact work queue](docs/images/paseo-beads-compact.png)
+
+## What it shows
+
+- Active issues grouped into **Ready frontier**, **In progress**, **Blocked**, and **Other** lanes.
+- Priority, issue ID, title, type, assignee, labels, and relationship and comment counts on each row.
+- Lane totals, text search over ID, title, assignee, and labels, and **All**, **P0–P1**, and
+  **Assigned** filters.
+- A detail view with status, readiness, priority, type, assignee, parent, labels, description,
+  acceptance criteria, design, notes, dependencies, dependents, and update time.
+- A side-by-side list and detail view when space permits, with list/detail navigation in compact
+  layouts.
+- A virtualized issue list, descriptive accessibility labels, and focus restoration when navigating
+  between the compact list and detail view.
+
+Within each lane, issues are ordered by priority, most recent update, then ID. In-progress and hooked
+issues enter **In progress** first; remaining blocked issues enter **Blocked**; ready issues enter
+**Ready frontier**; all remaining active issues enter **Other**.
+
+## How it works
+
+The panel calls workspace-scoped Paseo plugin RPC handlers. On the daemon host, each handler resolves
+the workspace directory through Paseo and executes the `bd` CLI with `--readonly` and `-C`:
+
+- The list handler runs `bd list --json --sort priority`, then runs one authoritative
+  `bd list --ready --json --limit 0` query and intersects its IDs with the displayed issues.
+- Selecting an issue runs `bd show <issue-id> --json --include-dependents` plus the same authoritative
+  readiness query.
+
+The server validates and normalizes the CLI JSON before returning bounded data to the panel. The
+plugin never reads or writes `.beads` storage directly and exposes no issue mutation controls.
+
+The list and selected detail poll every 10 seconds. **Refresh** requests the list immediately. A
+failed background refresh keeps the previous data visible with an inline error; initial and detail
+failures provide a retry action.
+
+## Limits
+
+- Paseo `^0.8.0` with plugins enabled is required.
+- Beads `bd` 1.0 or newer must be available on the Paseo daemon's `PATH`.
+- A Beads project must be initialized in the workspace for issue data to appear.
+- CLI calls time out after 10 seconds and accept at most 8 MiB of output. Unexpected CLI details stay
+  in Paseo plugin logs; the panel receives a stable, sanitized error message.
+- At most 500 issues are displayed. When more exist, the panel warns that lane counts and local
+  search results may be incomplete.
+- The server rejects oversized IDs, titles, body fields, labels, relationships, comments, and
+  readiness sets rather than transferring unbounded data to the client.
+- Search and filters operate only on the displayed snapshot.
+- The panel distinguishes an unavailable `bd` binary, an uninitialized Beads project, an empty
+  project, request failures, and missing issue details.
+- This plugin is read-only and workspace-scoped. It uses the `bd` CLI exclusively and does not
+  create, edit, close, or assign issues.
+
+## Install
+
+Paseo plugins are trusted, unsandboxed code. Review the source before installing it on the daemon
+host.
+
+From npm:
+
+```bash
+paseo plugin install npm:@omercnet/paseo-beads
+```
+
+From GitHub:
+
+```bash
+paseo plugin add omercnet/paseo-plugins:paseo-beads
+```
+
+From a local checkout on the Paseo daemon host:
+
+```bash
+git clone https://github.com/omercnet/paseo-plugins.git
+cd paseo-plugins/paseo-beads
+npm ci
+paseo plugin install "$PWD"
+```
+
+Open a workspace, choose **New tab** in Explorer, then select **Beads**. You can also run **Open
+Beads** from the Command Center while viewing a workspace or one of its agents.
+
+## Develop
+
+```bash
+npm ci
+npm run check
+npm test
+npm run test:coverage
+npm run typecheck
+paseo plugin install "$PWD"
+paseo plugin reload paseo-beads
+```
+
+The package is `@omercnet/paseo-beads` at version `0.0.1`. Release Please maintains versions,
+changelog entries, component tags, and GitHub releases from Conventional Commits in the monorepo.

package/client/beads-view.ts

@@ -0,0 +1,155 @@
+import type { BeadSummary } from "../shared/beads";
+
+export const BEAD_LANES = ["ready", "in_progress", "blocked", "other"] as const;
+
+export type BeadLane = (typeof BEAD_LANES)[number];
+
+export const BEAD_LANE_TITLES: Record<BeadLane, string> = {
+  ready: "Ready",
+  in_progress: "In progress",
+  blocked: "Blocked",
+  other: "Other",
+};
+
+export const BEAD_LANE_METADATA: readonly { id: BeadLane; title: string }[] = BEAD_LANES.map(
+  (id) => ({ id, title: BEAD_LANE_TITLES[id] }),
+);
+
+export type BeadsFilter = "all" | "high_priority" | "assigned";
+
+export interface BeadsViewOptions {
+  query?: string;
+  filter?: BeadsFilter;
+}
+
+export type BeadLanes = Record<BeadLane, BeadSummary[]>;
+export type BeadLaneCounts = Record<BeadLane, number>;
+
+export interface BeadsView {
+  lanes: BeadLanes;
+  counts: BeadLaneCounts;
+}
+
+export interface BeadSection {
+  lane: BeadLane;
+  title: string;
+  data: BeadSummary[];
+}
+
+export function buildBeadSections(view: BeadsView, activeFiltering: boolean): BeadSection[] {
+  const sections: BeadSection[] = [];
+
+  for (const lane of BEAD_LANES) {
+    const data = view.lanes[lane];
+    if (activeFiltering && data.length === 0) continue;
+
+    sections.push({
+      lane,
+      title: lane === "ready" ? "Ready frontier" : BEAD_LANE_TITLES[lane],
+      data,
+    });
+  }
+
+  return sections;
+}
+
+export function issueAccessibilityLabel(issue: BeadSummary, lane: BeadLane): string {
+  const laneDescription = lane === "ready" ? "Ready frontier" : `${BEAD_LANE_TITLES[lane]} lane`;
+  const assigneeDescription = issue.assignee ? `Assigned to ${issue.assignee}` : "Unassigned";
+  const activity: string[] = [];
+
+  if (issue.dependencyCount > 0) {
+    activity.push(
+      `${issue.dependencyCount} ${issue.dependencyCount === 1 ? "dependency" : "dependencies"}`,
+    );
+  }
+  if (issue.dependentCount > 0) {
+    activity.push(
+      `${issue.dependentCount} ${issue.dependentCount === 1 ? "dependent" : "dependents"}`,
+    );
+  }
+  if (issue.commentCount > 0) {
+    activity.push(`${issue.commentCount} ${issue.commentCount === 1 ? "comment" : "comments"}`);
+  }
+
+  const descriptions = [
+    `Open issue ${issue.id}: ${issue.title}`,
+    `Priority P${issue.priority}`,
+    laneDescription,
+    `Issue type ${issue.issueType}`,
+    assigneeDescription,
+    ...activity,
+  ];
+
+  return `${descriptions.join(". ")}.`;
+}
+
+export function beadLaneFor(issue: BeadSummary): BeadLane {
+  if (issue.status === "in_progress" || issue.status === "hooked") return "in_progress";
+  if (issue.isBlocked) return "blocked";
+  if (issue.isReady) return "ready";
+  return "other";
+}
+
+function matchesSearch(issue: BeadSummary, query: string): boolean {
+  if (!query) return true;
+  if (issue.id.toLowerCase().includes(query)) return true;
+  if (issue.title.toLowerCase().includes(query)) return true;
+  if (issue.assignee?.toLowerCase().includes(query)) return true;
+  return issue.labels.some((label) => label.toLowerCase().includes(query));
+}
+
+function matchesFilter(issue: BeadSummary, filter: BeadsFilter): boolean {
+  if (filter === "high_priority") return issue.priority <= 1;
+  if (filter === "assigned") return issue.assignee !== null;
+  return true;
+}
+
+function updatedTimestamp(updatedAt: string | null): number {
+  if (updatedAt === null) return Number.NEGATIVE_INFINITY;
+  const timestamp = Date.parse(updatedAt);
+  return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY;
+}
+
+function compareBeads(left: BeadSummary, right: BeadSummary): number {
+  const byPriority = left.priority - right.priority;
+  if (byPriority !== 0) return byPriority;
+
+  const leftUpdatedAt = updatedTimestamp(left.updatedAt);
+  const rightUpdatedAt = updatedTimestamp(right.updatedAt);
+  if (leftUpdatedAt !== rightUpdatedAt) return rightUpdatedAt > leftUpdatedAt ? 1 : -1;
+
+  if (left.id < right.id) return -1;
+  if (left.id > right.id) return 1;
+  return 0;
+}
+
+export function buildBeadsView(
+  issues: readonly BeadSummary[],
+  options: BeadsViewOptions = {},
+): BeadsView {
+  const lanes: BeadLanes = {
+    ready: [],
+    in_progress: [],
+    blocked: [],
+    other: [],
+  };
+  const counts: BeadLaneCounts = {
+    ready: 0,
+    in_progress: 0,
+    blocked: 0,
+    other: 0,
+  };
+  const query = options.query?.trim().toLowerCase() ?? "";
+  const filter = options.filter ?? "all";
+
+  for (const issue of issues) {
+    const lane = beadLaneFor(issue);
+    counts[lane] += 1;
+    if (matchesFilter(issue, filter) && matchesSearch(issue, query)) lanes[lane].push(issue);
+  }
+
+  for (const lane of BEAD_LANES) lanes[lane].sort(compareBeads);
+
+  return { lanes, counts };
+}