@dsdenes/devboard 0.1.560 → 0.1.563

package/client/lib/skill-document.ts

@@ -0,0 +1,57 @@
+import { Marked, type Tokens } from "marked";
+
+/**
+ * The prepared SKILL.md body without its YAML frontmatter. The frontmatter is
+ * bookkeeping: the panel header already states the name and the skills list
+ * owns the description, so the document starts at the first instruction.
+ */
+export function skillBody(source: string): string {
+  const normalized = source.replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines[0]?.trim() !== "---") return normalized.trim();
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (close < 0) return normalized.trim();
+  return lines.slice(close + 1).join("\n").trim();
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/** Links may leave the console, but never into a script or data URL. */
+function safeHref(href: string): boolean {
+  if (/^\s*(?:javascript|data|vbscript):/i.test(href)) return false;
+  return true;
+}
+
+const marked = new Marked({ gfm: true });
+
+marked.use({
+  renderer: {
+    // A skill file is host content, not app markup: raw HTML renders as text.
+    html({ text }: Tokens.HTML | Tokens.Tag) {
+      return escapeHtml(text);
+    },
+    link({ href, title, tokens }: Tokens.Link) {
+      const label = this.parser.parseInline(tokens);
+      if (!safeHref(href)) return label;
+      const titleAttribute = title == null ? "" : ` title="${escapeHtml(title)}"`;
+      return `<a href="${escapeHtml(href)}"${titleAttribute} target="_blank" rel="noreferrer noopener">${label}</a>`;
+    },
+    image({ text }: Tokens.Image) {
+      return escapeHtml(text);
+    },
+  },
+});
+
+/** Renders the skill body as sanitized HTML for the document panel. */
+export function renderSkillDocument(source: string): string {
+  const body = skillBody(source);
+  if (body.length === 0) return "";
+  return marked.parse(body, { async: false });
+}

package/client/lib/status-tone.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { statusTone } from "./status-tone";
+
+describe("status tone", () => {
+  test("marks active work as accent", () => {
+    expect(statusTone("running")).toBe("accent");
+    expect(statusTone("scanning")).toBe("accent");
+    expect(statusTone("pausing")).toBe("accent");
+    expect(statusTone("retrying")).toBe("accent");
+  });
+
+  test("marks successful completion as success", () => {
+    expect(statusTone("succeeded")).toBe("success");
+    expect(statusTone("merged")).toBe("success");
+    expect(statusTone("handled")).toBe("success");
+    expect(statusTone("accepted")).toBe("success");
+  });
+
+  test("marks failures as error", () => {
+    expect(statusTone("failed")).toBe("error");
+  });
+
+  test("keeps stopped and paused work neutral instead of the running color", () => {
+    for (const status of ["stopped", "paused", "parked", "idle", "closed", "unknown", "none"]) {
+      expect(statusTone(status)).toBeUndefined();
+    }
+    expect(statusTone("stopped")).not.toBe(statusTone("running"));
+  });
+
+  test("normalizes the status word", () => {
+    expect(statusTone(" Running ")).toBe("accent");
+    expect(statusTone("FAILED")).toBe("error");
+  });
+
+  test("keeps pending and stale distinct", () => {
+    expect(statusTone("pending")).toBe("pending");
+    expect(statusTone("stale")).toBe("stale");
+    expect(statusTone("deferred")).toBeUndefined();
+  });
+});

package/client/lib/status-tone.ts

@@ -0,0 +1,33 @@
+import type { BadgeTone } from "./record-status";
+
+/**
+ * The tone one process status earns, wherever the dashboard renders it.
+ *
+ * A status word has one color in every surface: active work is `accent`,
+ * successful completion is `success`, a failure is `error`, and anything that
+ * is neither working nor finished — stopped, paused, parked, idle, closed,
+ * unknown — stays neutral. Stopped work therefore never borrows the running
+ * color, and a status that changes surface does not change meaning.
+ */
+export function statusTone(status: string): BadgeTone | undefined {
+  switch (status.trim().toLowerCase()) {
+    case "running":
+    case "scanning":
+    case "pausing":
+    case "retrying":
+      return "accent";
+    case "succeeded":
+    case "merged":
+    case "handled":
+    case "accepted":
+      return "success";
+    case "failed":
+      return "error";
+    case "pending":
+      return "pending";
+    case "stale":
+      return "stale";
+    default:
+      return undefined;
+  }
+}

