@rbbtsn0w/adg 0.1.0-alpha.1

package/vendor/skills/src/prompts/search-multiselect.ts

@@ -0,0 +1,387 @@
+import * as readline from 'readline';
+import { stripVTControlCharacters } from 'node:util';
+import { Writable } from 'stream';
+import pc from 'picocolors';
+
+// Silent writable stream to prevent readline from echoing input
+const silentOutput = new Writable({
+  write(_chunk, _encoding, callback) {
+    callback();
+  },
+});
+
+export interface SearchItem<T> {
+  value: T;
+  label: string;
+  hint?: string;
+}
+
+export interface LockedSection<T> {
+  title: string;
+  items: SearchItem<T>[];
+  hiddenCount?: number;
+}
+
+export interface SearchMultiselectOptions<T> {
+  message: string;
+  items: SearchItem<T>[];
+  maxVisible?: number;
+  initialSelected?: T[];
+  /** If true, require at least one item to be selected before submitting */
+  required?: boolean;
+  /** Locked section shown above the searchable list - items are always selected and can't be toggled */
+  lockedSection?: LockedSection<T>;
+}
+
+const S_STEP_ACTIVE = pc.green('◆');
+const S_STEP_CANCEL = pc.red('■');
+const S_STEP_SUBMIT = pc.green('◇');
+const S_RADIO_ACTIVE = pc.green('●');
+const S_RADIO_INACTIVE = pc.dim('○');
+const S_CHECKBOX_LOCKED = pc.green('✓');
+const S_BULLET = pc.green('•');
+const S_BAR = pc.dim('│');
+const S_BAR_H = pc.dim('─');
+
+export const cancelSymbol = Symbol('cancel');
+
+/**
+ * Approximate terminal display width (cells) for a string with no ANSI sequences.
+ * Matches common East Asian / emoji double-width behavior used by modern terminals.
+ */
+export function approxStringWidth(plain: string): number {
+  let width = 0;
+  for (const ch of plain) {
+    const code = ch.codePointAt(0)!;
+    if (code === 0) continue;
+    const wide =
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x231a && code <= 0x231b) ||
+      (code >= 0x2329 && code <= 0x232a) ||
+      (code >= 0x23e9 && code <= 0x23ec) ||
+      code === 0x23f0 ||
+      code === 0x23f3 ||
+      (code >= 0x25fd && code <= 0x25fe) ||
+      (code >= 0x2614 && code <= 0x2615) ||
+      (code >= 0x2648 && code <= 0x2653) ||
+      (code >= 0x267f && code <= 0x267f) ||
+      (code >= 0x2693 && code <= 0x2693) ||
+      (code >= 0x26a1 && code <= 0x26a1) ||
+      (code >= 0x26aa && code <= 0x26ab) ||
+      (code >= 0x26bd && code <= 0x26be) ||
+      (code >= 0x26c4 && code <= 0x26c5) ||
+      (code >= 0x26ce && code <= 0x26ce) ||
+      (code >= 0x26d4 && code <= 0x26d4) ||
+      (code >= 0x26ea && code <= 0x26ea) ||
+      (code >= 0x26f2 && code <= 0x26f3) ||
+      (code >= 0x26f5 && code <= 0x26f5) ||
+      (code >= 0x26fa && code <= 0x26fa) ||
+      (code >= 0x26fd && code <= 0x26fd) ||
+      (code >= 0x2705 && code <= 0x2705) ||
+      (code >= 0x270a && code <= 0x270b) ||
+      (code >= 0x2728 && code <= 0x2728) ||
+      (code >= 0x274c && code <= 0x274c) ||
+      (code >= 0x274e && code <= 0x274e) ||
+      (code >= 0x2753 && code <= 0x2755) ||
+      (code >= 0x2757 && code <= 0x2757) ||
+      (code >= 0x2795 && code <= 0x2797) ||
+      (code >= 0x27b0 && code <= 0x27b0) ||
+      (code >= 0x27bf && code <= 0x27bf) ||
+      (code >= 0x2b1b && code <= 0x2b1c) ||
+      (code >= 0x2b50 && code <= 0x2b50) ||
+      (code >= 0x2b55 && code <= 0x2b55) ||
+      (code >= 0x2e80 && code <= 0xa4cf && code !== 0x303f) ||
+      (code >= 0xa960 && code <= 0xa97c) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe10 && code <= 0xfe19) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) ||
+      (code >= 0x1f000 && code <= 0x1f9ff);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+/**
+ * How many physical terminal rows one logical line occupies after soft-wrapping.
+ */
+export function visualRowsForLine(line: string, columns: number): number {
+  const plain = stripVTControlCharacters(line);
+  const cols = Math.max(1, columns);
+  const w = approxStringWidth(plain);
+  return Math.max(1, Math.ceil(w / cols));
+}
+
+/**
+ * Total physical rows for a block of logical lines (used to erase/redraw TUI output).
+ */
+export function countVisualRowsForLines(lines: string[], columns: number | undefined): number {
+  const cols =
+    columns !== undefined && columns > 0
+      ? columns
+      : process.stdout.columns && process.stdout.columns > 0
+        ? process.stdout.columns
+        : 80;
+  return lines.reduce((sum, line) => sum + visualRowsForLine(line, cols), 0);
+}
+
+/**
+ * Interactive search multiselect prompt.
+ * Allows users to filter a long list by typing and select multiple items.
+ * Optionally supports a "locked" section that displays always-selected items.
+ */
+export async function searchMultiselect<T>(
+  options: SearchMultiselectOptions<T>
+): Promise<T[] | symbol> {
+  const {
+    message,
+    items,
+    maxVisible = 8,
+    initialSelected = [],
+    required = false,
+    lockedSection,
+  } = options;
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: silentOutput,
+      terminal: false,
+    });
+
+    // Enable raw mode for keypress detection
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    readline.emitKeypressEvents(process.stdin, rl);
+
+    let query = '';
+    let cursor = 0;
+    const selected = new Set<T>(initialSelected);
+    let lastRenderHeight = 0;
+
+    // Locked items are always included in the result
+    const lockedValues = lockedSection ? lockedSection.items.map((i) => i.value) : [];
+
+    const filter = (item: SearchItem<T>, q: string): boolean => {
+      if (!q) return true;
+      const lowerQ = q.toLowerCase();
+      return (
+        item.label.toLowerCase().includes(lowerQ) ||
+        String(item.value).toLowerCase().includes(lowerQ)
+      );
+    };
+
+    const getFiltered = (): SearchItem<T>[] => {
+      return items.filter((item) => filter(item, query));
+    };
+
+    const clearRender = (): void => {
+      if (lastRenderHeight > 0) {
+        // Move up and clear each line
+        process.stdout.write(`\x1b[${lastRenderHeight}A`);
+        for (let i = 0; i < lastRenderHeight; i++) {
+          process.stdout.write('\x1b[2K\x1b[1B');
+        }
+        process.stdout.write(`\x1b[${lastRenderHeight}A`);
+      }
+    };
+
+    const render = (state: 'active' | 'submit' | 'cancel' = 'active'): void => {
+      clearRender();
+
+      const lines: string[] = [];
+      const filtered = getFiltered();
+
+      // Header
+      const icon =
+        state === 'active' ? S_STEP_ACTIVE : state === 'cancel' ? S_STEP_CANCEL : S_STEP_SUBMIT;
+      lines.push(`${icon}  ${pc.bold(message)}`);
+
+      if (state === 'active') {
+        // Locked section (universal agents)
+        if (lockedSection && lockedSection.items.length > 0) {
+          lines.push(`${S_BAR}`);
+          const lockedTitle = `${pc.bold(lockedSection.title)} ${pc.dim('── always included')}`;
+          lines.push(`${S_BAR}  ${S_BAR_H}${S_BAR_H} ${lockedTitle} ${S_BAR_H.repeat(12)}`);
+          for (const item of lockedSection.items) {
+            lines.push(`${S_BAR}    ${S_BULLET} ${pc.bold(item.label)}`);
+          }
+          if (lockedSection.hiddenCount && lockedSection.hiddenCount > 0) {
+            lines.push(`${S_BAR}    ${pc.dim(`...and ${lockedSection.hiddenCount} more`)}`);
+          }
+          lines.push(`${S_BAR}`);
+          lines.push(
+            `${S_BAR}  ${S_BAR_H}${S_BAR_H} ${pc.bold('Additional agents')} ${S_BAR_H.repeat(29)}`
+          );
+        }
+
+        // Search input
+        const searchLine = `${S_BAR}  ${pc.dim('Search:')} ${query}${pc.inverse(' ')}`;
+        lines.push(searchLine);
+
+        // Hint
+        lines.push(`${S_BAR}  ${pc.dim('↑↓ move, space select, enter confirm')}`);
+        lines.push(`${S_BAR}`);
+
+        // Items
+        const visibleStart = Math.max(
+          0,
+          Math.min(cursor - Math.floor(maxVisible / 2), filtered.length - maxVisible)
+        );
+        const visibleEnd = Math.min(filtered.length, visibleStart + maxVisible);
+        const visibleItems = filtered.slice(visibleStart, visibleEnd);
+
+        if (filtered.length === 0) {
+          lines.push(`${S_BAR}  ${pc.dim('No matches found')}`);
+        } else {
+          for (let i = 0; i < visibleItems.length; i++) {
+            const item = visibleItems[i]!;
+            const actualIndex = visibleStart + i;
+            const isSelected = selected.has(item.value);
+            const isCursor = actualIndex === cursor;
+
+            const radio = isSelected ? S_RADIO_ACTIVE : S_RADIO_INACTIVE;
+            const label = isCursor ? pc.underline(item.label) : item.label;
+            const hint = item.hint ? pc.dim(` (${item.hint})`) : '';
+
+            const prefix = isCursor ? pc.cyan('❯') : ' ';
+            lines.push(`${S_BAR} ${prefix} ${radio} ${label}${hint}`);
+          }
+
+          // Show count if more items
+          const hiddenBefore = visibleStart;
+          const hiddenAfter = filtered.length - visibleEnd;
+          if (hiddenBefore > 0 || hiddenAfter > 0) {
+            const parts: string[] = [];
+            if (hiddenBefore > 0) parts.push(`↑ ${hiddenBefore} more`);
+            if (hiddenAfter > 0) parts.push(`↓ ${hiddenAfter} more`);
+            lines.push(`${S_BAR}  ${pc.dim(parts.join('  '))}`);
+          }
+        }
+
+        // Selected summary (include locked items)
+        lines.push(`${S_BAR}`);
+        const allSelectedLabels = [
+          ...(lockedSection ? lockedSection.items.map((i) => i.label) : []),
+          ...items.filter((item) => selected.has(item.value)).map((item) => item.label),
+        ];
+        if (allSelectedLabels.length === 0) {
+          lines.push(`${S_BAR}  ${pc.dim('Selected: (none)')}`);
+        } else {
+          const summary =
+            allSelectedLabels.length <= 3
+              ? allSelectedLabels.join(', ')
+              : `${allSelectedLabels.slice(0, 3).join(', ')} +${allSelectedLabels.length - 3} more`;
+          lines.push(`${S_BAR}  ${pc.green('Selected:')} ${summary}`);
+        }
+
+        lines.push(`${pc.dim('└')}`);
+      } else if (state === 'submit') {
+        // Final state - show what was selected (including locked)
+        const allSelectedLabels = [
+          ...(lockedSection ? lockedSection.items.map((i) => i.label) : []),
+          ...items.filter((item) => selected.has(item.value)).map((item) => item.label),
+        ];
+        lines.push(`${S_BAR}  ${pc.dim(allSelectedLabels.join(', '))}`);
+      } else if (state === 'cancel') {
+        lines.push(`${S_BAR}  ${pc.strikethrough(pc.dim('Cancelled'))}`);
+      }
+
+      process.stdout.write(lines.join('\n') + '\n');
+      // Use wrapped row count: logical lines can span multiple terminal rows when hints
+      // or labels exceed column width. Using lines.length alone under-counts and breaks
+      // clearRender(), causing the prompt to re-print hundreds of times on each redraw.
+      lastRenderHeight = countVisualRowsForLines(lines, process.stdout.columns);
+    };
+
+    const cleanup = (): void => {
+      process.stdin.removeListener('keypress', keypressHandler);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      rl.close();
+    };
+
+    const submit = (): void => {
+      // If required and no locked items, don't allow submitting with no selection
+      if (required && selected.size === 0 && lockedValues.length === 0) {
+        return;
+      }
+      render('submit');
+      cleanup();
+      // Include locked values in the result
+      resolve([...lockedValues, ...Array.from(selected)]);
+    };
+
+    const cancel = (): void => {
+      render('cancel');
+      cleanup();
+      resolve(cancelSymbol);
+    };
+
+    // Handle keypresses
+    const keypressHandler = (_str: string, key: readline.Key): void => {
+      if (!key) return;
+
+      const filtered = getFiltered();
+
+      if (key.name === 'return') {
+        submit();
+        return;
+      }
+
+      if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+        cancel();
+        return;
+      }
+
+      if (key.name === 'up') {
+        cursor = Math.max(0, cursor - 1);
+        render();
+        return;
+      }
+
+      if (key.name === 'down') {
+        cursor = Math.min(filtered.length - 1, cursor + 1);
+        render();
+        return;
+      }
+
+      if (key.name === 'space') {
+        const item = filtered[cursor];
+        if (item) {
+          if (selected.has(item.value)) {
+            selected.delete(item.value);
+          } else {
+            selected.add(item.value);
+          }
+        }
+        render();
+        return;
+      }
+
+      if (key.name === 'backspace') {
+        query = query.slice(0, -1);
+        cursor = 0;
+        render();
+        return;
+      }
+
+      // Regular character input
+      if (key.sequence && !key.ctrl && !key.meta && key.sequence.length === 1) {
+        query += key.sequence;
+        cursor = 0;
+        render();
+        return;
+      }
+    };
+
+    process.stdin.on('keypress', keypressHandler);
+
+    // Initial render
+    render();
+  });
+}

