paseo-beads 0.1.0

package/server/command.ts

@@ -0,0 +1,343 @@
+import { access, constants } from "node:fs/promises";
+import { delimiter, isAbsolute, join } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import type { CommandError, CommandErrorCode } from "../shared/beads";
+
+export interface CommandLimits {
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+}
+
+export const DEFAULT_LIMITS: CommandLimits = {
+  timeoutMs: 20_000,
+  maxOutputBytes: 4 * 1024 * 1024,
+};
+
+/** Raw process outcome, before it is interpreted as JSON. */
+export interface ProcessOutcome {
+  readonly exitCode: number | null;
+  readonly signal: string | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+  readonly truncated: boolean;
+}
+
+export type CommandResult<Value> =
+  | { readonly ok: true; readonly value: Value }
+  | { readonly ok: false; readonly error: CommandError };
+
+function commandError(code: CommandErrorCode, message: string, exitCode: number | null = null): CommandError {
+  return { code, message, exitCode };
+}
+
+export function failure(code: CommandErrorCode, message: string, exitCode: number | null = null): CommandResult<never> {
+  return { ok: false, error: commandError(code, message, exitCode) };
+}
+
+/** Keeps stderr useful without leaking a multi-megabyte blob into the UI. */
+export function summarizeStderr(stderr: string, maxLength = 400): string {
+  const collapsed = stderr.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxLength) return collapsed;
+  return `${collapsed.slice(0, maxLength)}…`;
+}
+
+const executableCache = new Map<string, string | null>();
+const activeProcesses = new Set<ChildProcess>();
+
+async function isExecutableFile(candidate: string): Promise<boolean> {
+  try {
+    await access(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolves a bare tool name to an absolute path by scanning `PATH` directly.
+ * No shell is involved, so `PATH` entries cannot inject arguments or operators.
+ */
+export async function resolveExecutable(name: string): Promise<string | null> {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) return null;
+  const cached = executableCache.get(name);
+  if (cached !== undefined) return cached;
+
+  const searchPath = process.env.PATH ?? "";
+  let resolved: string | null = null;
+  for (const entry of searchPath.split(delimiter)) {
+    if (entry.length === 0) continue;
+    if (!isAbsolute(entry)) continue;
+    const candidate = join(entry, name);
+    if (await isExecutableFile(candidate)) {
+      resolved = candidate;
+      break;
+    }
+  }
+  // Do not cache misses: installing a missing CLI should take effect on the next
+  // explicit refresh without requiring a plugin reload.
+  if (resolved !== null) executableCache.set(name, resolved);
+  return resolved;
+}
+
+/** Test seam: lets unit tests exercise resolution failures without touching `PATH`. */
+export function primeExecutableCache(name: string, value: string | null): void {
+  executableCache.set(name, value);
+}
+
+export function clearExecutableCache(): void {
+  executableCache.clear();
+}
+
+/** Terminates every process this module still owns. Used by plugin cleanup. */
+export function killActiveProcesses(): void {
+  for (const child of activeProcesses) {
+    child.kill("SIGKILL");
+  }
+  activeProcesses.clear();
+}
+
+export type BeadsEnvironment = Readonly<
+  Partial<Record<"BEADS_DIR" | "BEADS_DB" | "BEADS_JSONL" | "BD_DB", string | null>>
+>;
+
+function childEnvironment(overrides: BeadsEnvironment | undefined): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env, NO_COLOR: "1", CLICOLOR: "0" };
+  if (overrides === undefined) return env;
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === null) delete env[key];
+    else env[key] = value;
+  }
+  return env;
+}
+
+export interface SpawnRequest {
+  /** Absolute path to the executable. Never a shell string. */
+  readonly executable: string;
+  /** Literal argv. Values are passed verbatim; no interpolation, no shell. */
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly limits?: CommandLimits;
+  readonly env?: BeadsEnvironment;
+}
+
+/**
+ * Spawns a process with a literal argv, a fixed cwd, a hard timeout, and an
+ * output cap. `shell` is never enabled.
+ */
+export async function runProcess(request: SpawnRequest): Promise<ProcessOutcome> {
+  const limits = request.limits ?? DEFAULT_LIMITS;
+  return await new Promise<ProcessOutcome>((resolve, reject) => {
+    const child = spawn(request.executable, [...request.args], {
+      cwd: request.cwd,
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: childEnvironment(request.env),
+    });
+    activeProcesses.add(child);
+
+    let stdout = "";
+    let stderr = "";
+    let stdoutBytes = 0;
+    let truncated = false;
+    let timedOut = false;
+    let settled = false;
+    let killGraceTimer: NodeJS.Timeout | null = null;
+
+    const finish = (outcome: ProcessOutcome): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killGraceTimer !== null) clearTimeout(killGraceTimer);
+      activeProcesses.delete(child);
+      resolve(outcome);
+    };
+
+    // A grandchild can inherit the pipes and prevent `close` after this child is
+    // killed. Bound that case too, otherwise one timeout can pin the per-workspace queue.
+    const killAndBoundClose = (): void => {
+      child.kill("SIGKILL");
+      if (killGraceTimer !== null) return;
+      killGraceTimer = setTimeout(() => {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        finish({
+          exitCode: child.exitCode,
+          signal: child.signalCode,
+          stdout,
+          stderr,
+          timedOut,
+          truncated,
+        });
+      }, 250);
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killAndBoundClose();
+    }, limits.timeoutMs);
+
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      stdoutBytes += Buffer.byteLength(chunk, "utf8");
+      if (stdoutBytes > limits.maxOutputBytes) {
+        if (!truncated) {
+          truncated = true;
+          killAndBoundClose();
+        }
+        return;
+      }
+      stdout += chunk;
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      if (stderr.length < 8192) stderr += chunk;
+    });
+
+    child.on("error", (error: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killGraceTimer !== null) clearTimeout(killGraceTimer);
+      activeProcesses.delete(child);
+      reject(error);
+    });
+
+    child.on("close", (exitCode: number | null, signal: NodeJS.Signals | null) => {
+      finish({ exitCode, signal, stdout, stderr, timedOut, truncated });
+    });
+  });
+}
+
+/**
+ * Maps a raw process outcome onto the plugin's error taxonomy. Timeout, output
+ * overrun, non-zero exit, and malformed JSON stay distinguishable.
+ */
+export function interpretJsonOutcome<Value>(
+  label: string,
+  outcome: ProcessOutcome,
+  parse: (payload: unknown) => Value,
+): CommandResult<Value> {
+  if (outcome.truncated) {
+    return failure("output_limit", `${label} produced more output than the plugin accepts.`, outcome.exitCode);
+  }
+  if (outcome.timedOut) {
+    return failure("timeout", `${label} timed out.`, outcome.exitCode);
+  }
+
+  const trimmed = outcome.stdout.trim();
+  if (trimmed.length === 0) {
+    const detail = summarizeStderr(outcome.stderr);
+    if (outcome.exitCode === 0) {
+      return failure("invalid_json", `${label} returned no output.`, outcome.exitCode);
+    }
+    return failure(
+      "exit",
+      detail.length > 0 ? `${label} failed: ${detail}` : `${label} failed with exit code ${outcome.exitCode ?? "unknown"}.`,
+      outcome.exitCode,
+    );
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(trimmed) as unknown;
+  } catch {
+    if (outcome.exitCode !== 0) {
+      const detail = summarizeStderr(outcome.stderr);
+      return failure(
+        "exit",
+        detail.length > 0 ? `${label} failed: ${detail}` : `${label} failed with exit code ${outcome.exitCode ?? "unknown"}.`,
+        outcome.exitCode,
+      );
+    }
+    return failure("invalid_json", `${label} returned output that is not JSON.`, outcome.exitCode);
+  }
+
+  if (outcome.exitCode !== 0) {
+    const record = typeof payload === "object" && payload !== null && !Array.isArray(payload) ? payload as Record<string, unknown> : null;
+    const payloadError = typeof record?.["error"] === "string" ? record["error"].trim() : "";
+    const stderrDetail = summarizeStderr(outcome.stderr);
+    const detail = payloadError || stderrDetail;
+    return failure(
+      "exit",
+      detail.length > 0 ? `${label} failed: ${detail}` : `${label} failed with exit code ${outcome.exitCode}.`,
+      outcome.exitCode,
+    );
+  }
+
+  try {
+    return { ok: true, value: parse(payload) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "unrecognized payload";
+    return failure("invalid_json", `${label} returned an unexpected payload: ${message}`, outcome.exitCode);
+  }
+}
+
+export interface JsonCommandRequest {
+  readonly label: string;
+  readonly executableName: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly limits?: CommandLimits;
+  readonly env?: BeadsEnvironment;
+}
+
+/** Resolves the executable, runs it, and interprets its stdout as JSON. */
+export async function runJsonCommand<Value>(
+  request: JsonCommandRequest,
+  parse: (payload: unknown) => Value,
+): Promise<CommandResult<Value>> {
+  const executable = await resolveExecutable(request.executableName);
+  if (executable === null) {
+    return failure("unavailable", `${request.executableName} was not found on the daemon PATH.`);
+  }
+
+  let outcome: ProcessOutcome;
+  try {
+    outcome = await runProcess({
+      executable,
+      args: request.args,
+      cwd: request.cwd,
+      limits: request.limits,
+      env: request.env,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "spawn failed";
+    return failure("unavailable", `${request.label} could not start: ${message}`);
+  }
+
+  return interpretJsonOutcome(request.label, outcome, parse);
+}
+
+/** Runs a command purely for its text output, e.g. `--version`. */
+export async function runTextCommand(request: JsonCommandRequest): Promise<CommandResult<string>> {
+  const executable = await resolveExecutable(request.executableName);
+  if (executable === null) {
+    return failure("unavailable", `${request.executableName} was not found on the daemon PATH.`);
+  }
+  let outcome: ProcessOutcome;
+  try {
+    outcome = await runProcess({
+      executable,
+      args: request.args,
+      cwd: request.cwd,
+      limits: request.limits,
+      env: request.env,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "spawn failed";
+    return failure("unavailable", `${request.label} could not start: ${message}`);
+  }
+  if (outcome.truncated) return failure("output_limit", `${request.label} produced more output than the plugin accepts.`, outcome.exitCode);
+  if (outcome.timedOut) return failure("timeout", `${request.label} timed out.`, outcome.exitCode);
+  if (outcome.exitCode !== 0) {
+    const detail = summarizeStderr(outcome.stderr);
+    return failure(
+      "exit",
+      detail.length > 0 ? `${request.label} failed: ${detail}` : `${request.label} failed.`,
+      outcome.exitCode,
+    );
+  }
+  return { ok: true, value: outcome.stdout.trim() };
+}

package/server/dashboard.ts

@@ -0,0 +1,244 @@
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { CommandError, SectionState } from "../shared/beads";
+import { dashboardRpc } from "../shared/rpc";
+import { runBvJson, runBvVersion, runTrackerFacets } from "./bv";
+import { ExpiringCache } from "./cache";
+import type { CommandResult } from "./command";
+import {
+  EMPTY_FACETS,
+  normalizeAlertSummary,
+  normalizeAlerts,
+  normalizeBlockers,
+  normalizeBoardIssues,
+  normalizeCounts,
+  normalizeHealth,
+  normalizePlanSummary,
+  normalizeRecommendations,
+  normalizeSource,
+  normalizeTracks,
+  parseTrackerFacets,
+  readPayloadError,
+  type TrackerFacets,
+} from "./normalize";
+import { rememberTracker, resolveTrackerFromPayload, type TrackerResolution } from "./tracker";
+import { resolveWorkspaceTarget, UNKNOWN_TRACKER } from "./workspace";
+
+type DashboardOutput = RpcOutput<typeof dashboardRpc>;
+
+const DASHBOARD_TTL_MS = 15_000;
+const dashboardCache = new ExpiringCache<DashboardOutput>(DASHBOARD_TTL_MS);
+const dashboardGenerations = new ExpiringCache<number>(300_000);
+
+export function clearDashboardCache(): void {
+  dashboardCache.clear();
+  dashboardGenerations.clear();
+}
+
+const OK_SECTION: SectionState = { status: "ok", error: null };
+
+/** No graph read happened, so the board has nothing rather than a guess. */
+function emptyBoard(): DashboardOutput["board"] {
+  return { issues: [], typed: false, total: 0, truncated: false };
+}
+
+function degraded(error: CommandError): SectionState {
+  return { status: "unavailable", error };
+}
+
+function sectionOf(result: CommandResult<unknown>): SectionState {
+  if (!result.ok) return degraded(result.error);
+  const payloadError = readPayloadError(result.value);
+  return payloadError === null
+    ? OK_SECTION
+    : degraded({ code: "exit", message: payloadError, exitCode: null });
+}
+
+function identity(payload: unknown): unknown {
+  return payload;
+}
+
+/**
+ * A directory without a Beads project makes `bv` exit non-zero while still
+ * printing a valid JSON envelope carrying a top-level `error`. When it cannot
+ * even print JSON, the exit message is matched instead. Either way this is an
+ * ordinary, representable state rather than a plugin failure.
+ */
+function isMissingProject(error: CommandError): boolean {
+  if (error.code !== "exit") return false;
+  return /beads directory|br init|bd init|no such file|not initialized/i.test(error.message);
+}
+
+export type ProjectState = "ready" | "missing" | "error";
+
+export interface ProjectClassification {
+  readonly projectState: ProjectState;
+  readonly triage: SectionState;
+}
+
+/**
+ * Separates "no Beads project here" and "the triage read failed" from
+ * "healthy project that happens to be empty".
+ */
+export function classifyProject(triage: CommandResult<unknown>): ProjectClassification {
+  if (!triage.ok) {
+    return {
+      projectState: isMissingProject(triage.error) ? "missing" : "error",
+      triage: degraded(triage.error),
+    };
+  }
+  const loadError = readPayloadError(triage.value);
+  if (loadError !== null) {
+    const error: CommandError = { code: "exit", message: loadError, exitCode: null };
+    return { projectState: isMissingProject(error) ? "missing" : "error", triage: degraded(error) };
+  }
+  return { projectState: "ready", triage: OK_SECTION };
+}
+
+export async function getDashboard(
+  input: RpcInput<typeof dashboardRpc>,
+  context: PluginHandlerContext,
+): Promise<DashboardOutput> {
+  const previousGeneration = dashboardGenerations.get(input.workspaceId) ?? 0;
+  const requestGeneration = input.refresh === true ? previousGeneration + 1 : previousGeneration;
+  if (input.refresh === true) dashboardGenerations.set(input.workspaceId, requestGeneration);
+
+  const fetchedAt = new Date().toISOString();
+  const workspace = await resolveWorkspaceTarget(context, input.workspaceId);
+  if (!workspace.ok) {
+    return {
+      workspaceId: input.workspaceId,
+      directory: null,
+      tool: { available: false, version: null, error: workspace.error },
+      tracker: UNKNOWN_TRACKER,
+      projectState: "error",
+      source: null,
+      counts: null,
+      health: null,
+      recommendations: [],
+      blockers: [],
+      board: emptyBoard(),
+      tracks: [],
+      planSummary: null,
+      alerts: [],
+      alertSummary: null,
+      sections: {
+        triage: degraded(workspace.error),
+        plan: degraded(workspace.error),
+        alerts: degraded(workspace.error),
+        graph: degraded(workspace.error),
+      },
+      fetchedAt,
+      cached: false,
+    };
+  }
+
+  const { directory } = workspace.value;
+  const cacheKey = `${input.workspaceId}\0${directory}`;
+  if (input.refresh === true) {
+    dashboardCache.delete(cacheKey);
+  } else {
+    const cached = dashboardCache.get(cacheKey);
+    if (cached !== null) return { ...cached, cached: true };
+  }
+
+  const version = await runBvVersion(directory);
+  if (!version.ok) {
+    return {
+      workspaceId: input.workspaceId,
+      directory,
+      tool: { available: false, version: null, error: version.error },
+      tracker: UNKNOWN_TRACKER,
+      projectState: "error",
+      source: null,
+      counts: null,
+      health: null,
+      recommendations: [],
+      blockers: [],
+      board: emptyBoard(),
+      tracks: [],
+      planSummary: null,
+      alerts: [],
+      alertSummary: null,
+      sections: {
+        triage: degraded(version.error),
+        plan: degraded(version.error),
+        alerts: degraded(version.error),
+        graph: degraded(version.error),
+      },
+      fetchedAt,
+      cached: false,
+    };
+  }
+
+  // These analyses are logically independent; server/bv serializes their subprocesses per workspace to avoid bd export races.
+  const [triage, plan, alerts, graph] = await Promise.all([
+    runBvJson("triage", directory, identity),
+    runBvJson("plan", directory, identity),
+    runBvJson("alerts", directory, identity),
+    runBvJson("graph", directory, identity),
+  ]);
+
+  const triagePayload = triage.ok ? triage.value : null;
+  const planPayload = plan.ok ? plan.value : null;
+  const alertsPayload = alerts.ok ? alerts.value : null;
+  const graphSection = sectionOf(graph);
+  const graphPayload = graphSection.status === "ok" && graph.ok ? graph.value : null;
+
+  const classification = classifyProject(triage);
+  const projectState = classification.projectState;
+
+  const source = normalizeSource(triagePayload) ?? normalizeSource(planPayload) ?? normalizeSource(alertsPayload);
+  const trackerResolution: TrackerResolution =
+    projectState === "ready"
+      ? await resolveTrackerFromPayload(triagePayload, directory)
+      : { state: UNKNOWN_TRACKER, route: null };
+  const tracker = trackerResolution.state;
+  if (tracker.kind !== null) rememberTracker(input.workspaceId, directory, trackerResolution);
+
+  // The graph carries no type or assignee, so the type and assignee facets
+  // depend on this overlay. A tracker that is absent or rejects the flags costs
+  // those two facets and nothing else; it never fails the dashboard.
+  let facets: TrackerFacets = EMPTY_FACETS;
+  if (trackerResolution.route !== null && graphPayload !== null) {
+    const csv = await runTrackerFacets(trackerResolution.route, directory);
+    if (csv.ok) facets = parseTrackerFacets(csv.value);
+  }
+
+  const triageSection = classification.triage;
+
+  const output: DashboardOutput = {
+    workspaceId: input.workspaceId,
+    directory,
+    tool: { available: true, version: version.value, error: null },
+    tracker,
+    projectState,
+    source,
+    counts: normalizeCounts(triagePayload),
+    health: normalizeHealth(triagePayload),
+    recommendations: normalizeRecommendations(triagePayload),
+    blockers: normalizeBlockers(triagePayload),
+    board: normalizeBoardIssues(graphPayload, facets),
+    tracks: normalizeTracks(planPayload),
+    planSummary: normalizePlanSummary(planPayload),
+    alerts: normalizeAlerts(alertsPayload),
+    alertSummary: normalizeAlertSummary(alertsPayload),
+    sections: {
+      triage: triageSection,
+      plan: sectionOf(plan),
+      alerts: sectionOf(alerts),
+      graph: graphSection,
+    },
+    fetchedAt,
+    cached: false,
+  };
+
+  // Only a fully readable, non-superseded snapshot is worth reusing.
+  if (
+    triageSection.status === "ok" &&
+    (dashboardGenerations.get(input.workspaceId) ?? 0) === requestGeneration
+  ) {
+    dashboardCache.set(cacheKey, output);
+  }
+  return output;
+}

package/server/issue.ts

@@ -0,0 +1,59 @@
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { IssueDetail } from "../shared/beads";
+import { issueRpc } from "../shared/rpc";
+import { runTrackerShow } from "./bv";
+import { failure, type CommandResult } from "./command";
+import { normalizeIssueDetail } from "./normalize";
+import { resolveTracker } from "./tracker";
+import { resolveWorkspaceTarget } from "./workspace";
+
+type IssueOutput = RpcOutput<typeof issueRpc>;
+
+function parseDetail(payload: unknown): IssueDetail {
+  const detail = normalizeIssueDetail(payload);
+  if (detail === null) throw new Error("no issue record in the response");
+  return detail;
+}
+
+/** Read-only detail read. There is no mutation path in this plugin. */
+export async function readIssueDetail(input: {
+  readonly workspaceId: string;
+  readonly directory: string;
+  readonly issueId: string;
+}): Promise<{ readonly tracker: IssueOutput["tracker"]; readonly result: CommandResult<IssueDetail> }> {
+  const resolution = await resolveTracker(input.workspaceId, input.directory);
+  const tracker = resolution.state;
+  if (resolution.route === null || tracker.kind === null || !tracker.available) {
+    return {
+      tracker,
+      result: failure(
+        "tracker_unknown",
+        tracker.detail ?? "The Beads tracker CLI for this workspace could not be established.",
+      ),
+    };
+  }
+  const result = await runTrackerShow(resolution.route, input.directory, input.issueId, parseDetail);
+  return { tracker, result };
+}
+
+export async function getIssue(
+  input: RpcInput<typeof issueRpc>,
+  context: PluginHandlerContext,
+): Promise<IssueOutput> {
+  const workspace = await resolveWorkspaceTarget(context, input.workspaceId);
+  if (!workspace.ok) {
+    return { issueId: input.issueId, tracker: { kind: null, available: false, detail: null }, issue: null, error: workspace.error };
+  }
+
+  const { tracker, result } = await readIssueDetail({
+    workspaceId: input.workspaceId,
+    directory: workspace.value.directory,
+    issueId: input.issueId,
+  });
+
+  if (!result.ok) {
+    return { issueId: input.issueId, tracker, issue: null, error: result.error };
+  }
+  return { issueId: input.issueId, tracker, issue: result.value, error: null };
+}