paseo-beads 0.1.0

package/server/search.ts

@@ -0,0 +1,40 @@
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { searchRpc } from "../shared/rpc";
+import { clampSearchLimit, runBvJson, sanitizeSearchQuery } from "./bv";
+import { normalizeSearchResults } from "./normalize";
+import { resolveWorkspaceTarget } from "./workspace";
+
+type SearchOutput = RpcOutput<typeof searchRpc>;
+
+export async function searchIssues(
+  input: RpcInput<typeof searchRpc>,
+  context: PluginHandlerContext,
+): Promise<SearchOutput> {
+  const limit = clampSearchLimit(input.limit);
+  const query = sanitizeSearchQuery(input.query);
+  if (query === null) {
+    return {
+      query: "",
+      limit,
+      results: [],
+      error: { code: "internal", message: "Enter at least one searchable character.", exitCode: null },
+    };
+  }
+
+  const workspace = await resolveWorkspaceTarget(context, input.workspaceId);
+  if (!workspace.ok) {
+    return { query, limit, results: [], error: workspace.error };
+  }
+
+  const result = await runBvJson(
+    "search",
+    workspace.value.directory,
+    (payload) => normalizeSearchResults(payload, limit),
+    { query, limit },
+  );
+  if (!result.ok) {
+    return { query, limit, results: [], error: result.error };
+  }
+  return { query, limit, results: result.value, error: null };
+}

package/server/tracker.ts

@@ -0,0 +1,122 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import type { TrackerKind, TrackerState } from "../shared/beads";
+import { runBvJson } from "./bv";
+import { ExpiringCache } from "./cache";
+import { normalizeSource } from "./normalize";
+import { detectTracker, readTrackerMetadata, UNKNOWN_TRACKER } from "./workspace";
+
+const TRACKER_TTL_MS = 120_000;
+
+/** Exact live tracker route established from bv's selected source and metadata. */
+export interface TrackerRoute {
+  readonly kind: TrackerKind;
+  readonly beadsDirectory: string;
+  readonly database: string;
+}
+
+export interface TrackerResolution {
+  readonly state: TrackerState;
+  readonly route: TrackerRoute | null;
+}
+
+const UNKNOWN_RESOLUTION: TrackerResolution = { state: UNKNOWN_TRACKER, route: null };
+const trackerCache = new ExpiringCache<TrackerResolution>(TRACKER_TTL_MS);
+const trackerReads = new Map<string, Promise<TrackerResolution>>();
+
+export function clearTrackerCache(): void {
+  trackerCache.clear();
+  trackerReads.clear();
+}
+
+function trackerCacheKey(workspaceId: string, directory: string): string {
+  return `${workspaceId}\0${directory}`;
+}
+
+export function rememberTracker(workspaceId: string, directory: string, resolution: TrackerResolution): void {
+  if (resolution.state.kind !== null) trackerCache.set(trackerCacheKey(workspaceId, directory), resolution);
+}
+
+async function buildTrackerRoute(
+  kind: TrackerKind,
+  payload: unknown,
+  directory: string,
+): Promise<TrackerRoute | null> {
+  const metadata = await readTrackerMetadata(payload, directory);
+  if (metadata === null) return null;
+
+  const source = normalizeSource(payload);
+  if (source?.sourcePath === null || source?.sourcePath === undefined || !isAbsolute(source.sourcePath)) return null;
+  const selectedSource = resolve(source.sourcePath);
+  const resolveMetadataPath = (value: string | null): string | null =>
+    value === null ? null : isAbsolute(value) ? resolve(value) : resolve(metadata.beadsDirectory, value);
+
+  let database: string | null;
+  if (kind === "bd") {
+    if (metadata.backend !== "dolt" || selectedSource !== resolve(metadata.beadsDirectory, "issues.jsonl")) return null;
+    database = metadata.beadsDirectory;
+  } else {
+    if (metadata.backend === "dolt") return null;
+    database = resolveMetadataPath(metadata.database);
+    const jsonlExport = resolveMetadataPath(metadata.jsonlExport);
+    if (database === null || (selectedSource !== database && selectedSource !== jsonlExport)) return null;
+  }
+  if (database.includes("\0") || !isAbsolute(database)) return null;
+
+  try {
+    const info = await stat(database);
+    if (kind === "bd" ? !info.isDirectory() : !info.isFile()) return null;
+  } catch {
+    return null;
+  }
+
+  return { kind, beadsDirectory: metadata.beadsDirectory, database };
+}
+
+/**
+ * Establishes both tracker identity and the exact database route. Detail reads
+ * fail closed when metadata cannot bind the CLI to bv's selected live source.
+ */
+export async function resolveTrackerFromPayload(payload: unknown, directory: string): Promise<TrackerResolution> {
+  const detected = await detectTracker(payload, directory);
+  if (detected.kind === null || !detected.available) return { state: detected, route: null };
+
+  const route = await buildTrackerRoute(detected.kind, payload, directory);
+  if (route === null) {
+    return {
+      state: {
+        kind: detected.kind,
+        available: false,
+        detail: `The ${detected.kind} CLI is installed, but its exact read-only database route could not be established.`,
+      },
+      route: null,
+    };
+  }
+  return { state: detected, route };
+}
+
+/** Resolves and caches the exact read-only tracker route for one workspace. */
+export async function resolveTracker(workspaceId: string, directory: string): Promise<TrackerResolution> {
+  const key = trackerCacheKey(workspaceId, directory);
+  const cached = trackerCache.get(key);
+  if (cached !== null) return cached;
+
+  const active = trackerReads.get(key);
+  if (active !== undefined) return await active;
+
+  const read = (async () => {
+    const triage = await runBvJson("triage", directory, (payload) => payload);
+    if (!triage.ok) {
+      return { ...UNKNOWN_RESOLUTION, state: { ...UNKNOWN_TRACKER, detail: triage.error.message } };
+    }
+    const resolution = await resolveTrackerFromPayload(triage.value, directory);
+    rememberTracker(workspaceId, directory, resolution);
+    return resolution;
+  })();
+  trackerReads.set(key, read);
+  try {
+    return await read;
+  } finally {
+    trackerReads.delete(key);
+  }
+}