package/client/lib/types.ts

@@ -0,0 +1,578 @@
+export type Mode = "goal" | "issues" | "flow" | "discover";
+export type Theme = "dark" | "light";
+
+export interface AdrRecord {
+  file: string;
+  title: string;
+  status: string;
+  pending: boolean;
+  summary: string;
+}
+
+export interface VersionState {
+  running: string | null;
+  installed: string | null;
+  latest: string | null;
+  stale: boolean;
+}
+
+export type IssuesLifecycle = "stopped" | "idle" | "running" | "pausing" | "paused" | "failed";
+export type IssuesRunStatus = "running" | "succeeded" | "failed" | "stopped";
+
+export interface IssuesIssue {
+  number: number;
+  title: string;
+  url: string;
+  createdAt: string;
+  labels: string[];
+}
+
+export interface QueuedIssue extends IssuesIssue {
+  handled: boolean;
+  /** The run that last handled this issue, or null. */
+  runId: string | null;
+  /** The run of the agent currently working this issue, or null. */
+  agentRunId: string | null;
+}
+
+export interface IssuesPollState {
+  intervalMs: number;
+  lastPollAt: string | null;
+  nextPollAt: string | null;
+  etag: string | null;
+  notModified: boolean;
+  rateLimitedUntil: string | null;
+  error: string | null;
+}
+
+export interface IssuesWorkerRecord {
+  pid: number;
+  startedAt: string;
+  stateDir: string;
+  harnessVersion: string | null;
+  argv: string[];
+}
+
+export interface IssuesRunSummary {
+  runId: string;
+  status: IssuesRunStatus;
+  startedAt: string;
+  finishedAt: string | null;
+  exitCode: number | null;
+  issueNumbers: number[];
+  activity: number;
+  firstStderrLine: string | null;
+}
+
+export interface IssuesRunDetail extends IssuesRunSummary {
+  repo: string;
+  argv: string[];
+  cwd: string;
+  issues: IssuesIssue[];
+  workerPid: number;
+  harnessVersion: string | null;
+  activityLines: string[];
+}
+
+/** The worker's published snapshot, as the dashboard is allowed to see it. */
+export interface IssuesSnapshot {
+  present: boolean;
+  repo: string | null;
+  root: string;
+  lifecycle: IssuesLifecycle;
+  enabled: boolean;
+  paused: boolean;
+  attached: boolean;
+  worker: IssuesWorkerRecord | null;
+  poll: IssuesPollState | null;
+  queue: QueuedIssue[];
+  runs: IssuesRunSummary[];
+  agents: IssuesAgent[];
+  cooldowns: Record<string, string>;
+  lastError: string | null;
+  lastExitCode: number | null;
+  finishedAt: string | null;
+  notice: string | null;
+  updatedAt: string | null;
+}
+
+export interface IssuesActivityEntry {
+  text: string;
+  append: boolean;
+}
+
+export interface RunQuestionOption {
+  label: string;
+  description?: string;
+  recommended: boolean;
+}
+
+export interface RunQuestion {
+  id: number | string;
+  message: string;
+  options: RunQuestionOption[];
+}
+
+/** One running issue's own concurrent peer. */
+export interface IssuesAgent {
+  runId: string;
+  issueNumber: number;
+  startedAt: string;
+  question: RunQuestion | null;
+  acp: { pid: number; argv: string[]; cwd: string } | null;
+}
+
+export interface GoalDraftSummary {
+  path: string;
+  name: string;
+  heading: string;
+}
+
+export interface GoalDraftDetail extends GoalDraftSummary {
+  text: string;
+}
+
+export type GoalDraftStatus = "idle" | "running" | "succeeded" | "failed" | "stopped";
+
+export interface GoalDraftRun {
+  status: GoalDraftStatus;
+  path: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  error: string | null;
+  activity: string[];
+  question: RunQuestion | null;
+}
+
+export type ScoutLifecycle = "stopped" | "idle" | "scanning" | "failed";
+export type ScoutIssueState = "pending" | "implemented";
+export type ScoutSyncState = "ok" | "error" | "stale";
+
+/** One Auto Scout issue, as GitHub last reported it. */
+export interface ScoutIssueRow {
+  number: number;
+  title: string;
+  url: string;
+  createdAt: string;
+  /** An open issue is `pending`; a closed one is `implemented`. */
+  state: ScoutIssueState;
+  /** The recommendation's category, the body's `## Category`, or null. */
+  category: string | null;
+  /** The earliest published release that shipped the closing commit, or null. */
+  version: string | null;
+}
+
+export interface ScoutLimits {
+  maxPerHour: number;
+  maxPending: number;
+}
+
+export interface ScoutSync {
+  state: ScoutSyncState;
+  /** The last successful read, or null before one. */
+  at: string | null;
+  /** Why the last read failed, or null. */
+  error: string | null;
+}
+
+export interface ScoutScanRecord {
+  scanId: string;
+  startedAt: string;
+  /** How many recommendations the request asked for. */
+  requested: number;
+}
+
+/** The scout worker's published state, as the dashboard is allowed to see it. */
+export interface ScoutSnapshot {
+  present: boolean;
+  repo: string | null;
+  root: string;
+  lifecycle: ScoutLifecycle;
+  enabled: boolean;
+  attached: boolean;
+  worker: IssuesWorkerRecord | null;
+  limits: ScoutLimits;
+  issues: ScoutIssueRow[];
+  sync: ScoutSync;
+  scan: ScoutScanRecord | null;
+  newestScanId: string | null;
+  nextAttemptAt: string | null;
+  lastError: string | null;
+  notice: string | null;
+  updatedAt: string | null;
+}
+
+export interface ScoutActivityEntry {
+  text: string;
+  append: boolean;
+}
+
+export type WatchdogIssueState = "pending" | "implemented";
+export type WatchdogSyncState = "ok" | "error" | "stale";
+
+/** One issue the watchdog filed, with what GitHub last reported for it. */
+export interface WatchdogIssue {
+  url: string;
+  category: string;
+  line: string;
+  filedAt: string;
+  /** `null` until a GitHub read has answered for this issue. */
+  state: WatchdogIssueState | null;
+  /** The earliest published release that shipped the closing commit, or null. */
+  version: string | null;
+}
+
+export interface WatchdogCycleWindow {
+  start: string | null;
+  end: string | null;
+}
+
+/** One retained watchdog run directory. */
+export interface WatchdogCycle {
+  at: string;
+  window: WatchdogCycleWindow;
+  action: string;
+  findings: number;
+  /** The GitHub issues this cycle's findings map to, in finding order. */
+  issues: string[];
+  reason?: string;
+}
+
+export interface WatchdogSync {
+  state: WatchdogSyncState;
+  /** The last successful read, or null before one. */
+  at: string | null;
+  /** Why the last read failed, or null after a success. */
+  error: string | null;
+}
+
+/** `GET /api/watchdog`, as the page renders it. */
+export interface WatchdogSnapshot {
+  cycle: string | null;
+  action: string;
+  reason?: string;
+  findings: number;
+  issues: WatchdogIssue[];
+  pending: number;
+  cycles: WatchdogCycle[];
+  sync: WatchdogSync;
+}
+
+export interface SkillSummary {
+  name: string;
+  description: string;
+  /** Which preparation owns the skill; an older server sends neither field. */
+  family?: "prepare" | "discover";
+  state?: "generated" | "edited" | "missing";
+  /** The SKILL.md text; absent from an older server. */
+  content?: string;
+}
+
+/** The issue reporter's overlay phase, shared between the shell and the overlay. */
+export type FeedbackPhase = "idle" | "picking" | "composing" | "sending" | "failed";
+
+/** The UI issue action an armed selection mode files. */
+export type FeedbackAction = "report" | "remove" | "redesign";
+
+export interface SkillContradiction {
+  skills: [string, string];
+  directives: [string, string];
+}
+
+export type RunAction = "resolving" | "implementing" | "generating";
+export type LifecycleStage = "goal" | "epic" | "adr" | "implementation" | "finished";
+
+export interface LifecycleWork {
+  kind: "adr" | "epic";
+  id: string;
+  url?: string;
+}
+
+export interface LifecycleState {
+  stage: LifecycleStage;
+  pass: number;
+  work: LifecycleWork | null;
+  paused: boolean;
+}
+
+export type LaneKind = "generation" | "implementation" | "adr";
+export type LaneStatus = "running" | "paused" | "closed" | "failed" | "retrying" | "parked";
+
+export interface LaneEpic {
+  number: number;
+  title: string;
+  url: string;
+}
+
+export interface Lane {
+  id: string;
+  kind: LaneKind;
+  epic: LaneEpic | null;
+  record: { file: string; title: string } | null;
+  attempt: number;
+  status: LaneStatus;
+  activity: string[];
+  question: RunQuestion | null;
+}
+
+export type FlowStatus = "none" | "idle" | "running" | "stopped" | "merged";
+export type FlowCategory =
+  | "contract"
+  | "entity"
+  | "naming"
+  | "data"
+  | "dependency"
+  | "irreversible"
+  | "structure";
+export type AnswerTarget = "goal" | "implementation" | "conversation";
+
+export interface FlowFile {
+  path: string;
+  status: "added" | "modified" | "deleted" | "renamed";
+  insertions: number;
+  deletions: number;
+  diff: string;
+}
+
+export interface FlowWidget {
+  id: string;
+  category: FlowCategory;
+  concept: string;
+  summary: string;
+  rationale: string;
+  files: string[];
+  accepted: boolean;
+}
+
+export interface FlowSteeringNote {
+  id: string;
+  timestamp: string;
+  source: string;
+  text: string;
+  status: "new" | "read";
+}
+
+export interface FlowCheckpoint {
+  id: string;
+  timestamp: string;
+  summary: string;
+  files: number;
+  commit: string;
+  verification: "passed" | "failed" | "not-run";
+}
+
+export interface FlowVerification {
+  command: string;
+  status: "passed" | "failed" | "not-run";
+  timestamp: string;
+  output: string;
+}
+
+export interface FlowBlocker {
+  id: string;
+  timestamp: string;
+  text: string;
+  dismissed: boolean;
+}
+
+export interface FlowPr {
+  forge: "github" | "gitlab";
+  number: number;
+  url: string;
+  state: "none" | "draft" | "live" | "merged" | "closed" | "error";
+}
+
+export interface FlowConversationMessage {
+  role: "developer" | "agent";
+  text: string;
+}
+
+export interface FlowConversation {
+  widgetId: string;
+  messages: FlowConversationMessage[];
+  activity: string[];
+  question: RunQuestion | null;
+}
+
+export interface FlowGoalCreation {
+  activity: string[];
+  question: RunQuestion | null;
+}
+
+export interface FlowHistoryEntry {
+  sessionId: string;
+  goal: string;
+  pr: FlowPr | null;
+}
+
+export interface FlowSnapshot {
+  sessionId: string | null;
+  status: FlowStatus;
+  goal: string;
+  decisions: string;
+  worktree: string | null;
+  branch: string | null;
+  baseRevision: string | null;
+  files: FlowFile[];
+  widgets: FlowWidget[];
+  steering: FlowSteeringNote[];
+  checkpoints: FlowCheckpoint[];
+  verification: FlowVerification | null;
+  blockers: FlowBlocker[];
+  pr: FlowPr | null;
+  prError: string | null;
+  leftover: string | null;
+  question: RunQuestion | null;
+  goalCreation: FlowGoalCreation | null;
+  conversation: FlowConversation | null;
+  activity: string[];
+  notice: string | null;
+  history: FlowHistoryEntry[];
+}
+
+export type Confidence = "observed" | "declared" | "inferred" | "unknown";
+
+export interface Leaf {
+  value: unknown;
+  evidence: string[];
+  confidence: Confidence;
+  reason?: string;
+}
+
+export interface Labelled {
+  language: string;
+  text: string;
+}
+
+export interface Concept {
+  id: string;
+  prefLabels: Labelled[];
+  altLabels?: Labelled[];
+  definitions?: Labelled[];
+  status: string;
+  origin: string;
+  kind: string;
+  grounding?: unknown[];
+}
+
+export interface Glossary {
+  boundedContext: string;
+  titles: Labelled[];
+  concepts: Concept[];
+}
+
+/** How often one concept is used across the host's documentation and source. */
+export interface ConceptUsage {
+  count: number;
+  files: number;
+  examples: string[];
+}
+
+/** Usage keyed by bounded context, then concept id. */
+export type GlossaryUsage = Record<string, Record<string, ConceptUsage>>;
+
+/** The crawl's own judgment of how much a concept matters to the project. */
+export interface ConceptSignificance {
+  score: number;
+  reason: string;
+}
+
+/** Significance keyed by bounded context, then concept id. */
+export type GlossarySignificance = Record<string, Record<string, ConceptSignificance>>;
+
+export interface DiscoverSkill {
+  name: string;
+  state: "generated" | "edited" | "missing";
+  baseline: string | null;
+  live: string | null;
+}
+
+export interface Freshness {
+  project: string;
+  commit: string;
+  dirty: boolean;
+  discoveredAt: string;
+}
+
+/** One remote project whose published bytes the dashboard retains. */
+export interface RetainedRemoteProject {
+  url: string;
+  owner: string;
+  repo: string;
+  /** ISO time the discovery that produced the retained bytes completed. */
+  completedAt: string;
+}
+
+/** The target Discover reads and writes: this host, or a retained remote project. */
+export type DiscoverTarget =
+  | { kind: "host" }
+  | {
+      kind: "remote";
+      url: string;
+      owner: string;
+      repo: string;
+      /** True while the active project's transient clone exists for a run. */
+      checkout: boolean;
+    };
+
+export interface DiscoverStatePayload {
+  active: boolean;
+  runId: string | null;
+  startedAt: string | null;
+  interrupted: boolean;
+  stale: boolean;
+  warnings: string[];
+  busy: string | null;
+  error: string | null;
+  /** True only when the dashboard serves a harness source checkout. */
+  remoteAvailable: boolean;
+  /** Retained remote projects, newest completed discovery first. */
+  retained: RetainedRemoteProject[];
+  /** `owner/name` of the repository being read, or null outside a GitHub remote. */
+  repository: string | null;
+  target: DiscoverTarget;
+  cloning: { url: string } | null;
+  manifest: unknown;
+  freshness: Freshness | null;
+  sheet: Record<string, unknown> | null;
+  /** The manifest's invocations for the commands the sheet recorded. */
+  commandAliases?: Array<{ command: string; alias: string }>;
+  dependencyRepositories: Record<string, string>;
+  glossaries: Glossary[];
+  glossaryUsage: GlossaryUsage;
+  glossarySignificance: GlossarySignificance;
+  decisions: unknown[];
+  skills: DiscoverSkill[];
+}
+
+export type DiscoverTabId =
+  | "overview"
+  | "glossary"
+  | "testing-strategy"
+  | "naming-conventions"
+  | "coding-conventions"
+  | "architecture-boundaries"
+  | "glossary-skill";
+
+export interface DiscoverTab {
+  id: DiscoverTabId;
+  label: string;
+  skill: string | null;
+}
+
+/** One visible turn of the element-scoped Ask conversation. */
+export interface AskTurn {
+  role: "developer" | "agent";
+  text: string;
+}
+
+/** The captured element an Ask question travels with. */
+export interface AskContext {
+  route: string;
+  url: string;
+  selector: string;
+  viewport: string;
+  captured_at: string;
+  visible_text: string;
+  dom_excerpt: string;
+}

package/client/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}