package/vendor/skills/src/providers/index.ts

@@ -0,0 +1,14 @@
+// Export types
+export type { HostProvider, ProviderMatch, ProviderRegistry, RemoteSkill } from './types.ts';
+
+// Export registry functions
+export { registry, registerProvider, findProvider, getProviders } from './registry.ts';
+
+// Export individual providers
+export {
+  WellKnownProvider,
+  wellKnownProvider,
+  type WellKnownIndex,
+  type WellKnownSkillEntry,
+  type WellKnownSkill,
+} from './wellknown.ts';

package/vendor/skills/src/providers/registry.ts

@@ -0,0 +1,51 @@
+import type { HostProvider, ProviderRegistry } from './types.ts';
+
+class ProviderRegistryImpl implements ProviderRegistry {
+  private providers: HostProvider[] = [];
+
+  register(provider: HostProvider): void {
+    // Check for duplicate IDs
+    if (this.providers.some((p) => p.id === provider.id)) {
+      throw new Error(`Provider with id "${provider.id}" already registered`);
+    }
+    this.providers.push(provider);
+  }
+
+  findProvider(url: string): HostProvider | null {
+    for (const provider of this.providers) {
+      const match = provider.match(url);
+      if (match.matches) {
+        return provider;
+      }
+    }
+    return null;
+  }
+
+  getProviders(): HostProvider[] {
+    return [...this.providers];
+  }
+}
+
+// Singleton registry instance
+export const registry = new ProviderRegistryImpl();
+
+/**
+ * Register a provider with the global registry.
+ */
+export function registerProvider(provider: HostProvider): void {
+  registry.register(provider);
+}
+
+/**
+ * Find a provider that matches the given URL.
+ */
+export function findProvider(url: string): HostProvider | null {
+  return registry.findProvider(url);
+}
+
+/**
+ * Get all registered providers.
+ */
+export function getProviders(): HostProvider[] {
+  return registry.getProviders();
+}

