@dsdenes/devboard 0.1.559 → 0.1.562

package/client/lib/discover.svelte.ts

@@ -0,0 +1,412 @@
+import { connection } from "./connection.svelte";
+import { dependencyName } from "../../lib/dependencies.ts";
+import { notifications } from "./notifications.svelte";
+import {
+  commandAlias,
+  conceptSignificance,
+  conceptUsage,
+  filterContexts,
+  glossaryHasSignificance,
+  scalarText,
+  sectionLeaf,
+  SIGNIFICANCE_FLOOR,
+} from "./discover-format";
+import type {
+  ConceptSignificance,
+  ConceptUsage,
+  DiscoverSkill,
+  DiscoverStatePayload,
+  DiscoverTarget,
+  Freshness,
+  Glossary,
+  GlossarySignificance,
+  GlossaryUsage,
+  RetainedRemoteProject,
+  RunQuestion,
+  RunQuestionOption,
+} from "./types";
+
+type Message = Record<string, unknown>;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function appendLine(lines: string[], text: string, append: boolean): string[] {
+  if (append && lines.length > 0) {
+    return [...lines.slice(0, -1), (lines[lines.length - 1] ?? "") + text];
+  }
+  return [...lines, text];
+}
+
+export class DiscoverStore {
+  state = $state<DiscoverStatePayload | null>(null);
+  active = $state(false);
+  runId = $state<string | null>(null);
+  startedAt = $state<string | null>(null);
+  activity = $state<string[]>([]);
+  question = $state<RunQuestion | null>(null);
+  error = $state<string | null>(null);
+  warnings = $state<string[]>([]);
+  interrupted = $state(false);
+  transition = $state<string | null>(null);
+  answerDraft = $state("");
+  glossarySearch = $state("");
+  /** The URL field of the source-checkout-only remote target strip. */
+  remoteUrl = $state("");
+  /** Significance floor a listed term needs to stay listed. */
+  glossaryThreshold = $state(SIGNIFICANCE_FLOOR);
+  /** Hide scored terms below the floor; on by default. */
+  glossarySignificantOnly = $state(true);
+
+  drafts = $state<Record<string, string>>({});
+  dirty = $state<Record<string, boolean>>({});
+
+  get remoteAvailable(): boolean {
+    return this.state?.remoteAvailable === true;
+  }
+
+  get target(): DiscoverTarget {
+    return this.state?.target ?? { kind: "host" };
+  }
+
+  /** The repository identity the head shows: `owner/name` when it is known. */
+  get repository(): string | null {
+    if (typeof this.state?.repository === "string" && this.state.repository.length > 0) {
+      return this.state.repository;
+    }
+    const target = this.target;
+    return target.kind === "remote" ? `${target.owner}/${target.repo}` : null;
+  }
+
+  get remoteTarget(): Extract<DiscoverTarget, { kind: "remote" }> | null {
+    const target = this.target;
+    return target.kind === "remote" ? target : null;
+  }
+
+  /** Every retained remote project, newest completed discovery first. */
+  get retained(): RetainedRemoteProject[] {
+    return Array.isArray(this.state?.retained) ? this.state.retained : [];
+  }
+
+  /** True while the remote target cannot be changed without a refusal. */
+  get remoteChangeDisabled(): boolean {
+    return this.remoteChangeTitle !== undefined;
+  }
+
+  get remoteChangeTitle(): string | undefined {
+    if (!connection.open) return "Not connected";
+    if (this.cloning !== null) return "A repository clone is running";
+    if (this.active) return "A Discover run is active";
+    return this.busy ?? undefined;
+  }
+
+  get cloning(): { url: string } | null {
+    return this.state?.cloning ?? null;
+  }
+
+  /** The remote start control's disabled state; its title names the reason. */
+  get remoteStartDisabled(): boolean {
+    return this.remoteStartTitle !== undefined;
+  }
+
+  get remoteStartTitle(): string | undefined {
+    if (!connection.open) return "Not connected";
+    if (this.cloning !== null) return "A repository clone is running";
+    if (this.active) return "A Discover run is active";
+    if (this.busy !== null) return this.busy;
+    if (this.remoteUrl.trim().length === 0) return "Enter a GitHub repository URL";
+    return undefined;
+  }
+
+  get busy(): string | null {
+    return this.state?.busy ?? null;
+  }
+
+  get stale(): boolean {
+    return this.state?.stale === true;
+  }
+
+  get freshness(): Freshness | null {
+    return this.state?.freshness ?? null;
+  }
+
+  get sheet(): Record<string, unknown> | null {
+    return this.state?.sheet ?? null;
+  }
+
+  get repositories(): Record<string, string> {
+    const value = this.state?.dependencyRepositories;
+    return typeof value === "object" && value !== null ? value : {};
+  }
+
+  /** The repository URL an installed package behind this entry declares. */
+  repositoryLink(line: string): string | null {
+    const name = dependencyName(line);
+    if (name.length === 0) return null;
+    return this.repositories[name] ?? this.repositories[name.toLowerCase()] ?? null;
+  }
+
+  get hasArtifacts(): boolean {
+    return this.sheet !== null;
+  }
+
+  get displayError(): string | null {
+    return this.error ?? this.state?.error ?? null;
+  }
+
+  get displayedWarnings(): string[] {
+    return this.warnings.length > 0 ? this.warnings : (this.state?.warnings ?? []);
+  }
+
+  get contexts(): Glossary[] {
+    return Array.isArray(this.state?.glossaries) ? this.state.glossaries : [];
+  }
+
+  get glossaryUsage(): GlossaryUsage {
+    const value = this.state?.glossaryUsage;
+    return typeof value === "object" && value !== null ? value : {};
+  }
+
+  get glossarySignificance(): GlossarySignificance {
+    const value = this.state?.glossarySignificance;
+    return typeof value === "object" && value !== null ? value : {};
+  }
+
+  /** True when the published glossary carries at least one crawl score. */
+  get glossaryHasScores(): boolean {
+    return glossaryHasSignificance(this.contexts, this.glossarySignificance);
+  }
+
+  usageFor(context: string, id: string): ConceptUsage {
+    return conceptUsage(this.glossaryUsage, context, id);
+  }
+
+  significanceFor(context: string, id: string): ConceptSignificance | null {
+    return conceptSignificance(this.glossarySignificance, context, id) ?? null;
+  }
+
+  get filteredContexts(): Glossary[] {
+    return filterContexts(this.contexts, {
+      search: this.glossarySearch,
+      significantOnly: this.glossarySignificantOnly,
+      floor: this.glossaryThreshold,
+      significance: this.glossarySignificance,
+    });
+  }
+
+  /** The invocation that runs the whole suite, preferring the manifest's own alias. */
+  get testCommand(): string {
+    const leaf = sectionLeaf(this.sheet?.commands, "test");
+    if (leaf === undefined || leaf.confidence === "unknown") return "";
+    return this.aliasFor(scalarText(leaf.value));
+  }
+
+  /** The command to show for a recorded command: its declared alias when one exists. */
+  aliasFor(command: string): string {
+    return commandAlias(this.state?.commandAliases, command);
+  }
+
+  get startDisabled(): boolean {
+    return !connection.open || this.active || this.busy !== null;
+  }
+
+  get startTitle(): string | undefined {
+    if (!connection.open) return "Not connected";
+    if (this.active) return "A Discover run is active";
+    return this.busy ?? undefined;
+  }
+
+  get skills(): DiscoverSkill[] {
+    return Array.isArray(this.state?.skills) ? this.state.skills : [];
+  }
+
+  skill(name: string): DiscoverSkill | null {
+    return this.skills.find((skill) => skill.name === name) ?? null;
+  }
+
+  skillDraft(name: string): string {
+    const stored = this.drafts[name];
+    if (stored !== undefined) return stored;
+    const entry = this.skill(name);
+    return entry?.live ?? entry?.baseline ?? "";
+  }
+
+  skillDirty(name: string): boolean {
+    return this.dirty[name] === true;
+  }
+
+  start(): void {
+    connection.send({ type: "discoverProject" });
+  }
+
+  /** Sends exactly one `discoverRemote` for the trimmed URL. */
+  startRemote(): void {
+    const url = this.remoteUrl.trim();
+    if (url.length === 0 || this.remoteStartTitle !== undefined) return;
+    this.remoteUrl = "";
+    connection.send({ type: "discoverRemote", url });
+  }
+
+  /** Returns to this checkout's own artifacts; retained projects are kept. */
+  clearRemote(): void {
+    this.remoteUrl = "";
+    connection.send({ type: "clearDiscoverRemote" });
+  }
+
+  /** Switches to a retained project; never clones or crawls. */
+  switchRemote(url: string): void {
+    if (url.length === 0 || url === this.remoteTarget?.url) return;
+    connection.send({ type: "switchDiscoverRemote", url });
+  }
+
+  /** Deletes one retained project; the host target returns when it was active. */
+  removeRemote(url: string): void {
+    if (url.length === 0) return;
+    connection.send({ type: "removeDiscoverRemote", url });
+  }
+
+  stop(): void {
+    connection.send({ type: "stopDiscover" });
+  }
+
+  answer(value: string): void {
+    if (this.question === null) return;
+    const trimmed = value.trim();
+    if (trimmed.length === 0) return;
+    const id = this.question.id;
+    this.question = null;
+    this.answerDraft = "";
+    connection.send({ type: "answerDiscover", id, value: trimmed });
+  }
+
+  updateDraft(name: string, text: string): void {
+    this.drafts = { ...this.drafts, [name]: text };
+    const live = this.skill(name)?.live ?? this.skill(name)?.baseline ?? "";
+    this.dirty = { ...this.dirty, [name]: text !== live };
+  }
+
+  saveSkill(name: string): void {
+    connection.send({ type: "saveDiscoverSkill", name, text: this.skillDraft(name) });
+  }
+
+  restoreSkill(name: string): void {
+    const baseline = this.skill(name)?.baseline ?? null;
+    if (baseline !== null) {
+      this.drafts = { ...this.drafts, [name]: baseline };
+      this.dirty = { ...this.dirty, [name]: false };
+    }
+    connection.send({ type: "restoreDiscoverSkill", name });
+  }
+
+  discardDraft(name: string): void {
+    const entry = this.skill(name);
+    const live = entry?.live ?? entry?.baseline ?? "";
+    this.drafts = { ...this.drafts, [name]: live };
+    this.dirty = { ...this.dirty, [name]: false };
+  }
+
+  setGlossarySearch(value: string): void {
+    this.glossarySearch = value;
+  }
+
+  setGlossaryThreshold(value: number): void {
+    if (!Number.isFinite(value)) return;
+    this.glossaryThreshold = Math.min(100, Math.max(0, Math.round(value)));
+  }
+
+  setGlossarySignificantOnly(value: boolean): void {
+    this.glossarySignificantOnly = value;
+  }
+
+  /** Restores the default view: no search, the floor, and the filter on. */
+  resetGlossaryFilters(): void {
+    this.glossarySearch = "";
+    this.glossaryThreshold = SIGNIFICANCE_FLOOR;
+    this.glossarySignificantOnly = true;
+  }
+
+  private syncDrafts(payload: DiscoverStatePayload): void {
+    const skills = Array.isArray(payload.skills) ? payload.skills : [];
+    for (const skill of skills) {
+      if (typeof skill?.name !== "string") continue;
+      const live = skill.live ?? skill.baseline ?? "";
+      if (this.dirty[skill.name] !== true) {
+        this.drafts = { ...this.drafts, [skill.name]: live };
+      } else if (this.drafts[skill.name] === live) {
+        this.dirty = { ...this.dirty, [skill.name]: false };
+      }
+    }
+  }
+
+  private applySnapshot(payload: DiscoverStatePayload): void {
+    this.state = payload;
+    this.glossaryThreshold = Math.min(100, Math.max(0, Math.round(this.glossaryThreshold)));
+    this.active = payload.active === true;
+    this.runId = typeof payload.runId === "string" ? payload.runId : null;
+    this.startedAt = typeof payload.startedAt === "string" ? payload.startedAt : null;
+    this.warnings = Array.isArray(payload.warnings)
+      ? payload.warnings.filter((warning): warning is string => typeof warning === "string")
+      : [];
+    this.interrupted = payload.interrupted === true;
+    this.syncDrafts(payload);
+  }
+
+  handleEvent(message: Message): void {
+    const type = message.type;
+
+    if (type === "discoverState" && isObject(message.state)) {
+      this.applySnapshot(message.state as unknown as DiscoverStatePayload);
+      return;
+    }
+    if (type === "discoverStarted") {
+      this.active = true;
+      if (typeof message.runId === "string") this.runId = message.runId;
+      this.startedAt = typeof message.startedAt === "string" ? message.startedAt : null;
+      this.activity = [];
+      this.question = null;
+      this.answerDraft = "";
+      this.error = null;
+      this.transition = null;
+      return;
+    }
+    if (type === "discoverActivity" && typeof message.text === "string") {
+      this.activity = appendLine(this.activity, message.text, message.append === true);
+      return;
+    }
+    if (
+      type === "discoverQuestion" &&
+      (typeof message.id === "string" || typeof message.id === "number") &&
+      typeof message.message === "string" &&
+      Array.isArray(message.options)
+    ) {
+      this.question = {
+        id: message.id,
+        message: message.message,
+        options: message.options as RunQuestionOption[],
+      };
+      this.answerDraft = "";
+      return;
+    }
+    if (type === "discoverStopped") {
+      this.active = false;
+      this.question = null;
+      this.answerDraft = "";
+      if (message.completed === true) {
+        this.transition = null;
+      } else if (typeof message.reason === "string" && message.reason.length > 0) {
+        this.transition = `Discover run stopped: ${message.reason}`;
+      } else {
+        this.transition = "Discover run stopped.";
+      }
+      return;
+    }
+    if (type === "discoverError" && typeof message.message === "string") {
+      this.error = message.message;
+      notifications.push("error", message.message);
+    }
+  }
+}
+
+export const discover = new DiscoverStore();
+

