@upgraide/ui-notes-cli 0.1.3 → 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/index.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env bun
 
 import { getConfig } from './config.js';
 import { configShow, configSet } from './commands/config.js';
@@ -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.3",
+  "version": "0.2.0",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],
@@ -11,7 +11,8 @@
     "*.ts",
     "commands/*.ts",
     "formatters/*.ts",
-    "resolvers/*.ts"
+    "resolvers/*.ts",
+    "schemas/*.json"
   ],
   "engines": {
     "bun": ">=1.0.0"

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"]
+}