paseo-beads 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "paseo-beads",
+  "version": "0.1.0",
+  "description": "Read-only Beads console for Paseo: project progress, ready and waiting work, the critical chain, and a whole-project board, read through bv.",
+  "license": "MIT",
+  "author": "cuongntr",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "beads",
+    "bv",
+    "issue-tracker",
+    "kanban"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cuongntr/paseo-beads-viewer.git"
+  },
+  "homepage": "https://github.com/cuongntr/paseo-beads-viewer#readme",
+  "bugs": {
+    "url": "https://github.com/cuongntr/paseo-beads-viewer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "client",
+    "images",
+    "server",
+    "shared",
+    "index.client.tsx",
+    "index.server.ts",
+    "README.md",
+    "paseo-plugin.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.8.0",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "26.6.1",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.6",
+    "zod": "^4.4.3"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "paseo-beads",
+  "requirements": {
+    "paseo": ">=0.8.0"
+  }
+}

package/server/attachments.ts

@@ -0,0 +1,166 @@
+import type { PluginAttachmentItem, RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { access, constants } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import {
+  ATTACHMENT_RESOURCE_TYPE,
+  ATTACHMENT_RESULT_LIMIT,
+  buildIssueUrl,
+  type SearchResult,
+} from "../shared/beads";
+import { attachmentSearchRpc } from "../shared/rpc";
+import { clampSearchLimit, runBvJson, sanitizeSearchQuery } from "./bv";
+import { buildIssueSnapshot, normalizeSearchResults } from "./normalize";
+import { readIssueDetail } from "./issue";
+
+type AttachmentOutput = RpcOutput<typeof attachmentSearchRpc>;
+
+/**
+ * Attachment search runs without workspace context, so it discovers candidates
+ * itself. Every bound below exists to keep subprocess fanout finite: at most
+ * WORKSPACE_SCAN_LIMIT workspaces are inspected, WORKSPACE_SEARCH_LIMIT of them
+ * are searched, and at most ATTACHMENT_RESULT_LIMIT detail reads follow.
+ */
+const WORKSPACE_SCAN_LIMIT = 12;
+const WORKSPACE_SEARCH_LIMIT = 4;
+const PER_WORKSPACE_SEARCH_LIMIT = 5;
+const SEARCH_CONCURRENCY = 2;
+const DETAIL_CONCURRENCY = 3;
+
+interface Candidate {
+  readonly id: string;
+  readonly name: string;
+  readonly directory: string;
+}
+
+/** Presence of a `.beads` directory. The plugin never reads its contents. */
+async function hasBeadsDirectory(directory: string): Promise<boolean> {
+  try {
+    await access(join(directory, ".beads"), constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function mapWithConcurrency<Input, Output>(
+  inputs: readonly Input[],
+  concurrency: number,
+  run: (input: Input) => Promise<Output>,
+): Promise<Output[]> {
+  const results: Output[] = new Array<Output>(inputs.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(concurrency, inputs.length) }, async () => {
+    for (;;) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= inputs.length) return;
+      const input = inputs[index];
+      if (input === undefined) return;
+      results[index] = await run(input);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+async function findCandidates(context: PluginHandlerContext): Promise<Candidate[]> {
+  let entries: Awaited<ReturnType<PluginHandlerContext["paseo"]["workspaces"]["list"]>>["entries"];
+  try {
+    const listed = await context.paseo.workspaces.list({
+      page: { limit: WORKSPACE_SCAN_LIMIT },
+      sort: [{ key: "activity_at", direction: "desc" }],
+    });
+    entries = listed.entries;
+  } catch {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  const unique: Candidate[] = [];
+  for (const entry of entries) {
+    const directory = entry.workspaceDirectory;
+    if (typeof directory !== "string" || !isAbsolute(directory)) continue;
+    if (seen.has(directory)) continue;
+    seen.add(directory);
+    unique.push({ id: entry.id, name: entry.title ?? entry.name, directory });
+  }
+
+  const enabled = await mapWithConcurrency(unique, DETAIL_CONCURRENCY, async (candidate) => ({
+    candidate,
+    enabled: await hasBeadsDirectory(candidate.directory),
+  }));
+  return enabled
+    .filter((entry) => entry.enabled)
+    .map((entry) => entry.candidate)
+    .slice(0, WORKSPACE_SEARCH_LIMIT);
+}
+
+interface Hit {
+  readonly candidate: Candidate;
+  readonly result: SearchResult;
+}
+
+export async function searchAttachments(
+  input: RpcInput<typeof attachmentSearchRpc>,
+  context: PluginHandlerContext,
+): Promise<AttachmentOutput> {
+  const query = sanitizeSearchQuery(input.query);
+  if (query === null) return { items: [] };
+
+  const candidates = await findCandidates(context);
+  if (candidates.length === 0) return { items: [] };
+
+  const limit = clampSearchLimit(PER_WORKSPACE_SEARCH_LIMIT);
+  // One failing workspace must never remove the other workspaces' results.
+  const perWorkspace = await mapWithConcurrency(candidates, SEARCH_CONCURRENCY, async (candidate) => {
+    const result = await runBvJson(
+      "search",
+      candidate.directory,
+      (payload) => normalizeSearchResults(payload, limit),
+      { query, limit },
+    );
+    return result.ok ? result.value.map((entry) => ({ candidate, result: entry })) : [];
+  });
+
+  const seen = new Set<string>();
+  const hits: Hit[] = [];
+  for (const group of perWorkspace) {
+    for (const hit of group) {
+      const key = `${hit.candidate.id}:${hit.result.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      hits.push(hit);
+      if (hits.length >= ATTACHMENT_RESULT_LIMIT) break;
+    }
+    if (hits.length >= ATTACHMENT_RESULT_LIMIT) break;
+  }
+  if (hits.length === 0) return { items: [] };
+
+  const items = await mapWithConcurrency(hits, DETAIL_CONCURRENCY, async (hit): Promise<PluginAttachmentItem> => {
+    const detail = await readIssueDetail({
+      workspaceId: hit.candidate.id,
+      directory: hit.candidate.directory,
+      issueId: hit.result.id,
+    });
+    const issue = detail.result.ok ? detail.result.value : null;
+    const title = issue?.title ?? hit.result.title;
+    return {
+      id: `${hit.candidate.id}:${hit.result.id}`,
+      identifier: hit.result.id,
+      title,
+      subtitle: `${hit.candidate.name}${issue === null ? "" : ` · ${issue.status}`}`,
+      url: buildIssueUrl(hit.candidate.id, hit.result.id),
+      text: buildIssueSnapshot({
+        workspaceName: hit.candidate.name,
+        workspaceDirectory: hit.candidate.directory,
+        issueId: hit.result.id,
+        title,
+        detail: issue,
+      }),
+      resourceType: ATTACHMENT_RESOURCE_TYPE,
+    };
+  });
+
+  return { items };
+}

package/server/bv.ts

@@ -0,0 +1,213 @@
+import {
+  ISSUE_ID_MAX_LENGTH,
+  SEARCH_LIMIT_DEFAULT,
+  SEARCH_LIMIT_MAX,
+  SEARCH_LIMIT_MIN,
+  SEARCH_QUERY_MAX_LENGTH,
+} from "../shared/beads";
+import { failure, runJsonCommand, runTextCommand, type CommandResult, type JsonCommandRequest } from "./command";
+import type { TrackerRoute } from "./tracker";
+
+export const BV_EXECUTABLE = "bv";
+const JSON_FORMAT_ARGS = ["--format", "json"] as const;
+const CLEAN_BEADS_ENV = { BEADS_DIR: null, BEADS_DB: null, BEADS_JSONL: null, BD_DB: null } as const;
+
+/**
+ * Only these read-only `bv` invocations exist in the plugin. Every argv is
+ * literal; nothing is templated from user input except the bounded search
+ * query and limit below, which are passed as separate argv values.
+ */
+export type BvRobotCommand = "version" | "triage" | "plan" | "alerts" | "graph" | "search";
+
+interface BvInvocation {
+  readonly label: string;
+  readonly args: readonly string[];
+}
+
+// `bv` refreshes the compatibility export in bd/Dolt workspaces. Serialize
+// invocations per workspace so dashboard and attachment reads cannot race on it.
+const workspaceCommandTails = new Map<string, Promise<void>>();
+
+async function serializeWorkspaceCommand<Value>(cwd: string, run: () => Promise<Value>): Promise<Value> {
+  const previous = workspaceCommandTails.get(cwd) ?? Promise.resolve();
+  let release: () => void = () => {};
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.catch(() => {}).then(() => gate);
+  workspaceCommandTails.set(cwd, tail);
+  await previous.catch(() => {});
+  try {
+    return await run();
+  } finally {
+    release();
+    if (workspaceCommandTails.get(cwd) === tail) workspaceCommandTails.delete(cwd);
+  }
+}
+
+export interface BvSearchParams {
+  readonly query: string;
+  readonly limit: number;
+}
+
+/** Collapses whitespace and enforces the shared query bound. */
+export function sanitizeSearchQuery(raw: string): string | null {
+  const collapsed = raw.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0) return null;
+  return collapsed.slice(0, SEARCH_QUERY_MAX_LENGTH);
+}
+
+export function clampSearchLimit(raw: number | undefined): number {
+  if (raw === undefined || !Number.isFinite(raw)) return SEARCH_LIMIT_DEFAULT;
+  const rounded = Math.trunc(raw);
+  return Math.min(SEARCH_LIMIT_MAX, Math.max(SEARCH_LIMIT_MIN, rounded));
+}
+
+export function bvInvocation(command: BvRobotCommand, params?: BvSearchParams): BvInvocation {
+  switch (command) {
+    case "version":
+      return { label: "bv --version", args: ["--version"] };
+    case "triage":
+      return { label: "bv --robot-triage", args: ["--robot-triage", ...JSON_FORMAT_ARGS] };
+    case "plan":
+      return { label: "bv --robot-plan", args: ["--robot-plan", ...JSON_FORMAT_ARGS] };
+    case "alerts":
+      return { label: "bv --robot-alerts", args: ["--robot-alerts", ...JSON_FORMAT_ARGS] };
+    case "graph":
+      // The only read that returns every issue, which is what the board needs;
+      // triage and plan both hand back analysis-selected subsets.
+      return {
+        label: "bv --robot-graph",
+        args: ["--robot-graph", "--graph-format", "json", ...JSON_FORMAT_ARGS],
+      };
+    case "search": {
+      if (params === undefined) {
+        throw new Error("bv --robot-search requires search parameters");
+      }
+      return {
+        label: "bv --robot-search",
+        args: [
+          "--robot-search",
+          `--search=${params.query}`,
+          `--search-limit=${clampSearchLimit(params.limit)}`,
+          ...JSON_FORMAT_ARGS,
+        ],
+      };
+    }
+  }
+}
+
+export function bvCommandRequest(
+  command: BvRobotCommand,
+  cwd: string,
+  params?: BvSearchParams,
+): JsonCommandRequest {
+  const invocation = bvInvocation(command, params);
+  return {
+    label: invocation.label,
+    executableName: BV_EXECUTABLE,
+    args: invocation.args,
+    cwd,
+    env: CLEAN_BEADS_ENV,
+  };
+}
+
+/** Runs one allowlisted `bv` robot command in a fixed workspace directory. */
+export async function runBvJson<Value>(
+  command: Exclude<BvRobotCommand, "version">,
+  cwd: string,
+  parse: (payload: unknown) => Value,
+  params?: BvSearchParams,
+): Promise<CommandResult<Value>> {
+  const request = bvCommandRequest(command, cwd, params);
+  return await serializeWorkspaceCommand(cwd, async () => await runJsonCommand(request, parse));
+}
+
+export async function runBvVersion(cwd: string): Promise<CommandResult<string>> {
+  const request = bvCommandRequest("version", cwd);
+  return await serializeWorkspaceCommand(cwd, async () => await runTextCommand(request));
+}
+
+export function trackerShowInvocation(route: TrackerRoute, issueId: string) {
+  if (issueId.length > ISSUE_ID_MAX_LENGTH || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(issueId)) return null;
+  const safetyArgs = route.kind === "br" ? ["--no-auto-import", "--no-auto-flush"] : [];
+  return {
+    args: ["--db", route.database, ...safetyArgs, "show", "--json", "--", issueId],
+    env: {
+      BEADS_DIR: route.beadsDirectory,
+      BEADS_DB: route.database,
+      BEADS_JSONL: null,
+      BD_DB: route.database,
+    },
+  } as const;
+}
+
+/**
+ * The issue facets `bv --robot-graph` does not carry: type and assignee. CSV
+ * with an explicit `--fields` list is the only compact shape the trackers
+ * offer; their JSON form embeds every description and measured 2.5 MB for the
+ * same 778 issues this returns in 24 KB. The argv is literal and takes no user
+ * input, and the selected columns hold no free text, so no quoted field or
+ * embedded newline can appear.
+ */
+export function trackerFacetsInvocation(route: TrackerRoute) {
+  const safetyArgs = route.kind === "br" ? ["--no-auto-import", "--no-auto-flush"] : [];
+  return {
+    args: [
+      "--db",
+      route.database,
+      ...safetyArgs,
+      "list",
+      "--status",
+      "all",
+      "--fields",
+      "id,issue_type,assignee",
+      "--format",
+      "csv",
+    ],
+    env: {
+      BEADS_DIR: route.beadsDirectory,
+      BEADS_DB: route.database,
+      BEADS_JSONL: null,
+      BD_DB: route.database,
+    },
+  } as const;
+}
+
+/** Runs the facet read. A tracker that rejects these flags degrades to no overlay. */
+export async function runTrackerFacets(route: TrackerRoute, cwd: string): Promise<CommandResult<string>> {
+  const invocation = trackerFacetsInvocation(route);
+  return await runTextCommand({
+    label: `${route.kind} list --format csv`,
+    executableName: route.kind,
+    args: invocation.args,
+    cwd,
+    env: invocation.env,
+  });
+}
+
+/**
+ * The only tracker invocation the plugin performs for one issue: a read-only
+ * detail read. `--` separates the id so an id can never be read as a flag.
+ */
+export async function runTrackerShow<Value>(
+  route: TrackerRoute,
+  cwd: string,
+  issueId: string,
+  parse: (payload: unknown) => Value,
+): Promise<CommandResult<Value>> {
+  const invocation = trackerShowInvocation(route, issueId);
+  if (invocation === null) {
+    return failure("internal", "Refusing to query an issue id with unexpected characters.");
+  }
+  return await runJsonCommand(
+    {
+      label: `${route.kind} show --json`,
+      executableName: route.kind,
+      args: invocation.args,
+      cwd,
+      env: invocation.env,
+    },
+    parse,
+  );
+}

package/server/cache.ts

@@ -0,0 +1,51 @@
+/**
+ * Short-lived cache of normalized command results only. Nothing derived from
+ * graph analysis is stored, and entries are invalidated purely by expiry, so a
+ * stale dependency graph can never be served from here.
+ */
+interface CacheEntry<Value> {
+  readonly value: Value;
+  readonly expiresAt: number;
+}
+
+export class ExpiringCache<Value> {
+  private readonly entries = new Map<string, CacheEntry<Value>>();
+
+  constructor(
+    private readonly ttlMs: number,
+    private readonly maxEntries = 32,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  get(key: string): Value | null {
+    const entry = this.entries.get(key);
+    if (entry === undefined) return null;
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  set(key: string, value: Value): void {
+    if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) this.entries.delete(oldest.value);
+    }
+    // Refresh insertion order as well as expiry when replacing an entry.
+    this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: this.now() + this.ttlMs });
+  }
+
+  delete(key: string): void {
+    this.entries.delete(key);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}