package/client/lib/draft-format.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { draftProposal } from "./draft-format";
+
+const DRAFT = `# Proposed goal: persist remote discoveries
+
+Persist every remote project and offer a switcher.
+
+## Captured UI context
+
+- Route: \`/\`
+- URL: \`http://127.0.0.1:8081/\`
+- Selected element: \`section.panel:nth-of-type(2)\`
+- Viewport: \`2101x1017 @1.21875x\`
+- Captured at: \`2026-10-28T10:30:03.635Z\`
+
+### Visible text
+
+The remote clone is missing.
+
+### DOM excerpt
+
+\`\`\`html
+<section class="panel"></section>
+\`\`\`
+`;
+
+describe("draft proposal", () => {
+  test("drops the captured context and the heading the panel shows", () => {
+    const proposal = draftProposal(DRAFT);
+    expect(proposal).toBe("Persist every remote project and offer a switcher.");
+    expect(proposal).not.toContain("Proposed goal:");
+    expect(proposal).not.toContain("Captured UI context");
+    expect(proposal).not.toContain("Route:");
+    expect(proposal).not.toContain("Unprocessed draft");
+  });
+
+  test("keeps a draft without the marker whole", () => {
+    expect(draftProposal("# Question draft\n\nAsk about the scope.\n")).toBe("Ask about the scope.");
+  });
+
+  test("returns nothing for a draft that is only captured context", () => {
+    expect(draftProposal("# Draft\n\n## Captured UI context\n\nNo page context was captured.\n")).toBe("");
+  });
+
+  test("returns nothing for an empty draft", () => {
+    expect(draftProposal("")).toBe("");
+  });
+});

