@dsdenes/devboard 0.1.560 → 0.1.562

package/server/feedback.ts

@@ -0,0 +1,369 @@
+import { giteaCreateIssue, type FetchLike } from "../lib/gitea";
+
+/**
+ * Operator issue reporting for the local interface.
+ *
+ * The client sends one action plus the DOM context of the element it is about.
+ * A report also carries the operator's free text and, when the panel answered
+ * questions, the Ask conversation; the removal and redesign shortcuts carry
+ * only the context and use a fixed instruction. This module
+ * validates that payload, renders it as a Gitea issue for an implementation
+ * agent, and files the issue through the configured Gitea API.
+ *
+ * Reports describe the harness interface itself, so the issue always lands in
+ * the harness repository, never in the host project that embeds the harness.
+ * Without `DEVBOARD_GITEA_URL` reporting is disabled rather than redirected to
+ * another forge.
+ */
+
+/** The repository that receives every reported UI issue. */
+export const FEEDBACK_REPOSITORY = "dsdenes/devboard";
+
+const MAX_REPORT = 8000;
+const MAX_CONTEXT_FIELD = 2000;
+const MAX_DOM_EXCERPT = 8000;
+const MAX_VISIBLE_TEXT = 8000;
+const MAX_VIEWPORT = 500;
+const MAX_TITLE = 200;
+const TITLE_PREFIX = "[ui] ";
+const BODY_VISIBLE_TEXT = 1500;
+/** Bounds shared with the client's Ask transcript capture. */
+const MAX_CONVERSATION_TURNS = 40;
+const MAX_CONVERSATION_TURN = 4000;
+const MAX_CONVERSATION_TEXT = 12_000;
+
+/** What the operator asked for when they picked an element. */
+export type FeedbackAction = "report" | "remove" | "redesign";
+
+/**
+ * The instruction a removal issue carries. It is fixed, so the implementation
+ * agent never has to interpret operator text for the one-click shortcuts.
+ */
+export const REMOVAL_INSTRUCTION = "Remove the selected UI element from the interface.";
+
+/**
+ * The instruction a redesign issue carries. It names the normative design
+ * sources so the agent checks the element against the project's own system.
+ */
+export const REDESIGN_INSTRUCTION =
+  "Check the selected UI element and redesign it because it does not look good. " +
+  "Use the global OMP UI/UX standard (the ui-ux skill) and this repository's " +
+  "DESIGN.md and design/tokens.json as the normative design system.";
+
+const ACTION_ERROR = "action must be one of report, remove, redesign.";
+
+/** One visible turn of the element-scoped Ask conversation. */
+export interface FeedbackTurn {
+  role: "developer" | "agent";
+  text: string;
+}
+
+export interface FeedbackSubmission {
+  action: FeedbackAction;
+  report: string;
+  /** The Ask conversation the operator had about this element, if any. */
+  conversation: FeedbackTurn[];
+  route: string;
+  url: string;
+  selector: string;
+  domExcerpt: string;
+  visibleText: string;
+  viewport: string;
+  capturedAt: string;
+}
+
+export interface FeedbackIssue {
+  url: string;
+  title: string;
+}
+
+/** A payload the endpoint refuses with a client error. */
+export class FeedbackRequestError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "FeedbackRequestError";
+    this.status = status;
+  }
+}
+
+/** A delivery failure: the Gitea API refused the request or timed out. */
+export class FeedbackDeliveryError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "FeedbackDeliveryError";
+    this.status = status;
+  }
+}
+
+export interface FeedbackIssueOptions {
+  /** Gitea HTTP origin; reporting is disabled when this is absent. */
+  baseUrl: string;
+  /** `owner/name` repository that receives the issue. */
+  repo: string;
+  token?: string;
+  /** Wall-clock bound for the API request. */
+  timeoutMs: number;
+  /** Test seam; production uses the global fetch. */
+  fetchImpl?: FetchLike;
+}
+
+function field(
+  value: unknown,
+  name: string,
+  limit: number,
+  required: false,
+): string;
+function field(
+  value: unknown,
+  name: string,
+  limit: number,
+  required: true,
+): string;
+function field(
+  value: unknown,
+  name: string,
+  limit: number,
+  required: boolean,
+): string {
+  if (value === undefined || value === null) {
+    if (required) throw new FeedbackRequestError(400, `${name} is required.`);
+    return "";
+  }
+  if (typeof value !== "string") {
+    throw new FeedbackRequestError(400, `${name} must be a string.`);
+  }
+  if (value.length > limit) {
+    throw new FeedbackRequestError(400, `${name} is longer than ${limit} characters.`);
+  }
+  if (required && value.trim().length === 0) {
+    throw new FeedbackRequestError(400, `${name} must not be empty.`);
+  }
+  return value;
+}
+
+function feedbackAction(value: unknown): FeedbackAction {
+  // An absent action keeps the original free-text report contract.
+  if (value === undefined || value === null) return "report";
+  if (value === "report" || value === "remove" || value === "redesign") return value;
+  throw new FeedbackRequestError(400, ACTION_ERROR);
+}
+
+/** The element context every browser request carries. */
+export interface CapturedFields {
+  route: string;
+  url: string;
+  selector: string;
+  domExcerpt: string;
+  visibleText: string;
+  viewport: string;
+  capturedAt: string;
+}
+
+/** Validates the captured element context under the shared per-field limits. */
+export function parseCapturedFields(source: Record<string, unknown>): CapturedFields {
+  return {
+    route: field(source.route, "route", MAX_CONTEXT_FIELD, false),
+    url: field(source.url, "url", MAX_CONTEXT_FIELD, false),
+    selector: field(source.selector, "selector", MAX_CONTEXT_FIELD, false),
+    domExcerpt: field(source.dom_excerpt, "dom_excerpt", MAX_DOM_EXCERPT, false),
+    visibleText: field(source.visible_text, "visible_text", MAX_VISIBLE_TEXT, false),
+    viewport: field(source.viewport, "viewport", MAX_VIEWPORT, false),
+    capturedAt: field(source.captured_at, "captured_at", MAX_CONTEXT_FIELD, false),
+  };
+}
+
+/** Validates the required free text under the shared report limit. */
+export function parseReportText(value: unknown): string {
+  return field(value, "report", MAX_REPORT, true);
+}
+
+/**
+ * Validates the Ask conversation. A submission without one carries no turns,
+ * so an older client keeps filing reports unchanged.
+ */
+export function parseConversation(value: unknown): FeedbackTurn[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new FeedbackRequestError(400, "conversation must be an array.");
+  }
+  if (value.length > MAX_CONVERSATION_TURNS) {
+    throw new FeedbackRequestError(
+      400,
+      `conversation has more than ${MAX_CONVERSATION_TURNS} turns.`,
+    );
+  }
+  const turns: FeedbackTurn[] = [];
+  let total = 0;
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new FeedbackRequestError(400, `conversation[${index}] must be an object.`);
+    }
+    const source = entry as Record<string, unknown>;
+    const role = source.role;
+    if (role !== "developer" && role !== "agent") {
+      throw new FeedbackRequestError(
+        400,
+        `conversation[${index}].role must be developer or agent.`,
+      );
+    }
+    const text = field(source.text, `conversation[${index}].text`, MAX_CONVERSATION_TURN, true);
+    total += text.length;
+    turns.push({ role, text });
+  }
+  if (total > MAX_CONVERSATION_TEXT) {
+    throw new FeedbackRequestError(
+      400,
+      `conversation is longer than ${MAX_CONVERSATION_TEXT} characters.`,
+    );
+  }
+  return turns;
+}
+
+/** Validates one JSON body. Unknown fields are ignored for forwards compatibility. */
+export function parseFeedbackSubmission(value: unknown): FeedbackSubmission {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new FeedbackRequestError(400, "The report must be a JSON object.");
+  }
+  const source = value as Record<string, unknown>;
+  const action = feedbackAction(source.action);
+  return {
+    action,
+    // The one-click shortcuts use a fixed instruction, so any text the client
+    // still sends is ignored rather than validated or filed.
+    report: action === "report" ? parseReportText(source.report) : "",
+    conversation: parseConversation(source.conversation),
+    ...parseCapturedFields(source),
+  };
+}
+
+function collapse(value: string, limit: number): string {
+  const single = value.replace(/\s+/g, " ").trim();
+  if (single.length <= limit) return single;
+  return `${single.slice(0, limit - 1).trimEnd()}…`;
+}
+
+function truncate(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit - 1).trimEnd()}…`;
+}
+
+function firstLine(value: string): string {
+  const line =
+    value
+      .split("\n")
+      .map((entry) => entry.trim())
+      .find((entry) => entry.length > 0) ?? "no diagnostic";
+  return truncate(line, 300);
+}
+
+/** One-line issue title for the submission's action. */
+export function feedbackTitle(submission: FeedbackSubmission): string {
+  if (submission.action !== "report") {
+    const label = submission.action === "remove" ? "Remove element" : "Redesign element";
+    const selector = submission.selector.replace(/\s+/g, " ").trim();
+    if (selector.length === 0) return `${TITLE_PREFIX}${label}`;
+    return truncate(`${TITLE_PREFIX}${label}: ${selector}`, MAX_TITLE);
+  }
+  const line =
+    submission.report
+      .split("\n")
+      .map((value) => value.trim())
+      .find((value) => value.length > 0) ?? "operator report";
+  return truncate(`${TITLE_PREFIX}${line.replace(/\s+/g, " ")}`, MAX_TITLE);
+}
+
+/**
+ * The Ask conversation as Markdown: one labelled block per visible turn. It is
+ * empty when the operator filed without asking the agent anything.
+ */
+export function conversationSection(conversation: FeedbackTurn[]): string[] {
+  const lines: string[] = [];
+  for (const turn of conversation) {
+    lines.push("", `**${turn.role === "developer" ? "You" : "Agent"}:**`, "", turn.text.trim());
+  }
+  if (lines.length === 0) return [];
+  return ["## Ask conversation", ...lines];
+}
+
+/** The ticket body: the request first, then the conversation and captured context. */
+export function feedbackBody(submission: FeedbackSubmission): string {
+  const request =
+    submission.action === "remove"
+      ? ["## Removal request", "", REMOVAL_INSTRUCTION]
+      : submission.action === "redesign"
+        ? ["## Redesign request", "", REDESIGN_INSTRUCTION]
+        : ["## Operator report", "", submission.report.trim()];
+  const lines = [...request, ""];
+
+  const context: string[] = [];
+  for (const [label, value] of [
+    ["Route", submission.route],
+    ["URL", submission.url],
+    ["Selected element", submission.selector],
+    ["Viewport", submission.viewport],
+    ["Captured at", submission.capturedAt],
+  ] as const) {
+    // A backtick inside an inline code span would close it early.
+    if (value.trim().length > 0) {
+      context.push(`- ${label}: \`${value.trim().replace(/`/g, "'")}\``);
+    }
+  }
+
+  const visible = collapse(submission.visibleText, BODY_VISIBLE_TEXT);
+  if (visible.length > 0) {
+    context.push("", "### Visible text", "", visible);
+  }
+
+  const dom = submission.domExcerpt.trim();
+  if (dom.length > 0) {
+    const fence = dom.includes("```") ? "````" : "```";
+    context.push("", "### DOM excerpt", "", `${fence}html`, dom, fence);
+  }
+
+  const conversation = conversationSection(submission.conversation);
+  if (conversation.length > 0) lines.push(...conversation, "");
+
+  lines.push("## Captured UI context", "");
+  lines.push(...(context.length === 0 ? ["No page context was captured."] : context));
+  return lines.join("\n");
+}
+
+/** Files one report and returns the created issue. */
+export async function fileFeedbackIssue(
+  submission: FeedbackSubmission,
+  options: FeedbackIssueOptions,
+): Promise<FeedbackIssue> {
+  const title = feedbackTitle(submission);
+  const body = feedbackBody(submission);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const withTimeout: FetchLike = (input, init) =>
+    fetchImpl(input, {
+      ...init,
+      signal: AbortSignal.timeout(options.timeoutMs),
+    });
+  try {
+    const issue = await giteaCreateIssue(
+      {
+        baseUrl: options.baseUrl,
+        project: options.repo,
+        ...(options.token === undefined ? {} : { token: options.token }),
+      },
+      { title, body },
+      withTimeout,
+    );
+    return { url: issue.url, title };
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      throw new FeedbackDeliveryError(
+        504,
+        `Issue creation timed out after ${options.timeoutMs} ms.`,
+      );
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new FeedbackDeliveryError(502, `Issue creation failed: ${firstLine(detail)}`);
+  }
+}

