@upgraide/ui-notes-cli 0.1.2 → 0.2.0

package/commands/batch.ts

@@ -0,0 +1,116 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+import { readFileSync } from 'fs';
+
+interface BatchOp {
+  op: 'resolve' | 'wontfix' | 'comment' | 'reopen';
+  id: string;
+  message?: string;
+  text?: string;
+}
+
+interface BatchOptions {
+  project?: string;
+  concurrency?: number;
+  dryRun?: boolean;
+}
+
+export async function batch(config: Config, source: string, opts: BatchOptions): Promise<void> {
+  let input: string;
+  if (source === '-') {
+    input = await readStdin();
+  } else {
+    input = readFileSync(source, 'utf-8');
+  }
+
+  const lines = input.trim().split('\n').filter(l => l.trim());
+  const ops: BatchOp[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    try {
+      ops.push(JSON.parse(lines[i]));
+    } catch {
+      console.error(`Line ${i + 1}: invalid JSON — skipped`);
+    }
+  }
+
+  if (ops.length === 0) {
+    console.log('No operations to execute.');
+    return;
+  }
+
+  if (opts.dryRun) {
+    console.log(`Dry run: ${ops.length} operations`);
+    for (let i = 0; i < ops.length; i++) {
+      console.log(`[${i + 1}/${ops.length}] ${ops[i].op} ${ops[i].id}`);
+    }
+    return;
+  }
+
+  const concurrency = opts.concurrency || 5;
+  let succeeded = 0;
+  let failed = 0;
+
+  for (let i = 0; i < ops.length; i += concurrency) {
+    const chunk = ops.slice(i, i + concurrency);
+    await Promise.allSettled(
+      chunk.map(async (op, idx) => {
+        const globalIdx = i + idx;
+        try {
+          await executeOp(config, op, opts.project);
+          succeeded++;
+          console.log(`[${globalIdx + 1}/${ops.length}] ${op.op} ${op.id} ✓`);
+        } catch (err: any) {
+          failed++;
+          console.log(`[${globalIdx + 1}/${ops.length}] ${op.op} ${op.id} ✗ ${err.message}`);
+        }
+      })
+    );
+  }
+
+  console.log(`Batch complete: ${succeeded}/${ops.length} succeeded${failed > 0 ? `, ${failed} failed` : ''}`);
+}
+
+async function executeOp(config: Config, op: BatchOp, project?: string): Promise<void> {
+  switch (op.op) {
+    case 'resolve':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'resolved', resolution: op.message },
+        project,
+      });
+      break;
+    case 'wontfix':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'wontfix', resolution: op.message },
+        project,
+      });
+      break;
+    case 'comment':
+      if (!op.text) throw new Error('Missing "text" field for comment operation');
+      await apiFetch(config, `/notes/${op.id}/comments`, {
+        method: 'POST',
+        body: { body: op.text },
+        project,
+      });
+      break;
+    case 'reopen':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'open' },
+        project,
+      });
+      break;
+    default:
+      throw new Error(`Unknown operation: ${(op as any).op}`);
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}

package/commands/changelog.ts