package/client/lib/draft-format.ts

@@ -0,0 +1,13 @@
+const CONTEXT_MARKER = "## Captured UI context";
+
+/**
+ * Reads the proposal out of a draft. Both writers in `server/feedback.ts` and
+ * `server/goal-proposal.ts` put the captured evidence after this one marker;
+ * the proposal keeps the writer's own text and loses the heading the panel
+ * already shows.
+ */
+export function draftProposal(text: string): string {
+  const index = text.indexOf(CONTEXT_MARKER);
+  const before = index === -1 ? text : text.slice(0, index);
+  return before.trim().replace(/^#\s+[^\n]*/, "").trim();
+}

package/client/lib/flow-save.test.ts

@@ -0,0 +1,148 @@
+import { afterEach, expect, test } from "bun:test";
+import { ConnectionStore, connection } from "./connection.svelte";
+import { FlowStore } from "./flow.svelte";
+import type { FlowSnapshot } from "./types";
+
+interface FakeEnvelope {
+  data: string;
+}
+
+/** Stands in for the browser socket so closed and open sends are explicit. */
+class FakeSocket {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static instances: FakeSocket[] = [];
+
+  readyState = FakeSocket.CONNECTING;
+  onopen: (() => void) | null = null;
+  onmessage: ((event: FakeEnvelope) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: (() => void) | null = null;
+  sent: string[] = [];
+
+  constructor(readonly url: string) {
+    FakeSocket.instances.push(this);
+  }
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  close(): void {
+    this.readyState = FakeSocket.CLOSED;
+    this.onclose?.();
+  }
+
+  open(): void {
+    this.readyState = FakeSocket.OPEN;
+    this.onopen?.();
+  }
+}
+
+interface InstalledGlobals {
+  WebSocket?: unknown;
+  window: unknown;
+  location?: unknown;
+}
+
+const originalGlobals: InstalledGlobals = {
+  WebSocket: (globalThis as unknown as Record<string, unknown>).WebSocket,
+  window: (globalThis as unknown as Record<string, unknown>).window,
+  location: (globalThis as unknown as Record<string, unknown>).location,
+};
+
+function installGlobals(values: InstalledGlobals): void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  if (values.WebSocket !== undefined) target.WebSocket = values.WebSocket;
+  target.window = values.window;
+  if (values.location !== undefined) target.location = values.location;
+}
+
+function restoreGlobals(): void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const [key, value] of Object.entries(originalGlobals)) {
+    if (value === undefined) delete target[key];
+    else target[key] = value;
+  }
+}
+
+function fakeWindow(): Record<string, unknown> {
+  return {
+    setTimeout: () => 0,
+    clearTimeout: () => undefined,
+    setInterval: () => 0,
+    clearInterval: () => undefined,
+  };
+}
+
+function snapshot(goal: string, decisions: string): FlowSnapshot {
+  return { goal, decisions } as unknown as FlowSnapshot;
+}
+
+afterEach(() => {
+  FakeSocket.instances = [];
+  restoreGlobals();
+});
+
+test("a save on a closed connection keeps the drafts dirty", () => {
+  const sockets = new ConnectionStore();
+  expect(sockets.open).toBe(false);
+  const store = new FlowStore();
+  store.applySnapshot(snapshot("old goal", "old decisions"));
+
+  store.setGoalDraft("edited goal");
+  store.saveGoal();
+  expect(store.goalDirty).toBe(true);
+  expect(store.goalDraft).toBe("edited goal");
+
+  store.setDecisionsDraft("edited decisions");
+  store.saveDecisions();
+  expect(store.decisionsDirty).toBe(true);
+  expect(store.decisionsDraft).toBe("edited decisions");
+
+  // The reconnect snapshot must not replace edits that were never sent.
+  store.applySnapshot(snapshot("server goal", "server decisions"));
+  expect(store.goalDraft).toBe("edited goal");
+  expect(store.decisionsDraft).toBe("edited decisions");
+});
+
+test("a save on an open connection clears the matching dirty flag", () => {
+  FakeSocket.instances = [];
+  installGlobals({
+    WebSocket: FakeSocket as unknown as typeof WebSocket,
+    window: fakeWindow(),
+    location: { protocol: "http:", host: "test.invalid" },
+  });
+  const store = new FlowStore();
+  store.applySnapshot(snapshot("old goal", "old decisions"));
+
+  connection.connect();
+  const socket = FakeSocket.instances[0];
+  if (socket === undefined) throw new Error("no socket created");
+  socket.open();
+
+  store.setGoalDraft("edited goal");
+  store.saveGoal();
+  expect(store.goalDirty).toBe(false);
+  expect(socket.sent).toContain(
+    JSON.stringify({ type: "saveFlowGoal", text: "edited goal" }),
+  );
+
+  store.setDecisionsDraft("edited decisions");
+  store.saveDecisions();
+  expect(store.decisionsDirty).toBe(false);
+  expect(socket.sent).toContain(
+    JSON.stringify({ type: "saveFlowDecisions", text: "edited decisions" }),
+  );
+
+  // A later disconnect must not let the next save look successful.
+  socket.close();
+  store.setGoalDraft("second edit");
+  store.saveGoal();
+  expect(store.goalDirty).toBe(true);
+  expect(store.goalDraft).toBe("second edit");
+
+  connection.dispose();
+});