package/vendor/skills/src/providers/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Represents a parsed skill from a remote host.
+ * Different hosts may have different ways of identifying skills.
+ */
+export interface RemoteSkill {
+  /** Display name of the skill (from frontmatter) */
+  name: string;
+  /** Description of the skill (from frontmatter) */
+  description: string;
+  /** Full markdown content including frontmatter */
+  content: string;
+  /** The identifier used for installation directory name */
+  installName: string;
+  /** The original source URL */
+  sourceUrl: string;
+  /** Any additional metadata from frontmatter */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of attempting to match a URL to a provider.
+ */
+export interface ProviderMatch {
+  /** Whether the URL matches this provider */
+  matches: boolean;
+  /** The source identifier for telemetry/storage (e.g., "mintlify/bun.com", "huggingface/hf-skills/hf-jobs") */
+  sourceIdentifier?: string;
+}
+
+/**
+ * Interface for remote SKILL.md host providers.
+ * Each provider knows how to:
+ * - Detect if a URL belongs to it
+ * - Fetch and parse SKILL.md files
+ * - Convert URLs to raw content URLs
+ * - Provide source identifiers for telemetry
+ */
+export interface HostProvider {
+  /** Unique identifier for this provider (e.g., "mintlify", "huggingface", "github") */
+  readonly id: string;
+
+  /** Display name for this provider */
+  readonly displayName: string;
+
+  /**
+   * Check if a URL matches this provider.
+   * @param url - The URL to check
+   * @returns Match result with optional source identifier
+   */
+  match(url: string): ProviderMatch;
+
+  /**
+   * Fetch and parse a SKILL.md file from the given URL.
+   * @param url - The URL to the SKILL.md file
+   * @returns The parsed skill or null if invalid/not found
+   */
+  fetchSkill(url: string): Promise<RemoteSkill | null>;
+
+  /**
+   * Convert a user-facing URL to a raw content URL.
+   * For example, GitHub blob URLs to raw.githubusercontent.com URLs.
+   * @param url - The URL to convert
+   * @returns The raw content URL
+   */
+  toRawUrl(url: string): string;
+
+  /**
+   * Get the source identifier for telemetry/storage.
+   * This should be a stable identifier that can be used to group
+   * skills from the same source.
+   * @param url - The original URL
+   * @returns Source identifier (e.g., "mintlify/bun.com", "huggingface/hf-skills/hf-jobs")
+   */
+  getSourceIdentifier(url: string): string;
+}
+
+/**
+ * Registry for managing host providers.
+ */
+export interface ProviderRegistry {
+  /**
+   * Register a new provider.
+   */
+  register(provider: HostProvider): void;
+
+  /**
+   * Find a provider that matches the given URL.
+   * @param url - The URL to match
+   * @returns The matching provider or null
+   */
+  findProvider(url: string): HostProvider | null;
+
+  /**
+   * Get all registered providers.
+   */
+  getProviders(): HostProvider[];
+}