package/server/fixtures/adr-source.ts

@@ -0,0 +1,71 @@
+import { basename } from "node:path";
+
+/** The status vocabulary a fixture record may carry. */
+export type AdrStatus = "draft" | "proposed" | "accepted" | "rejected" | "superseded" | "deprecated";
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+/**
+ * Builds a fixture decision record with the YAML frontmatter the corpus format requires.
+ * The four-digit id is taken from the file name, so the record passes corpus validation
+ * exactly where the fixture writes it.
+ */
+export function fixtureRecord(
+  file: string,
+  title: string,
+  status: AdrStatus = "accepted",
+  body = "",
+  extra: Record<string, string> = {},
+): string {
+  const id = /^(\d{4,})-/.exec(basename(file))?.[1];
+  if (id === undefined) throw new Error(`Fixture record name needs a numeric id: ${file}`);
+  return [
+    "---",
+    "schemaVersion: 0.2.0",
+    `id: "${id}"`,
+    `title: ${title}`,
+    `status: ${status}`,
+    ...Object.entries(extra).map(([key, value]) => `${key}: ${value}`),
+    "date: 2026-10-19",
+    'deciders: ["@dsdenes"]',
+    "affects: []",
+    "---",
+    `# ${title}`,
+    "",
+    body,
+  ].join("\n");
+}
+
+/** A record that is still waiting for a decision. */
+export function pendingRecord(file: string, title: string, context = "", decision = ""): string {
+  return fixtureRecord(
+    file,
+    title,
+    "proposed",
+    `## Context\n\n${context}\n\n## Decision\n\n${decision}\n`,
+  );
+}
+
+/** The status field of a record's leading YAML frontmatter block, if it has one. */
+export function frontmatterStatus(source: string): AdrStatus | undefined {
+  const block = FRONTMATTER.exec(source)?.[1];
+  if (block === undefined) return undefined;
+  return /^status:\s*([a-z]+)\s*$/m.exec(block)?.[1] as AdrStatus | undefined;
+}
+
+/** Whether a status is waiting for a decision. */
+export function isPendingStatus(status: AdrStatus | undefined): boolean {
+  return status === "draft" || status === "proposed";
+}
+
+/** Rewrites the status field inside the frontmatter, leaving the rest of the file untouched. */
+export function setFrontmatterStatus(source: string, status: AdrStatus): string {
+  const match = FRONTMATTER.exec(source);
+  if (match === null) throw new Error("Record has no YAML frontmatter to update.");
+  const block = match[1] ?? "";
+  if (!/^status:\s*[a-z]+\s*$/m.test(block)) throw new Error("Record frontmatter has no status field.");
+  const updated = block.replace(/^status:\s*[a-z]+\s*$/m, `status: ${status}`);
+  const start = match[0].indexOf(block);
+  const head = match[0].slice(0, start) + updated + match[0].slice(start + block.length);
+  return head + source.slice(match[0].length);
+}

package/server/fixtures/hang-download.ts

@@ -0,0 +1,14 @@
+/**
+ * `gh` substitute whose asset download never settles. It records its pid in
+ * `STUB_GH_PID_FILE` so a test can prove the downloader's deadline killed the
+ * child instead of leaving it running.
+ */
+
+import { writeFileSync } from "node:fs";
+
+const pidFile = process.env.STUB_GH_PID_FILE;
+if (pidFile !== undefined) writeFileSync(pidFile, `${process.pid}\n`);
+
+await Bun.sleep(120_000);
+
+export {};