@mrclrchtr/supi-web 0.1.0

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -0,0 +1,226 @@
+// Generic settings overlay for SuPi extensions.
+//
+// Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
+// and search. Each extension declares its settings via registerSettings().
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@earendil-works/pi-tui";
+import {
+  getRegisteredSettings,
+  type SettingsScope,
+  type SettingsSection,
+} from "./settings-registry.ts";
+
+// ── Input submenu component ──────────────────────────────────
+
+/**
+ * Creates a pi-tui Input-backed submenu component with enter-to-confirm
+ * and escape-to-cancel handling.
+ *
+ * @param currentValue - Initial value for the text input.
+ * @param label - Label text displayed above the input.
+ * @param done - Callback invoked with the confirmed value, or undefined on cancel.
+ */
+export function createInputSubmenu(
+  currentValue: string,
+  label: string,
+  done: (selectedValue?: string) => void,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const input = new Input();
+  input.setValue(currentValue);
+
+  return {
+    render: (_width: number) => {
+      const lines = [`  ${label}`];
+      lines.push(...input.render(_width));
+      lines.push("  enter confirm • esc cancel");
+      return lines;
+    },
+    invalidate: () => {
+      input.invalidate();
+    },
+    handleInput: (data: string) => {
+      if (matchesKey(data, Key.escape)) {
+        done();
+        return true;
+      }
+      if (matchesKey(data, Key.enter)) {
+        done(input.getValue());
+        return true;
+      }
+      input.handleInput(data);
+      return true;
+    },
+  };
+}
+
+// ── Types ────────────────────────────────────────────────────
+
+interface OverlayState {
+  scope: SettingsScope;
+  cwd: string;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────
+
+function getScopeLabel(scope: SettingsScope): string {
+  return scope === "project" ? "Project" : "Global";
+}
+
+function buildFlatItems(
+  sections: SettingsSection[],
+  scope: SettingsScope,
+  cwd: string,
+): SettingItem[] {
+  const items: SettingItem[] = [];
+  for (const section of sections) {
+    const sectionItems = section.loadValues(scope, cwd);
+    for (const item of sectionItems) {
+      items.push({
+        ...item,
+        id: `${section.id}.${item.id}`,
+        label: `${section.label}: ${item.label}`,
+      });
+    }
+  }
+  return items;
+}
+
+function findSectionAndId(
+  sections: SettingsSection[],
+  flatId: string,
+): { section: SettingsSection; itemId: string } | null {
+  const dotIndex = flatId.indexOf(".");
+  if (dotIndex === -1) return null;
+  const sectionId = flatId.slice(0, dotIndex);
+  const itemId = flatId.slice(dotIndex + 1);
+  const section = sections.find((s) => s.id === sectionId);
+  if (!section) return null;
+  return { section, itemId };
+}
+
+// ── Component ────────────────────────────────────────────────
+
+interface SettingsOverlayDeps {
+  state: OverlayState;
+  container: Container;
+  settingsList: SettingsList | null;
+  tui: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[0];
+  theme: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[1];
+  done: () => void;
+}
+
+function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const sections = getRegisteredSettings();
+  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+  const onChange = (flatId: string, newValue: string) => {
+    const found = findSectionAndId(sections, flatId);
+    if (found) {
+      found.section.persistChange(deps.state.scope, deps.state.cwd, found.itemId, newValue);
+    }
+    // Re-read all values to reflect persisted changes, but keep the list
+    // instance (and its selectedIndex) intact.
+    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+    for (const updated of updatedItems) {
+      const existing = items.find((i) => i.id === updated.id);
+      if (existing && existing.currentValue !== updated.currentValue) {
+        settingsList.updateValue(updated.id, updated.currentValue);
+      }
+    }
+    deps.tui.requestRender();
+  };
+  const settingsList = new SettingsList(
+    items,
+    Math.min(items.length + 4, 20),
+    getSettingsListTheme(),
+    onChange,
+    () => deps.done(),
+    { enableSearch: true },
+  );
+  return settingsList;
+}
+
+function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const settingsList = createSettingsList(deps);
+  deps.settingsList = settingsList;
+
+  deps.container.clear();
+  deps.container.addChild(createHeaderComponent(deps));
+  deps.container.addChild(settingsList);
+
+  return settingsList;
+}
+
+function createHeaderComponent(deps: SettingsOverlayDeps): Text {
+  const { theme, state } = deps;
+  const scopeLabel = getScopeLabel(state.scope);
+  const otherScope = state.scope === "project" ? "Global" : "Project";
+  const headerText = new Text(
+    `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
+    0,
+    0,
+  );
+  return headerText;
+}
+
+function handleScopeToggle(deps: SettingsOverlayDeps): void {
+  deps.state.scope = deps.state.scope === "project" ? "global" : "project";
+  rebuildSettingsList(deps);
+  deps.tui.requestRender();
+}
+
+// ── Entry point ──────────────────────────────────────────────
+
+export function openSettingsOverlay(ctx: ExtensionContext): void {
+  const sections = getRegisteredSettings();
+  if (sections.length === 0) {
+    ctx.ui.notify("No settings registered by SuPi extensions", "info");
+    return;
+  }
+
+  void ctx.ui.custom<void>((tui, theme, _kb, done) => {
+    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
+    const container = new Container();
+
+    const deps: SettingsOverlayDeps = {
+      state,
+      container,
+      settingsList: null,
+      tui,
+      theme,
+      done,
+    };
+
+    rebuildSettingsList(deps);
+
+    const component = {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, Key.tab)) {
+          handleScopeToggle(deps);
+          return true;
+        }
+        // Delegate input to the settings list (always set after rebuildSettingsList)
+        deps.settingsList?.handleInput?.(data);
+        deps.tui.requestRender();
+        return true;
+      },
+    };
+
+    return component;
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/terminal.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared terminal title formatting and signaling utilities.
+ *
+ * Centralized place for pi title convention (π prefix), completion (✓)
+ * and waiting (●) indicators, and the audible terminal bell.
+ */
+import path from "node:path";
+
+/** Unicode checkmark shown when the agent finishes a turn. */
+export const DONE_SYMBOL = "\u2713";
+/** Unicode dot shown when waiting for user input. */
+export const WAITING_SYMBOL = "\u25CF";
+
+/** Minimal UI surface needed for title operations. */
+export interface TitleTarget {
+  ui: {
+    setTitle?(title: string): void;
+  };
+}
+
+/**
+ * Format pi's canonical terminal title from session name and cwd.
+ * Falls back gracefully when either is missing.
+ *
+ * @example
+ *   formatTitle("my-session", "/home/projects/foo")  // "π - my-session - foo"
+ *   formatTitle(undefined, "/home/projects/foo")      // "π - foo"
+ *   formatTitle("my-session")                         // "π - my-session"
+ *   formatTitle()                                     // "π"
+ */
+export function formatTitle(sessionName?: string, cwd?: string): string {
+  const base = cwd ? path.basename(cwd) : undefined;
+  if (sessionName && base) return `π - ${sessionName} - ${base}`;
+  if (sessionName) return `π - ${sessionName}`;
+  if (base) return `π - ${base}`;
+  return "π";
+}
+
+/** Sound the audible terminal bell (ASCII BEL). */
+export function signalBell(): void {
+  process.stdout.write("\x07");
+}
+
+/**
+ * Set the terminal title to indicate the agent is waiting for user input.
+ * Prefixes with ● and sounds the terminal bell.
+ */
+export function signalWaiting(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${WAITING_SYMBOL}  ${title}`);
+  signalBell();
+}
+
+/**
+ * Set the terminal title to indicate the agent turn has completed.
+ * Prefixes with ✓ and sounds the terminal bell.
+ */
+export function signalDone(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${DONE_SYMBOL} ${title}`);
+  signalBell();
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mrclrchtr/supi-web",
+  "version": "0.1.0",
+  "description": "SuPi Web extension — fetch web pages as clean Markdown (web_fetch_md) and library docs via Context7 (web_docs_search, web_docs_fetch)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*",
+    "@upstash/context7-sdk": "^0.3.0",
+    "jsdom": "^26.1.0",
+    "@mozilla/readability": "^0.6.0",
+    "turndown": "^7.2.0",
+    "turndown-plugin-gfm": "^1.0.2"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5",
+    "@types/jsdom": "^21.1.7",
+    "@types/turndown": "^5.0.6",
+    "@mrclrchtr/supi-test-utils": "workspace:*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/web.ts",
+      "./src/docs.ts"
+    ]
+  },
+  "main": "src/index.ts"
+}

package/src/context7-client.ts

@@ -0,0 +1,41 @@
+/**
+ * Context7 API client — thin wrapper around @upstash/context7-sdk.
+ *
+ * API key is read automatically from CONTEXT7_API_KEY env var by the SDK.
+ */
+
+import { Context7, Context7Error } from "@upstash/context7-sdk";
+
+export { Context7Error };
+
+export interface SearchResult {
+  id: string;
+  name: string;
+  description: string;
+  totalSnippets: number;
+  trustScore: number;
+  benchmarkScore: number;
+  versions?: string[];
+}
+
+export interface DocSnippet {
+  title: string;
+  content: string;
+  source: string;
+}
+
+const client = new Context7();
+
+export async function searchLibrary(query: string, libraryName: string): Promise<SearchResult[]> {
+  const results = await client.searchLibrary(query, libraryName);
+  return results as unknown as SearchResult[];
+}
+
+export async function getContext(
+  query: string,
+  libraryId: string,
+  raw?: boolean,
+): Promise<string | DocSnippet[]> {
+  const options = raw ? ({ type: "json" } as const) : ({ type: "txt" } as const);
+  return client.getContext(query, libraryId, options) as Promise<string | DocSnippet[]>;
+}

package/src/convert.ts

@@ -0,0 +1,219 @@
+/**
+ * HTML → Markdown conversion via JSDOM + Readability + Turndown.
+ */
+
+import { Readability } from "@mozilla/readability";
+import { JSDOM, VirtualConsole } from "jsdom";
+import Turndown from "turndown";
+import { guessLanguage } from "./fetch.ts";
+
+/**
+ * Convert HTML to clean Markdown.
+ *
+ * @param html - Raw HTML string.
+ * @param baseUrl - Base URL for resolving relative links.
+ * @param options.absLinks - Whether to absolutize links and image sources.
+ * @returns Clean Markdown string.
+ */
+export async function htmlToMarkdown(
+  html: string,
+  baseUrl: string,
+  options: { absLinks?: boolean } = {},
+): Promise<string> {
+  const absLinks = options.absLinks ?? true;
+
+  if (!isHtml(html)) {
+    // Not HTML — wrap as fenced code block
+    return wrapAsCodeBlock(html, baseUrl);
+  }
+
+  const doc = createDocument(html, baseUrl);
+
+  // Remove script/style/noscript
+  for (const tag of ["script", "style", "noscript"]) {
+    for (const el of doc.querySelectorAll(tag)) {
+      el.remove();
+    }
+  }
+
+  // Extract article content with Readability
+  const readability = new Readability(doc);
+  const article = readability.parse();
+
+  const title = article?.title?.trim() || doc.title?.trim() || "";
+
+  // Use Readability content, or fall back to body
+  const contentHtml = article?.content || doc.body?.innerHTML || html;
+
+  // Re-parse content so we can manipulate it cleanly
+  const contentDoc = createDocument(`<html><body>${contentHtml}</body></html>`, baseUrl);
+  const body = contentDoc.body;
+
+  if (absLinks) {
+    absolutizeLinks(body, baseUrl);
+  }
+
+  const turndown = await createTurndown();
+  let markdown = turndown.turndown(body);
+  markdown = cleanMarkdown(markdown);
+
+  // Prepend title if not already present
+  if (title && !markdown.trimStart().startsWith("# ")) {
+    markdown = `# ${title}\n\n${markdown}`;
+  }
+
+  return normalizeWhitespace(markdown);
+}
+
+/**
+ * Wrap plain text in a fenced code block.
+ */
+export function wrapAsCodeBlock(text: string, url: string): string {
+  const lang = guessLanguage(url);
+  const normalized = String(text || "")
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n");
+
+  // Find longest backtick sequence so we can choose a fence that won't conflict
+  const backticks = normalized.match(/`+/g) || [];
+  let maxTicks = 0;
+  for (const bt of backticks) {
+    maxTicks = Math.max(maxTicks, bt.length);
+  }
+  const fence = "`".repeat(Math.max(3, maxTicks + 1));
+  const body = normalized.endsWith("\n") ? normalized : `${normalized}\n`;
+  const prefix = lang ? `${fence}${lang}\n` : `${fence}\n`;
+  return normalizeWhitespace(`${prefix}${body}${fence}\n`);
+}
+
+function createDocument(html: string, url: string): Document {
+  const virtualConsole = new VirtualConsole();
+  return new JSDOM(html, { url, virtualConsole }).window.document;
+}
+
+function absolutizeLinks(root: Element, baseUrl: string): void {
+  for (const a of root.querySelectorAll("a[href]")) {
+    const resolved = resolveUrl(a.getAttribute("href") || "", baseUrl);
+    if (resolved) {
+      a.setAttribute("href", resolved);
+    } else {
+      a.removeAttribute("href");
+    }
+  }
+  for (const img of root.querySelectorAll("img[src]")) {
+    const resolved = resolveUrl(img.getAttribute("src") || "", baseUrl);
+    if (resolved) {
+      img.setAttribute("src", resolved);
+    } else {
+      img.removeAttribute("src");
+    }
+  }
+}
+
+function resolveUrl(href: string, baseUrl: string): string {
+  const trimmed = String(href || "").trim();
+  if (
+    !trimmed ||
+    trimmed.startsWith("#") ||
+    trimmed.startsWith("mailto:") ||
+    trimmed.startsWith("tel:")
+  ) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("javascript:")) {
+    return "";
+  }
+  try {
+    const resolved = new URL(trimmed, baseUrl);
+    return resolved.protocol === "http:" || resolved.protocol === "https:"
+      ? resolved.toString()
+      : trimmed;
+  } catch {
+    return trimmed;
+  }
+}
+
+async function createTurndown(): Promise<Turndown> {
+  const td = new Turndown({
+    codeBlockStyle: "fenced",
+    headingStyle: "atx",
+    hr: "---",
+    bulletListMarker: "-",
+    emDelimiter: "_",
+  });
+
+  // Try loading GFM plugins
+  try {
+    // @ts-expect-error — turndown-plugin-gfm has no @types package
+    const gfmMod = await import("turndown-plugin-gfm");
+    const gfm = (gfmMod as unknown as { default?: unknown }).default ?? gfmMod;
+    const plugins: unknown[] = [];
+    if (gfm && typeof gfm === "object") {
+      const obj = gfm as Record<string, unknown>;
+      if (typeof obj.gfm === "function") plugins.push(obj.gfm);
+      if (typeof obj.tables === "function") plugins.push(obj.tables);
+      if (typeof obj.strikethrough === "function") plugins.push(obj.strikethrough);
+      if (typeof obj.taskListItems === "function") plugins.push(obj.taskListItems);
+    }
+    if (plugins.length > 0) {
+      td.use(plugins as [(turndown: Turndown) => void]);
+    }
+  } catch {
+    // GFM plugin optional
+  }
+
+  // Custom pre → fenced code rule
+  td.addRule("preToFenced", {
+    filter: ["pre"],
+    replacement(_content: string, node: Turndown.Node) {
+      const text = (node as unknown as HTMLElement).textContent ?? "";
+      return `\n\n\`\`\`\n${String(text).replace(/\n+$/g, "")}\n\`\`\`\n\n`;
+    },
+  });
+
+  return td;
+}
+
+function cleanMarkdown(text: string): string {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const out: string[] = [];
+  let inCodeBlock = false;
+
+  for (const raw of lines) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      out.push(raw);
+      continue;
+    }
+    if (
+      !inCodeBlock &&
+      (/^(copy|copy page|copied!?|copy to clipboard)$/i.test(trimmed) ||
+        /^loading\.{3}$/i.test(trimmed))
+    ) {
+      continue;
+    }
+    out.push(raw);
+  }
+
+  return out.join("\n");
+}
+
+function normalizeWhitespace(text: string): string {
+  return `${String(text || "")
+    .replace(/\r\n/g, "\n")
+    .replace(/[ \t]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()}\n`;
+}
+
+function isHtml(text: string): boolean {
+  const trimmed = (text || "").trimStart().slice(0, 2000).toLowerCase();
+  return !!(
+    trimmed.startsWith("<!doctype html") ||
+    trimmed.startsWith("<html") ||
+    trimmed.startsWith("<?xml") ||
+    /<(head|body)\b/.test(trimmed) ||
+    (trimmed.startsWith("<") && /<\/(html|head|body)>/.test(trimmed))
+  );
+}