package/server/workspace.ts

@@ -0,0 +1,153 @@
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import type { TrackerKind, TrackerState } from "../shared/beads";
+import { failure, resolveExecutable, type CommandResult } from "./command";
+import { asRecord, normalizeSource } from "./normalize";
+
+export interface WorkspaceTarget {
+  readonly id: string;
+  readonly name: string;
+  readonly directory: string;
+}
+
+/**
+ * Every subprocess cwd comes from Paseo's own workspace record, never from
+ * client input. A workspace without a usable absolute directory is rejected.
+ */
+export async function resolveWorkspaceTarget(
+  context: PluginHandlerContext,
+  workspaceId: string,
+): Promise<CommandResult<WorkspaceTarget>> {
+  let directory: string | null = null;
+  let name: string | null = null;
+  try {
+    const workspace = await context.paseo.workspaces.ref(workspaceId).refresh();
+    if (workspace === null) {
+      return failure("workspace_unresolved", `Paseo does not know workspace ${workspaceId}.`);
+    }
+    directory = workspace.workspaceDirectory;
+    name = workspace.title ?? workspace.name;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "workspace lookup failed";
+    return failure("workspace_unresolved", `Could not resolve workspace ${workspaceId}: ${message}`);
+  }
+
+  if (directory === null || directory.length === 0 || !isAbsolute(directory)) {
+    return failure("cwd_invalid", `Workspace ${workspaceId} has no absolute directory to run bv in.`);
+  }
+  try {
+    const info = await stat(directory);
+    if (!info.isDirectory()) {
+      return failure("cwd_invalid", `Workspace path ${directory} is not a directory.`);
+    }
+  } catch {
+    return failure("cwd_invalid", `Workspace path ${directory} is not reachable on the daemon.`);
+  }
+
+  return { ok: true, value: { id: workspaceId, name: name ?? workspaceId, directory } };
+}
+
+export const UNKNOWN_TRACKER: TrackerState = {
+  kind: null,
+  available: false,
+  detail: "No Beads tracker CLI (br or bd) could be established for this workspace.",
+};
+
+/**
+ * `bv --robot-triage` names the tracker that owns the project in each
+ * recommendation's `actions.tracker`. That is the authoritative signal; the
+ * installed-binary check is only a fallback and stays inconclusive when both
+ * `br` and `bd` are present.
+ */
+export function readTrackerFromTriage(payload: unknown): TrackerKind | null {
+  const triage = asRecord(asRecord(payload)?.["triage"]);
+  if (triage === null) return null;
+  const quickRef = asRecord(triage["quick_ref"]);
+  const groups: readonly unknown[] = [
+    triage["recommendations"],
+    quickRef?.["top_picks"],
+    triage["quick_wins"],
+  ];
+  for (const group of groups) {
+    if (!Array.isArray(group)) continue;
+    for (const entry of group) {
+      const actions = asRecord(asRecord(entry)?.["actions"]);
+      const tracker = actions?.["tracker"];
+      if (tracker === "br" || tracker === "bd") return tracker;
+    }
+  }
+  return null;
+}
+
+export interface TrackerMetadata {
+  readonly beadsDirectory: string;
+  readonly backend: string;
+  readonly database: string | null;
+  readonly jsonlExport: string | null;
+}
+
+/** Reads only tracker routing metadata, preferring bv's selected source over cwd discovery. */
+export async function readTrackerMetadata(payload: unknown, directory: string): Promise<TrackerMetadata | null> {
+  const sourcePath = normalizeSource(payload)?.sourcePath ?? null;
+  const candidates = [
+    sourcePath !== null && isAbsolute(sourcePath) ? dirname(sourcePath) : null,
+    join(directory, ".beads"),
+  ].filter((candidate): candidate is string => candidate !== null);
+
+  for (const beadsDirectory of [...new Set(candidates)]) {
+    try {
+      const raw = await readFile(join(beadsDirectory, "metadata.json"), "utf8");
+      const record = asRecord(JSON.parse(raw) as unknown);
+      if (record === null) continue;
+      const backend = typeof record["backend"] === "string" ? record["backend"].trim().toLowerCase() : "";
+      const database = typeof record["database"] === "string" ? record["database"].trim() : null;
+      const jsonlExport = typeof record["jsonl_export"] === "string" ? record["jsonl_export"].trim() : null;
+      return {
+        beadsDirectory,
+        backend,
+        database: database === "" ? null : database,
+        jsonlExport: jsonlExport === "" ? null : jsonlExport,
+      };
+    } catch {
+      // Try the cwd fallback. Redirected/worktree sources normally succeed above.
+    }
+  }
+  return null;
+}
+
+function trackerFromMetadata(metadata: TrackerMetadata | null): TrackerKind | null {
+  if (metadata === null) return null;
+  if (metadata.backend === "dolt") return "bd";
+  const database = metadata.database?.toLowerCase() ?? "";
+  if (metadata.backend === "sqlite" || /\.(db|sqlite|sqlite3)$/.test(database)) return "br";
+  return null;
+}
+
+export async function detectTracker(payload: unknown, directory?: string): Promise<TrackerState> {
+  const metadata = directory === undefined ? null : await readTrackerMetadata(payload, directory);
+  const declared = readTrackerFromTriage(payload) ?? trackerFromMetadata(metadata);
+  if (declared !== null) {
+    const executable = await resolveExecutable(declared);
+    if (executable === null) {
+      return {
+        kind: declared,
+        available: false,
+        detail: `This project uses ${declared}, but ${declared} is not on the daemon PATH.`,
+      };
+    }
+    return { kind: declared, available: true, detail: null };
+  }
+
+  const [br, bd] = await Promise.all([resolveExecutable("br"), resolveExecutable("bd")]);
+  if (br !== null && bd === null) return { kind: "br", available: true, detail: "Inferred from the installed CLI." };
+  if (bd !== null && br === null) return { kind: "bd", available: true, detail: "Inferred from the installed CLI." };
+  if (br !== null && bd !== null) {
+    return {
+      kind: null,
+      available: false,
+      detail: "Both br and bd are installed and bv did not name the project tracker, so detail reads are disabled.",
+    };
+  }
+  return UNKNOWN_TRACKER;
+}