@@ -0,0 +1,150 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+
+interface ChangelogOptions {
+  project?: string;
+  since?: string;
+  format?: 'markdown' | 'json' | 'conventional';
+}
+
+interface Note {
+  id: string;
+  type: string;
+  body: string;
+  component: string | null;
+  resolved_at: string | null;
+}
+
+const TYPE_ORDER = ['bug', 'ux', 'feature', 'question'];
+
+const TYPE_LABELS: Record<string, string> = {
+  bug: 'Bugs',
+  ux: 'UX',
+  feature: 'Features',
+  question: 'Questions',
+};
+
+const TYPE_CONVENTIONAL: Record<string, string> = {
+  bug: 'fix',
+  ux: 'style',
+  feature: 'feat',
+  question: 'docs',
+};
+
+function isISODate(value: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}/.test(value);
+}
+
+function resolveTimestamp(since: string): string {
+  if (isISODate(since)) {
+    return since;
+  }
+
+  // Treat as git ref, resolve to ISO timestamp
+  const result = Bun.spawnSync(['git', 'log', '-1', '--format=%cI', since]);
+  const output = result.stdout.toString().trim();
+
+  if (result.exitCode !== 0 || !output) {
+    throw new Error(`Could not resolve git ref "${since}". Make sure it exists.`);
+  }
+
+  return output;
+}
+
+function formatMarkdown(notes: Note[]): string {
+  const grouped: Record<string, Note[]> = {};
+
+  for (const note of notes) {
+    if (!grouped[note.type]) grouped[note.type] = [];
+    grouped[note.type].push(note);
+  }
+
+  const lines: string[] = ['## UI Notes Resolved', ''];
+
+  for (const type of TYPE_ORDER) {
+    const group = grouped[type];
+    if (!group || group.length === 0) continue;
+
+    lines.push(`### ${TYPE_LABELS[type] || type}`);
+    for (const note of group) {
+      const shortId = note.id.slice(0, 8);
+      const body = note.body.split('\n')[0].trim();
+      lines.push(`- ${body} (#${shortId})`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatConventional(notes: Note[]): string {
+  const lines: string[] = [];
+
+  for (const type of TYPE_ORDER) {
+    const group = notes.filter((n) => n.type === type);
+    for (const note of group) {
+      const prefix = TYPE_CONVENTIONAL[note.type] || note.type;
+      const scope = note.component || 'ui';
+      const body = note.body.split('\n')[0].trim();
+      const shortId = note.id.slice(0, 8);
+      lines.push(`${prefix}(${scope}): ${body} (note:${shortId})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatJSON(notes: Note[]): string {
+  const items = notes.map((n) => ({
+    id: n.id,
+    type: n.type,
+    body: n.body,
+    component: n.component,
+    resolved_at: n.resolved_at,
+  }));
+  return JSON.stringify(items, null, 2);
+}
+
+export async function changelog(config: Config, opts: ChangelogOptions): Promise<void> {
+  const since = opts.since;
+  if (!since) {
+    console.error('--since is required. Provide a git ref (e.g., HEAD~5, v1.2.0) or ISO date (e.g., 2026-02-01).');
+    process.exit(1);
+  }
+
+  const timestamp = resolveTimestamp(since);
+  const format = opts.format || 'markdown';
+
+  const params = new URLSearchParams();
+  params.set('status', 'all');
+  params.set('resolved_after', timestamp);
+  params.set('limit', '500');
+
+  const path = `/notes?${params.toString()}`;
+  const response = (await apiFetch(config, path, { project: opts.project })) as {
+    ok: boolean;
+    data: { notes: Note[] };
+  };
+
+  const notes = response.data.notes
+    .filter((n) => n.resolved_at)
+    .sort((a, b) => (a.resolved_at! > b.resolved_at! ? 1 : -1));
+
+  if (notes.length === 0) {
+    console.log('No resolved notes found since ' + timestamp);
+    return;
+  }
+
+  switch (format) {
+    case 'json':
+      console.log(formatJSON(notes));
+      break;
+    case 'conventional':
+      console.log(formatConventional(notes));
+      break;
+    case 'markdown':
+    default:
+      console.log(formatMarkdown(notes));
+      break;
+  }
+}

package/commands/explain.ts

@@ -0,0 +1,67 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+
+interface ExplainOptions {
+  format?: 'markdown' | 'json';
+  project?: string;
+}
+
+export async function explain(config: Config, noteId: string, opts: ExplainOptions): Promise<void> {
+  const response = await apiFetch(config, `/notes/${noteId}/explain`, {
+    project: opts.project,
+  }) as any;
+
+  const { note, comments, history, visual_diffs } = response.data;
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(response.data, null, 2));
+    return;
+  }
+
+  // Default: markdown format
+  const lines: string[] = [];
+  lines.push(`# Note ${note.id} — ${note.type} (${note.status})`);
+  lines.push('');
+  if (note.component) lines.push(`**Component**: ${note.component}`);
+  if (note.selector) lines.push(`**Selector**: \`${note.selector}\``);
+  lines.push(`**URL**: ${note.url}`);
+  if (note.author) lines.push(`**Author**: ${note.author}`);
+  lines.push(`**Created**: ${note.created_at}`);
+  if (note.resolved_at) lines.push(`**Resolved**: ${note.resolved_at}`);
+  if (note.screenshot_url) lines.push(`**Screenshot**: ${note.screenshot_url}`);
+  lines.push('');
+  lines.push(`> ${note.body}`);
+
+  if (comments.length > 0) {
+    lines.push('');
+    lines.push(`## Comments (${comments.length})`);
+    lines.push('');
+    for (const c of comments) {
+      lines.push(`**${c.author}** (${c.created_at}):`);
+      lines.push(`> ${c.body}`);
+      lines.push('');
+    }
+  }
+
+  if (history.length > 0) {
+    lines.push('## History');
+    lines.push('');
+    for (const h of history) {
+      lines.push(`- ${h.changed_at}: ${h.field} ${h.old_value ?? '(none)'} → ${h.new_value ?? '(none)'}${h.changed_by ? ` (${h.changed_by})` : ''}`);
+    }
+  }
+
+  if (visual_diffs.length > 0) {
+    lines.push('');
+    lines.push(`## Visual Diffs (${visual_diffs.length})`);
+    lines.push('');
+    for (const vd of visual_diffs) {
+      lines.push(`- ${vd.created_at}: diff ${vd.diff_percentage != null ? `${vd.diff_percentage}%` : 'N/A'}`);
+      if (vd.before_url) lines.push(`  Before: ${vd.before_url}`);
+      if (vd.after_url) lines.push(`  After: ${vd.after_url}`);
+      if (vd.diff_url) lines.push(`  Diff: ${vd.diff_url}`);
+    }
+  }
+
+  console.log(lines.join('\n'));
+}

package/commands/schema.ts

@@ -0,0 +1,33 @@
+import type { Config } from '../config.js';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const RESOURCES = ['notes', 'comments', 'projects', 'webhooks'];
+
+export async function schema(_config: Config, resource?: string): Promise<void> {
+  if (!resource) {
+    console.log('Available schemas:');
+    for (const r of RESOURCES) {
+      console.log(`  ${r}`);
+    }
+    console.log('\nUsage: uinotes schema --resource <name>');
+    return;
+  }
+
+  if (!RESOURCES.includes(resource)) {
+    console.error(`Unknown resource: ${resource}`);
+    console.error(`Available: ${RESOURCES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const schemaDir = join(import.meta.dir, '..', 'schemas');
+  const schemaPath = join(schemaDir, `${resource}.json`);
+
+  try {
+    const content = readFileSync(schemaPath, 'utf-8');
+    console.log(content);
+  } catch {
+    console.error(`Schema file not found: ${schemaPath}`);
+    process.exit(1);
+  }
+}

package/formatters/ai-context.ts

@@ -0,0 +1,236 @@
+import type { ResolvedNote, FileMatch } from '../resolvers/file-resolver.js';
+
+interface Note {
+  id: string;
+  type: string;
+  body: string;
+  url: string;
+  component: string | null;
+  selector: string | null;
+  tag: string | null;
+  text_content: string | null;
+  created_at: string;
+}
+
+interface FormatOptions {
+  format: 'markdown' | 'xml' | 'json';
+  componentFilter?: string;
+  projectName: string;
+  resolvedNotes?: Map<string, ResolvedNote>;
+}
+
+export function formatNotesForAI(notes: Note[], opts: FormatOptions): string {
+  // Filter by component if specified
+  let filtered = notes;
+  if (opts.componentFilter) {
+    filtered = notes.filter(n =>
+      n.component?.toLowerCase().includes(opts.componentFilter!.toLowerCase())
+    );
+  }
+
+  // Group by component
+  const grouped = new Map<string, Note[]>();
+  for (const note of filtered) {
+    const key = note.component || '_unresolved';
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key)!.push(note);
+  }
+
+  const date = new Date().toISOString().split('T')[0];
+
+  if (opts.format === 'xml') {
+    return formatAsXML(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+  }
+  if (opts.format === 'json') {
+    return formatAsJSON(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+  }
+  return formatAsMarkdown(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+}
+
+function formatFileMatch(file: FileMatch): string {
+  const loc = file.lineNumber ? `${file.filePath}:${file.lineNumber}` : file.filePath;
+  return `\`${loc}\` (${file.confidence} confidence, matched on ${file.matchedOn})`;
+}
+
+function formatAsMarkdown(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`# UI Notes: ${projectName}`);
+
+  if (total === 0) {
+    lines.push('> No open notes.');
+    return lines.join('\n') + '\n';
+  }
+
+  const resolveInfo = resolvedNotes ? ' | File resolution: enabled' : '';
+  lines.push(`> ${total} open note${total === 1 ? '' : 's'} as of ${date}${resolveInfo}`);
+  lines.push('');
+
+  for (const [component, notes] of grouped) {
+    if (component === '_unresolved') {
+      lines.push(`## _Unresolved (${notes.length} note${notes.length === 1 ? '' : 's'})`);
+    } else {
+      lines.push(`## Component: ${component} (${notes.length} note${notes.length === 1 ? '' : 's'})`);
+    }
+    lines.push('');
+
+    for (const note of notes) {
+      const typeLabel = (note.type || 'note').toUpperCase();
+      const firstLine = note.body?.split('\n')[0] || '(no body)';
+      lines.push(`### [${typeLabel}] ${firstLine}`);
+
+      // File resolution output
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(note.id);
+        if (resolved && resolved.files.length > 0) {
+          for (const file of resolved.files) {
+            lines.push(`- **File**: ${formatFileMatch(file)}`);
+          }
+        } else {
+          lines.push(`- **File**: _(no match found)_`);
+        }
+      }
+
+      if (note.selector) {
+        lines.push(`- **Selector**: \`${note.selector}\``);
+      }
+      if (note.url) {
+        lines.push(`- **URL**: ${note.url}`);
+      }
+      if (note.tag || note.text_content) {
+        const parts: string[] = [];
+        if (note.tag) parts.push(`<${note.tag}>`);
+        if (note.text_content) parts.push(`"${note.text_content}"`);
+        lines.push(`- **Element**: ${parts.join(' ')}`);
+      }
+      if (note.created_at) {
+        const reported = note.created_at.split('T')[0];
+        lines.push(`- **Reported**: ${reported}`);
+      }
+
+      // Full body as blockquote
+      if (note.body) {
+        const bodyLines = note.body.split('\n').map(l => `> ${l}`);
+        lines.push(bodyLines.join('\n'));
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatAsXML(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`<ui-notes project="${escapeXml(projectName)}" count="${total}" date="${date}">`);
+
+  for (const [component, notes] of grouped) {
+    const compName = component === '_unresolved' ? '_unresolved' : component;
+    lines.push(`  <component name="${escapeXml(compName)}" count="${notes.length}">`);
+
+    for (const note of notes) {
+      const typeAttr = (note.type || 'note').toLowerCase();
+      lines.push(`    <note type="${escapeXml(typeAttr)}" id="${escapeXml(note.id)}">`);
+      lines.push(`      <body>${escapeXml(note.body || '')}</body>`);
+
+      // File resolution output
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(note.id);
+        if (resolved && resolved.files.length > 0) {
+          lines.push(`      <resolved-files>`);
+          for (const file of resolved.files) {
+            const loc = file.lineNumber ? `${file.filePath}:${file.lineNumber}` : file.filePath;
+            lines.push(`        <file path="${escapeXml(loc)}" confidence="${file.confidence}" match-type="${file.matchType}" matched-on="${escapeXml(file.matchedOn)}" />`);
+          }
+          lines.push(`      </resolved-files>`);
+        }
+      }
+
+      if (note.selector) {
+        lines.push(`      <selector>${escapeXml(note.selector)}</selector>`);
+      }
+      if (note.url) {
+        lines.push(`      <url>${escapeXml(note.url)}</url>`);
+      }
+      if (note.tag) {
+        lines.push(`      <tag>${escapeXml(note.tag)}</tag>`);
+      }
+      if (note.text_content) {
+        lines.push(`      <text-content>${escapeXml(note.text_content)}</text-content>`);
+      }
+      if (note.created_at) {
+        lines.push(`      <created>${note.created_at.split('T')[0]}</created>`);
+      }
+      lines.push(`    </note>`);
+    }
+
+    lines.push(`  </component>`);
+  }
+
+  lines.push(`</ui-notes>`);
+  return lines.join('\n') + '\n';
+}
+
+function formatAsJSON(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const components: Record<string, unknown[]> = {};
+
+  for (const [component, notes] of grouped) {
+    components[component] = notes.map(n => {
+      const entry: Record<string, unknown> = {
+        id: n.id,
+        type: n.type,
+        body: n.body,
+        selector: n.selector || undefined,
+        url: n.url || undefined,
+        tag: n.tag || undefined,
+        text_content: n.text_content || undefined,
+        created_at: n.created_at,
+      };
+
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(n.id);
+        entry.resolved_files = resolved?.files || [];
+      }
+
+      return entry;
+    });
+  }
+
+  const output = {
+    project: projectName,
+    total,
+    date,
+    components,
+  };
+
+  return JSON.stringify(output, null, 2) + '\n';
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/index.ts

@@ -25,13 +25,17 @@ Commands:
   login                                 Login and create API key
   pull                                  Fetch open notes
   context                               AI-optimized digest of open notes
+  explain <id>                          Full context for a single note
   resolve <id>                          Mark note as resolved
   wontfix <id>                          Mark note as won't fix
   comment <id> "text"                   Add a comment to a note
   comments <id>                         List comments for a note
   resolve-by-component <name> [msg]     Bulk resolve notes by component
   resolve-by-selector <sel> [msg]       Bulk resolve notes by selector
+  changelog                             Generate changelog from resolved notes
   visual-diff                           Capture & compare page screenshots
+  batch <file|->                        Execute NDJSON batch operations
+  schema                                List or print API resource schemas
   config                                View/edit configuration
 
 Options:
@@ -47,7 +51,11 @@ Options:
   --root-dir <dir>  Source root for file resolution (default: cwd)
   --compare         Compare current screenshots against previous (visual-diff)
   --width <px>      Viewport width for screenshots (default: 1280)
-  --full-page       Capture full page height (default: true)`;
+  --full-page       Capture full page height (default: true)
+  --since <ref>     Git ref or ISO date for changelog start
+  --resource <name> Resource name for schema command
+  --concurrency <n> Concurrent batch operations (default: 5)
+  --dry-run         Preview batch operations without executing`;
 
 function parseFlags(args: string[]): { flags: Record<string, string>; arrays: Record<string, string[]>; positional: string[] } {
   const flags: Record<string, string> = {};
@@ -116,6 +124,13 @@ async function main() {
     return;
   }
 
+  // Schema command is local-only, no API key needed
+  if (command === 'schema') {
+    const { schema } = await import('./commands/schema.js');
+    await schema(getConfig(), flags.resource);
+    return;
+  }
+
   const config = getConfig();
   if (!config.apiKey) {
     console.error('No API key configured. Run: uinotes config set apiKey <your-key>');
@@ -230,6 +245,20 @@ async function main() {
       });
       break;
 
+    case 'explain': {
+      const id = positional[1];
+      if (!id) {
+        console.error('Usage: uinotes explain <note-id> [--format markdown|json]');
+        process.exit(1);
+      }
+      const { explain } = await import('./commands/explain.js');
+      await explain(config, id, {
+        project,
+        format: (flags.format as 'markdown' | 'json') || undefined,
+      });
+      break;
+    }
+
     case 'resolve': {
       const id = positional[1];
       if (!id) {
@@ -288,6 +317,16 @@ async function main() {
       break;
     }
 
+    case 'changelog': {
+      const { changelog } = await import('./commands/changelog.js');
+      await changelog(config, {
+        project,
+        since: flags.since,
+        format: (flags.format as 'markdown' | 'json' | 'conventional') || undefined,
+      });
+      break;
+    }
+
     case 'visual-diff': {
       const { visualDiff } = await import('./commands/visual-diff.js');
       await visualDiff(config, {
@@ -300,6 +339,21 @@ async function main() {
       break;
     }
 
+    case 'batch': {
+      const source = positional[1];
+      if (!source) {
+        console.error('Usage: uinotes batch <file|-> [--concurrency 5] [--dry-run]');
+        process.exit(1);
+      }
+      const { batch } = await import('./commands/batch.js');
+      await batch(config, source, {
+        project,
+        concurrency: flags.concurrency ? parseInt(flags.concurrency) : undefined,
+        dryRun: flags['dry-run'] === 'true',
+      });
+      break;
+    }
+
     case 'resolve-by-selector': {
       const sel = positional[1];
       if (!sel) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upgraide/ui-notes-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],
@@ -9,7 +9,10 @@
   },
   "files": [
     "*.ts",
-    "commands/*.ts"
+    "commands/*.ts",
+    "formatters/*.ts",
+    "resolvers/*.ts",
+    "schemas/*.json"
   ],
   "engines": {
     "bun": ">=1.0.0"

package/resolvers/file-resolver.ts

@@ -0,0 +1,477 @@
+/**
+ * File resolver: maps UI note metadata (component names, CSS selectors) to source files.
+ *
+ * Resolution strategies in priority order:
+ *  1. data-testid / data-component attribute match  (very high confidence)
+ *  2. Component name -> filename match              (high confidence)
+ *  3. Component name -> export/function declaration  (high confidence)
+ *  4. Semantic class name search (non-Tailwind)      (high confidence)
+ *  5. ID attribute search                            (high confidence)
+ */
+
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, relative, basename, extname } from 'path';
+import { existsSync } from 'fs';
+import {
+  parseSelector,
+  filterSemanticClasses,
+  type SelectorTokens,
+} from './selector-parser.js';
+
+export interface FileMatch {
+  filePath: string;
+  lineNumber: number | null;
+  matchType: 'data-attr' | 'component' | 'selector' | 'id' | 'tag';
+  confidence: 'high' | 'medium' | 'low';
+  matchedOn: string;
+}
+
+export interface ResolvedNote {
+  noteId: string;
+  files: FileMatch[];
+}
+
+export interface ResolveOptions {
+  rootDir: string;
+  extensions?: string[];
+  excludeDirs?: string[];
+}
+
+const DEFAULT_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte'];
+const DEFAULT_EXCLUDE_DIRS = [
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+  '.git',
+  'coverage',
+];
+
+interface NoteForResolution {
+  id: string;
+  component?: string | null;
+  selector?: string | null;
+  tag?: string | null;
+}
+
+/**
+ * Check whether the project uses Tailwind CSS by looking for config files.
+ */
+function detectTailwind(rootDir: string): boolean {
+  const configFiles = [
+    'tailwind.config.js',
+    'tailwind.config.ts',
+    'tailwind.config.mjs',
+    'tailwind.config.cjs',
+  ];
+  return configFiles.some((f) => existsSync(join(rootDir, f)));
+}
+
+/**
+ * Recursively collect source files under rootDir, respecting extension and exclusion filters.
+ */
+async function collectSourceFiles(
+  dir: string,
+  extensions: string[],
+  excludeDirs: string[],
+): Promise<string[]> {
+  const results: string[] = [];
+
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!excludeDirs.includes(entry.name)) {
+        const sub = await collectSourceFiles(fullPath, extensions, excludeDirs);
+        results.push(...sub);
+      }
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name);
+      if (extensions.includes(ext)) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find the 1-based line number of the first occurrence of `pattern` in `content`.
+ */
+function findLineNumber(content: string, pattern: RegExp): number | null {
+  const match = content.match(pattern);
+  if (!match || match.index === undefined) return null;
+  return content.slice(0, match.index).split('\n').length;
+}
+
+// ── Strategy: data-attribute match ───────────────────────────────────────
+
+async function resolveByDataAttribute(
+  attrs: SelectorTokens['dataAttributes'],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const attr of attrs) {
+    if (!attr.value) continue;
+    const searchPattern = new RegExp(
+      `${escapeRegex(attr.name)}\\s*=\\s*["']${escapeRegex(attr.value)}["']`,
+    );
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, searchPattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'data-attr',
+          confidence: 'high',
+          matchedOn: `${attr.name}="${attr.value}"`,
+        });
+      }
+    }
+
+    // data-testid is very high confidence; return immediately if found
+    if (matches.length > 0) return matches;
+  }
+
+  return matches;
+}
+
+// ── Strategy: Component name -> filename match ───────────────────────────
+
+async function resolveByComponentFilename(
+  componentName: string,
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+  const normalizedName = componentName.toLowerCase();
+
+  for (const filePath of sourceFiles) {
+    const fileName = basename(filePath)
+      .replace(/\.[^.]+$/, '')
+      .toLowerCase();
+
+    if (fileName === normalizedName) {
+      // Try to find the exact component declaration for a line number
+      const content = await getFileContent(filePath, fileContents);
+      let lineNumber: number | null = null;
+      if (content) {
+        lineNumber = findComponentDeclarationLine(content, componentName);
+      }
+
+      matches.push({
+        filePath: relative(rootDir, filePath),
+        lineNumber,
+        matchType: 'component',
+        confidence: 'high',
+        matchedOn: componentName,
+      });
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: Component name -> export/function search ───────────────────
+
+async function resolveByComponentDeclaration(
+  componentName: string,
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+  const escaped = escapeRegex(componentName);
+
+  const patterns = [
+    new RegExp(`(?:export\\s+)?function\\s+${escaped}\\b`),
+    new RegExp(`(?:export\\s+)?const\\s+${escaped}\\s*[=:]`),
+    new RegExp(`(?:export\\s+)?class\\s+${escaped}\\b`),
+    new RegExp(`export\\s+default\\s+${escaped}\\b`),
+    new RegExp(`displayName\\s*=\\s*['"]${escaped}['"]`),
+  ];
+
+  for (const filePath of sourceFiles) {
+    const content = await getFileContent(filePath, fileContents);
+    if (!content) continue;
+
+    for (const pattern of patterns) {
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'component',
+          confidence: 'high',
+          matchedOn: componentName,
+        });
+        break; // One match per file is enough
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: Semantic class name search ─────────────────────────────────
+
+async function resolveBySemanticClasses(
+  classNames: string[],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const cls of classNames) {
+    const pattern = new RegExp(escapeRegex(cls));
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'selector',
+          confidence: 'high',
+          matchedOn: `.${cls}`,
+        });
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: ID attribute search ────────────────────────────────────────
+
+async function resolveByIds(
+  ids: string[],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const id of ids) {
+    const pattern = new RegExp(`id\\s*=\\s*["']${escapeRegex(id)}["']`);
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'id',
+          confidence: 'high',
+          matchedOn: `#${id}`,
+        });
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Read file content with caching within a single invocation.
+ */
+async function getFileContent(
+  filePath: string,
+  cache: Map<string, string>,
+): Promise<string | null> {
+  if (cache.has(filePath)) return cache.get(filePath)!;
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    cache.set(filePath, content);
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the line number of a component function/const declaration.
+ */
+function findComponentDeclarationLine(
+  content: string,
+  componentName: string,
+): number | null {
+  const escaped = escapeRegex(componentName);
+  const patterns = [
+    new RegExp(`(?:export\\s+)?function\\s+${escaped}\\b`),
+    new RegExp(`(?:export\\s+)?const\\s+${escaped}\\s*[=:]`),
+    new RegExp(`(?:export\\s+)?class\\s+${escaped}\\b`),
+    new RegExp(`export\\s+default\\s+${escaped}\\b`),
+  ];
+  for (const p of patterns) {
+    const line = findLineNumber(content, p);
+    if (line !== null) return line;
+  }
+  return null;
+}
+
+/**
+ * Deduplicate file matches, keeping the highest-confidence match per file.
+ */
+function deduplicateMatches(matches: FileMatch[]): FileMatch[] {
+  const byFile = new Map<string, FileMatch>();
+  const confidenceRank = { high: 3, medium: 2, low: 1 };
+
+  for (const m of matches) {
+    const existing = byFile.get(m.filePath);
+    if (
+      !existing ||
+      confidenceRank[m.confidence] > confidenceRank[existing.confidence]
+    ) {
+      byFile.set(m.filePath, m);
+    }
+  }
+
+  return Array.from(byFile.values());
+}
+
+// ── Main entry point ─────────────────────────────────────────────────────
+
+/**
+ * Resolve a single note to source files.
+ */
+export async function resolveNoteToFiles(
+  note: NoteForResolution,
+  opts: ResolveOptions,
+): Promise<ResolvedNote> {
+  const extensions = opts.extensions || DEFAULT_EXTENSIONS;
+  const excludeDirs = opts.excludeDirs || DEFAULT_EXCLUDE_DIRS;
+  const rootDir = opts.rootDir;
+
+  const sourceFiles = await collectSourceFiles(rootDir, extensions, excludeDirs);
+  const fileContents = new Map<string, string>();
+  const hasTailwind = detectTailwind(rootDir);
+
+  if (sourceFiles.length === 0) {
+    console.error(
+      `Warning: No source files found in ${rootDir}. Check --root-dir or resolve.rootDir in config.`,
+    );
+    return { noteId: note.id, files: [] };
+  }
+
+  let allMatches: FileMatch[] = [];
+
+  // Parse selector tokens if we have a selector
+  let tokens: SelectorTokens | null = null;
+  if (note.selector) {
+    tokens = parseSelector(note.selector);
+  }
+
+  // Strategy 1: data-attribute match (very high confidence, short-circuits)
+  if (tokens && tokens.dataAttributes.length > 0) {
+    const dataMatches = await resolveByDataAttribute(
+      tokens.dataAttributes,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    if (dataMatches.length > 0) {
+      return { noteId: note.id, files: deduplicateMatches(dataMatches) };
+    }
+  }
+
+  // Strategy 2: Component name -> filename match
+  if (note.component) {
+    const filenameMatches = await resolveByComponentFilename(
+      note.component,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...filenameMatches);
+  }
+
+  // Strategy 3: Component name -> export/function search (only if no filename match)
+  if (note.component && allMatches.length === 0) {
+    const declMatches = await resolveByComponentDeclaration(
+      note.component,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...declMatches);
+  }
+
+  // If we already have high-confidence component matches, return early
+  if (allMatches.length > 0) {
+    return { noteId: note.id, files: deduplicateMatches(allMatches) };
+  }
+
+  // Strategy 4: Semantic class name search
+  if (tokens && tokens.classNames.length > 0) {
+    const semanticClasses = filterSemanticClasses(tokens.classNames);
+    if (semanticClasses.length > 0) {
+      const classMatches = await resolveBySemanticClasses(
+        semanticClasses,
+        sourceFiles,
+        rootDir,
+        fileContents,
+      );
+      allMatches.push(...classMatches);
+    }
+  }
+
+  // Strategy 5: ID attribute search
+  if (tokens && tokens.ids.length > 0) {
+    const idMatches = await resolveByIds(
+      tokens.ids,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...idMatches);
+  }
+
+  return { noteId: note.id, files: deduplicateMatches(allMatches) };
+}
+
+/**
+ * Resolve multiple notes in batch, sharing the file cache.
+ */
+export async function resolveNotesToFiles(
+  notes: NoteForResolution[],
+  opts: ResolveOptions,
+): Promise<ResolvedNote[]> {
+  const results: ResolvedNote[] = [];
+  for (const note of notes) {
+    results.push(await resolveNoteToFiles(note, opts));
+  }
+  return results;
+}

package/resolvers/selector-parser.ts

@@ -0,0 +1,80 @@
+/**
+ * CSS selector parser and Tailwind utility class filter.
+ * Extracts searchable tokens from CSS selectors captured by the UI Notes React package.
+ */
+
+export interface SelectorTokens {
+  classNames: string[];
+  ids: string[];
+  tags: string[];
+  dataAttributes: Array<{ name: string; value: string | null }>;
+}
+
+/**
+ * Regex matching common Tailwind CSS utility class prefixes.
+ * Classes matching this pattern carry no semantic meaning for file resolution.
+ */
+const TAILWIND_UTILITY_RE =
+  /^(flex|grid|block|inline|hidden|visible|static|fixed|absolute|relative|sticky|p[xytblr]?-|m[xytblr]?-|text-|bg-|border-|rounded|w-|h-|min-w-|max-w-|gap-|space-|font-|leading-|tracking-|shadow-|opacity-|z-|overflow-|cursor-|transition-|duration-|ease-|animate-|ring-|outline-|placeholder-|divide-|sr-only|not-sr-only|items-|justify-|self-|place-|order-|col-|row-|float-|clear-|object-|aspect-|container|prose|truncate|break-|whitespace-|decoration-|underline|overline|line-through|no-underline|uppercase|lowercase|capitalize|normal-case|italic|not-italic|tabular-nums|oldstyle-nums|lining-nums|proportional-nums|ordinal|slashed-zero|diagonal-fractions|stacked-fractions|list-|align-|table-|border-collapse|border-separate|origin-|scale-|rotate-|translate-|skew-|transform|accent-|appearance-|caret-|scroll-|snap-|touch-|select-|will-change-|fill-|stroke-)/;
+
+/**
+ * Check if a class name looks like a Tailwind utility class.
+ */
+export function isTailwindUtility(className: string): boolean {
+  return TAILWIND_UTILITY_RE.test(className);
+}
+
+/**
+ * Filter out Tailwind utility classes, returning only semantic class names.
+ */
+export function filterSemanticClasses(classNames: string[]): string[] {
+  return classNames.filter((c) => !isTailwindUtility(c));
+}
+
+/**
+ * Parse a CSS selector string into searchable tokens.
+ *
+ * Handles selectors like:
+ *   [data-testid="sidebar"]
+ *   #checkout-form
+ *   nav.sidebar-nav > ul.nav-list
+ *   div.flex > button.submit-btn
+ */
+export function parseSelector(selector: string): SelectorTokens {
+  const classNames: string[] = [];
+  const ids: string[] = [];
+  const tags: string[] = [];
+  const dataAttributes: Array<{ name: string; value: string | null }> = [];
+
+  // Extract data-* attribute selectors: [data-testid="value"] or [data-component="value"]
+  const dataMatches = selector.matchAll(
+    /\[(data-[\w-]+)(?:="([^"]*)")?\]/g,
+  );
+  for (const m of dataMatches) {
+    dataAttributes.push({ name: m[1], value: m[2] ?? null });
+  }
+
+  // Extract .class-names (handling CSS-escaped chars like \.)
+  const classMatches = selector.matchAll(/\.([a-zA-Z_][\w-]*)/g);
+  for (const m of classMatches) {
+    classNames.push(m[1]);
+  }
+
+  // Extract #ids
+  const idMatches = selector.matchAll(/#([a-zA-Z_][\w-]*)/g);
+  for (const m of idMatches) {
+    ids.push(m[1]);
+  }
+
+  // Extract tag names: bare words at start of selector or after combinators (>, +, ~, space)
+  const tagMatches = selector.matchAll(/(?:^|[\s>+~])([a-z][a-z0-9]*)\b/gi);
+  for (const m of tagMatches) {
+    const tag = m[1].toLowerCase();
+    // Exclude common non-tag tokens
+    if (tag !== 'data' && tag !== 'not') {
+      tags.push(tag);
+    }
+  }
+
+  return { classNames, ids, tags, dataAttributes };
+}

package/schemas/comments.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Comment",
+  "description": "A comment on a note",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique comment identifier" },
+    "note_id": { "type": "string", "description": "ID of the parent note" },
+    "author": { "type": "string", "description": "Comment author" },
+    "body": { "type": "string", "description": "Comment text" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "note_id", "author", "body", "created_at"]
+}

package/schemas/notes.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Note",
+  "description": "A UI feedback note attached to a page element",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique note identifier" },
+    "project": { "type": "string", "description": "Project slug this note belongs to" },
+    "type": { "type": "string", "enum": ["bug", "ux", "feature", "question"], "description": "Type of feedback" },
+    "status": { "type": "string", "enum": ["open", "resolved", "wontfix"], "description": "Current status" },
+    "body": { "type": "string", "description": "Note content/description" },
+    "url": { "type": "string", "description": "Page URL where the note was created" },
+    "component": { "type": ["string", "null"], "description": "Component name from data attributes" },
+    "text_content": { "type": ["string", "null"], "description": "Text content of the annotated element" },
+    "selector": { "type": ["string", "null"], "description": "CSS selector for the annotated element" },
+    "tag": { "type": ["string", "null"], "description": "HTML tag of the annotated element" },
+    "author": { "type": ["string", "null"], "description": "Author email or name" },
+    "screenshot_url": { "type": ["string", "null"], "description": "URL to the screenshot capture" },
+    "resolution": { "type": ["string", "null"], "description": "Resolution message when resolved" },
+    "resolved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the note was resolved" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "project", "type", "status", "body", "url", "created_at"]
+}

package/schemas/projects.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Project",
+  "description": "A UI Notes project that groups notes",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique project identifier" },
+    "slug": { "type": "string", "description": "URL-friendly project identifier" },
+    "name": { "type": "string", "description": "Display name" },
+    "url_patterns": { "type": "array", "items": { "type": "string" }, "description": "URL glob patterns for auto-matching" },
+    "archived": { "type": "boolean", "description": "Whether the project is archived" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "slug", "name", "created_at"]
+}

package/schemas/webhooks.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Webhook",
+  "description": "A webhook endpoint for receiving note events",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique webhook identifier" },
+    "project_id": { "type": "string", "description": "Project this webhook belongs to" },
+    "url": { "type": "string", "description": "Webhook delivery URL" },
+    "secret": { "type": ["string", "null"], "description": "HMAC signing secret" },
+    "events": { "type": "array", "items": { "type": "string" }, "description": "Events to subscribe to" },
+    "active": { "type": "boolean", "description": "Whether the webhook is active" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "project_id", "url", "events", "active", "created_at"]
+}