package/shared/beads.ts

@@ -0,0 +1,325 @@
+import { z } from "zod";
+
+/** Fixed set of command failure codes surfaced to the client. */
+export const CommandErrorCodeSchema = z.enum([
+  "unavailable",
+  "timeout",
+  "exit",
+  "output_limit",
+  "invalid_json",
+  "cwd_invalid",
+  "workspace_unresolved",
+  "tracker_unknown",
+  "internal",
+]);
+export type CommandErrorCode = z.output<typeof CommandErrorCodeSchema>;
+
+export const CommandErrorSchema = z.object({
+  code: CommandErrorCodeSchema,
+  message: z.string(),
+  exitCode: z.number().nullable(),
+});
+export type CommandError = z.output<typeof CommandErrorSchema>;
+
+/** Per-section degradation so one missing analysis never fails the dashboard. */
+export const SectionStateSchema = z.object({
+  status: z.enum(["ok", "unavailable"]),
+  error: CommandErrorSchema.nullable(),
+});
+export type SectionState = z.output<typeof SectionStateSchema>;
+
+/**
+ * Beads statuses, readiness, and authority states are treated as opaque strings.
+ * Unknown values from a newer `bv` must render, not fail validation.
+ */
+export const SourceAuthoritySchema = z.object({
+  state: z.string(),
+  readiness: z.string(),
+  claimSafe: z.boolean(),
+  stale: z.boolean(),
+  loaded: z.number(),
+  failed: z.number(),
+  valid: z.number(),
+  visible: z.number(),
+  tombstones: z.number(),
+  warnings: z.array(z.string()),
+});
+export type SourceAuthority = z.output<typeof SourceAuthoritySchema>;
+
+export const SourceSnapshotSchema = z.object({
+  generatedAt: z.string().nullable(),
+  dataHash: z.string().nullable(),
+  sourcePath: z.string().nullable(),
+  sourceKind: z.string().nullable(),
+  toolVersion: z.string().nullable(),
+  authority: SourceAuthoritySchema.nullable(),
+});
+export type SourceSnapshot = z.output<typeof SourceSnapshotSchema>;
+
+/**
+ * `bv`'s own counts, kept verbatim. Two of them do not mean what a reader
+ * assumes: `blocked` counts only issues whose *status* is `blocked`, and
+ * `actionable` includes epics with no open blocker. Dependency-blocked work is
+ * `waiting`, read from `project_health`; the panel's own headline counts come
+ * from the graph instead (see `client/project.ts`).
+ */
+export const ProjectCountsSchema = z.object({
+  open: z.number(),
+  actionable: z.number(),
+  blocked: z.number(),
+  inProgress: z.number(),
+  notClosed: z.number(),
+  notActionable: z.number(),
+  total: z.number(),
+  /** `project_health.counts.dependency_blocked`; null when `bv` omitted it. */
+  waiting: z.number().nullable(),
+  /** `project_health.counts.closed`; null when `bv` omitted it. */
+  closed: z.number().nullable(),
+});
+export type ProjectCounts = z.output<typeof ProjectCountsSchema>;
+
+/** Pace and structural health from `project_health`, which triage already carries. */
+export const ProjectHealthSchema = z.object({
+  closedLast7Days: z.number().nullable(),
+  closedLast30Days: z.number().nullable(),
+  /** True when `bv` marked the velocity as an estimate. */
+  velocityEstimated: z.boolean(),
+  /** Null when `bv` did not report cycle detection. */
+  hasCycles: z.boolean().nullable(),
+});
+export type ProjectHealth = z.output<typeof ProjectHealthSchema>;
+
+export const RecommendationSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  type: z.string().nullable(),
+  priority: z.number().nullable(),
+  assignee: z.string().nullable(),
+  labels: z.array(z.string()),
+  score: z.number().nullable(),
+  action: z.string().nullable(),
+  reasons: z.array(z.string()),
+  blockedBy: z.array(z.string()),
+  unblocks: z.array(z.string()),
+  claimable: z.boolean(),
+});
+export type Recommendation = z.output<typeof RecommendationSchema>;
+
+export const BlockerSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  unblocksCount: z.number(),
+  unblocks: z.array(z.string()),
+  actionable: z.boolean(),
+});
+export type Blocker = z.output<typeof BlockerSchema>;
+
+export const TrackItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  priority: z.number().nullable(),
+  unblocks: z.array(z.string()),
+});
+
+export const TrackSchema = z.object({
+  id: z.string(),
+  reason: z.string().nullable(),
+  items: z.array(TrackItemSchema),
+  /** Items `bv` listed in this track, which exceeds `items.length` when capped. */
+  totalItems: z.number(),
+});
+export type Track = z.output<typeof TrackSchema>;
+
+export const PlanSummarySchema = z.object({
+  totalActionable: z.number().nullable(),
+  totalBlocked: z.number().nullable(),
+  /** Tracks `bv` reported, before the payload cap. */
+  totalTracks: z.number(),
+  highestImpact: z.string().nullable(),
+  impactReason: z.string().nullable(),
+});
+export type PlanSummary = z.output<typeof PlanSummarySchema>;
+
+/**
+ * One issue from `bv --robot-graph`, which is the only `bv` read that returns
+ * the *whole* project rather than an analysis-selected subset. Status stays an
+ * opaque string; the dependencies are derived from the graph's `blocks` edges,
+ * where `from` is blocked by `to`. A `blocks` edge outlives the blocker being
+ * closed, so only blockers that are still open count.
+ */
+export const BoardIssueSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  priority: z.number().nullable(),
+  labels: z.array(z.string()),
+  /** Ids of the blockers that are not closed yet, in edge order. */
+  blockedBy: z.array(z.string()),
+  /** How many issues that are not closed yet wait on this one. */
+  unblocksCount: z.number(),
+  /** Parent issue id. The graph emits `parent-child` as child → parent. */
+  parentId: z.string().nullable(),
+  /**
+   * Issues naming this one as parent, counted before any truncation, so an
+   * epic whose closed children were dropped is still known to be a container.
+   */
+  childCount: z.number(),
+  /** `epic`, `task`, `bug`, … from the tracker; null when the overlay is absent. */
+  type: z.string().nullable(),
+  /** From the tracker overlay; null when unassigned or the overlay is absent. */
+  assignee: z.string().nullable(),
+});
+export type BoardIssue = z.output<typeof BoardIssueSchema>;
+
+export const BoardSnapshotSchema = z.object({
+  issues: z.array(BoardIssueSchema),
+  /** True when the tracker supplied the type/assignee overlay for these issues. */
+  typed: z.boolean(),
+  /** Issue count `bv` reported before any cap was applied. */
+  total: z.number(),
+  /** True when {@link BOARD_ISSUE_LIMIT} dropped closed issues from `issues`. */
+  truncated: z.boolean(),
+});
+export type BoardSnapshot = z.output<typeof BoardSnapshotSchema>;
+
+/**
+ * Upper bound on issues carried to the client in one dashboard payload.
+ * Measured against a real 776-issue project carrying the tracker's type and
+ * assignee overlay: 215 KB normalized, 283 B per issue. This cap therefore
+ * costs ~553 KB in the worst case, which a phone fetches over the relay, so it
+ * is deliberately below what the 4 MB subprocess output cap would allow.
+ * Re-measure this when a field is added to {@link BoardIssueSchema}.
+ */
+export const BOARD_ISSUE_LIMIT = 2000;
+
+/**
+ * The statuses Beads itself defines, verified against `br 0.5.12`:
+ * "Built-in statuses: open, in_progress, blocked, deferred, draft, closed,
+ * tombstone, pinned", plus `hooked` from `bd`. A project may declare more in
+ * `.beads/policy.yaml`; those are custom, so the panel shows them verbatim and
+ * never guesses what they mean.
+ */
+export const BEADS_STATUSES = {
+  open: "open",
+  inProgress: "in_progress",
+  hooked: "hooked",
+  blocked: "blocked",
+  deferred: "deferred",
+  draft: "draft",
+  pinned: "pinned",
+  closed: "closed",
+  tombstone: "tombstone",
+} as const;
+
+/** Finished work: closed, or deleted and kept only as a tombstone. */
+const CLOSED_STATUSES: readonly string[] = [BEADS_STATUSES.closed, BEADS_STATUSES.tombstone];
+
+export function isClosedStatus(status: string): boolean {
+  return CLOSED_STATUSES.includes(status.trim().toLowerCase());
+}
+
+export const AlertSchema = z.object({
+  type: z.string(),
+  severity: z.string(),
+  message: z.string(),
+  issueId: z.string().nullable(),
+  detectedAt: z.string().nullable(),
+  suggestedAction: z.string().nullable(),
+  labels: z.array(z.string()),
+});
+export type Alert = z.output<typeof AlertSchema>;
+
+export const AlertSummarySchema = z.object({
+  total: z.number(),
+  critical: z.number(),
+  warning: z.number(),
+  info: z.number(),
+});
+export type AlertSummary = z.output<typeof AlertSummarySchema>;
+
+/** `bv` is required; the per-project tracker is either `br` or `bd`. */
+export const TrackerKindSchema = z.enum(["br", "bd"]);
+export type TrackerKind = z.output<typeof TrackerKindSchema>;
+
+export const ToolStateSchema = z.object({
+  available: z.boolean(),
+  version: z.string().nullable(),
+  error: CommandErrorSchema.nullable(),
+});
+
+export const TrackerStateSchema = z.object({
+  kind: TrackerKindSchema.nullable(),
+  available: z.boolean(),
+  detail: z.string().nullable(),
+});
+export type TrackerState = z.output<typeof TrackerStateSchema>;
+
+export const IssueRefSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  status: z.string().nullable(),
+  relation: z.string().nullable(),
+});
+
+export const IssueCommentSchema = z.object({
+  id: z.string(),
+  author: z.string().nullable(),
+  text: z.string(),
+  createdAt: z.string().nullable(),
+});
+
+export const IssueDetailSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  type: z.string().nullable(),
+  priority: z.number().nullable(),
+  assignee: z.string().nullable(),
+  description: z.string().nullable(),
+  design: z.string().nullable(),
+  acceptanceCriteria: z.string().nullable(),
+  notes: z.string().nullable(),
+  labels: z.array(z.string()),
+  parent: z.string().nullable(),
+  dependencies: z.array(IssueRefSchema),
+  dependents: z.array(IssueRefSchema),
+  comments: z.array(IssueCommentSchema),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  closedAt: z.string().nullable(),
+  closeReason: z.string().nullable(),
+});
+export type IssueDetail = z.output<typeof IssueDetailSchema>;
+
+export const SearchResultSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  score: z.number().nullable(),
+});
+export type SearchResult = z.output<typeof SearchResultSchema>;
+
+/** Bounds shared by the client and the server so both agree on limits. */
+export const SEARCH_QUERY_MAX_LENGTH = 120;
+export const SEARCH_LIMIT_MIN = 1;
+export const SEARCH_LIMIT_MAX = 25;
+export const SEARCH_LIMIT_DEFAULT = 10;
+export const ISSUE_ID_MAX_LENGTH = 128;
+export const ATTACHMENT_RESULT_LIMIT = 8;
+
+export const SearchQuerySchema = z.string().min(1).max(SEARCH_QUERY_MAX_LENGTH);
+export const SearchLimitSchema = z.number().int().min(SEARCH_LIMIT_MIN).max(SEARCH_LIMIT_MAX);
+export const IssueIdSchema = z
+  .string()
+  .min(1)
+  .max(ISSUE_ID_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "Beads issue ids are alphanumeric with . _ -");
+
+export const ATTACHMENT_URL_SCHEME = "paseo-beads:";
+export const ATTACHMENT_RESOURCE_TYPE = "beads_issue";
+
+/** Stable, parseable identity for an issue inside one Paseo workspace. */
+export function buildIssueUrl(workspaceId: string, issueId: string): string {
+  return `${ATTACHMENT_URL_SCHEME}//workspace/${encodeURIComponent(workspaceId)}/issue/${encodeURIComponent(issueId)}`;
+}