@upgraide/ui-notes-cli 0.2.3 → 0.2.5

package/commands/doctor.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getConfig, getConfigPath } from '../config.js';
+
+const PACKAGE_NAME = '@upgraide/ui-notes-cli';
+
+const PASS = '\x1b[32m✓\x1b[0m';
+const FAIL = '\x1b[31m✗\x1b[0m';
+const WARN = '\x1b[33m!\x1b[0m';
+
+function check(ok: boolean, label: string, detail?: string): boolean {
+  const icon = ok ? PASS : FAIL;
+  console.log(`  ${icon} ${label}${detail ? `  ${detail}` : ''}`);
+  return ok;
+}
+
+function warn(label: string, detail?: string): void {
+  console.log(`  ${WARN} ${label}${detail ? `  ${detail}` : ''}`);
+}
+
+export async function doctor(): Promise<void> {
+  console.log('uinotes doctor\n');
+  let issues = 0;
+
+  // 1. Config file
+  const globalPath = join(homedir(), '.uinotes.json');
+  const localPath = join(process.cwd(), '.uinotes.json');
+  const hasGlobal = existsSync(globalPath);
+  const hasLocal = existsSync(localPath);
+  const configExists = hasGlobal || hasLocal;
+  if (!check(configExists, 'Config file', configExists ? `(${getConfigPath()})` : 'not found')) {
+    issues++;
+  }
+
+  // 2. API URL
+  const config = getConfig();
+  const hasUrl = !!config.apiUrl;
+  if (!check(hasUrl, 'API URL', hasUrl ? config.apiUrl : 'not set')) {
+    issues++;
+  }
+
+  // 3. API key
+  const hasKey = !!config.apiKey;
+  if (!check(hasKey, 'API key', hasKey ? 'configured' : 'not set — run: uinotes config set apiKey <key>')) {
+    issues++;
+  }
+
+  // 4. API reachability
+  if (hasUrl && hasKey) {
+    try {
+      const res = await fetch(`${config.apiUrl}/api/projects`, {
+        headers: { 'x-api-key': config.apiKey },
+      });
+      if (!check(res.ok, 'API reachable', `HTTP ${res.status}`)) {
+        issues++;
+      }
+    } catch (err: any) {
+      check(false, 'API reachable', err.message);
+      issues++;
+    }
+  } else {
+    warn('API reachable', 'skipped (no API key)');
+  }
+
+  // 5. Project binding
+  const hasProject = !!config.project;
+  if (!check(hasProject, 'Project bound', hasProject ? config.project : 'none — run: uinotes set project <slug>')) {
+    issues++;
+  }
+
+  // 6. Skills installed
+  const skillPath = join(process.cwd(), '.claude', 'skills', 'ui-notes', 'SKILL.md');
+  const skillsInstalled = existsSync(skillPath);
+  if (!check(skillsInstalled, 'Skills installed', skillsInstalled ? skillPath : 'not found — run: uinotes install-skills')) {
+    issues++;
+  }
+
+  // 7. CLI version
+  const pkgPath = join(import.meta.dir, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const currentVersion = pkg.version as string;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`);
+    if (res.ok) {
+      const data = await res.json() as { version: string };
+      const latest = data.version;
+      const upToDate = currentVersion === latest;
+      if (!check(upToDate, 'CLI version', upToDate ? `${currentVersion} (latest)` : `${currentVersion} → ${latest} available — run: uinotes update`)) {
+        issues++;
+      }
+    } else {
+      warn('CLI version', `${currentVersion} (could not check registry)`);
+    }
+  } catch {
+    warn('CLI version', `${currentVersion} (could not reach registry)`);
+  }
+
+  // Summary
+  console.log('');
+  if (issues === 0) {
+    console.log('All checks passed.');
+  } else {
+    console.log(`${issues} issue${issues > 1 ? 's' : ''} found.`);
+  }
+}

package/commands/update.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const PACKAGE_NAME = '@upgraide/ui-notes-cli';
+
+function parseVersion(v: string): number[] {
+  return v.replace(/^v/, '').split('.').map(Number);
+}
+
+function isNewer(latest: number[], current: number[]): boolean {
+  for (let i = 0; i < Math.max(latest.length, current.length); i++) {
+    const a = latest[i] ?? 0;
+    const b = current[i] ?? 0;
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+  return false;
+}
+
+async function detectPackageManager(): Promise<'bun' | 'npm'> {
+  try {
+    const proc = Bun.spawn(['bun', '--version'], { stdout: 'pipe', stderr: 'pipe' });
+    await proc.exited;
+    if (proc.exitCode === 0) return 'bun';
+  } catch {}
+  return 'npm';
+}
+
+export async function update(): Promise<void> {
+  // Read current version
+  const pkgPath = join(import.meta.dir, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const currentVersion = pkg.version as string;
+
+  console.log(`Current version: ${currentVersion}`);
+  console.log('Checking for updates...');
+
+  // Fetch latest from npm registry
+  let latestVersion: string;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`);
+    if (!res.ok) {
+      console.error(`Failed to check registry (HTTP ${res.status})`);
+      process.exit(1);
+    }
+    const data = await res.json() as { version: string };
+    latestVersion = data.version;
+  } catch (err: any) {
+    console.error(`Failed to reach npm registry: ${err.message}`);
+    process.exit(1);
+  }
+
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+
+  if (!isNewer(latest, current)) {
+    console.log(`Already up to date (${currentVersion})`);
+    return;
+  }
+
+  console.log(`New version available: ${latestVersion}`);
+
+  const pm = await detectPackageManager();
+  const cmd = pm === 'bun'
+    ? ['bun', 'add', '-g', PACKAGE_NAME]
+    : ['npm', 'install', '-g', PACKAGE_NAME];
+
+  console.log(`Installing with ${pm}...`);
+  const proc = Bun.spawn(cmd, {
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    console.error('Update failed.');
+    process.exit(1);
+  }
+
+  console.log(`Updated to ${latestVersion}`);
+}

package/index.ts

@@ -36,6 +36,8 @@ Commands:
   batch <file|->                        Execute NDJSON batch operations
   schema                                List or print API resource schemas
   install-skills                        Install Claude Code skill files
+  doctor                                Check CLI config, connectivity & version
+  update                                Check for and install CLI updates
   config                                View/edit configuration
 
 Options:
@@ -143,6 +145,20 @@ async function main() {
     return;
   }
 
+  // doctor is local-only, no API key needed
+  if (command === 'doctor') {
+    const { doctor } = await import('./commands/doctor.js');
+    await doctor();
+    return;
+  }
+
+  // update is local-only, no API key needed
+  if (command === 'update') {
+    const { update } = await import('./commands/update.js');
+    await update();
+    return;
+  }
+
   // install-skills is local-only, no API key needed
   if (command === 'install-skills') {
     const { installSkills } = await import('./commands/install-skills.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upgraide/ui-notes-cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],
@@ -13,7 +13,7 @@
     "formatters/*.ts",
     "resolvers/*.ts",
     "schemas/*.json",
-    "skills/*.md"
+    "skills/**/*.md"
   ],
   "engines": {
     "bun": ">=1.0.0"

package/skills/ui-notes/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: ui-notes
+description: CLI commands for managing UI feedback notes — pull context, resolve issues, add comments, generate changelogs, and batch triage.
+---
+
+# UI Notes CLI
+
+`uinotes` is the CLI for UI Notes. Use these commands to triage, resolve, and manage UI feedback notes from your terminal.
+
+## Configuration
+
+```bash
+uinotes config                          # Show current config
+uinotes config set apiUrl <url>         # Set API URL
+uinotes config set apiKey <key>         # Set API key
+uinotes set project <slug>              # Bind project to current directory
+```
+
+## Context
+
+Fetch an AI-optimized digest of open UI notes.
+
+### When to use
+- At the start of a task to understand what UI issues exist
+- Before making UI changes to check for related notes
+- When the user asks about UI bugs, feedback, or design issues
+
+```bash
+uinotes context --format markdown
+```
+
+Add `--resolve-files --root-dir .` to map notes to source files.
+Add `--type bug` to filter by type (bug, ux, feature, question).
+Add `--project <slug>` to target a specific project.
+
+## Explain
+
+Get full context for a single note including comments, history, and visual diffs.
+
+### When to use
+- When investigating a specific note before fixing it
+- When you need comments, history, or visual diff context
+- When triaging a single note
+
+```bash
+uinotes explain <note-id>
+uinotes explain <note-id> --format json
+```
+
+Returns: note body, type, status, component, selector, URL, screenshot URL, all comments, status history, and visual diffs.
+
+## Resolve
+
+Mark notes as resolved after fixing the issue they describe.
+
+### When to use
+- After fixing a bug, UX issue, or implementing a feature request described in a note
+- After verifying a fix addresses the feedback
+
+```bash
+# Resolve with a message explaining the fix
+uinotes resolve <note-id> "Fixed by updating the component"
+
+# Mark as won't fix with explanation
+uinotes wontfix <note-id> "Working as intended"
+
+# Bulk resolve all notes for a component
+uinotes resolve-by-component <ComponentName> --message "Refactored component"
+```
+
+Always include a resolution message describing what was done.
+
+## Comment
+
+Add comments to notes to document progress or communicate.
+
+### When to use
+- To document what was tried or what's blocking a fix
+- To ask clarifying questions about a note
+- To provide a status update before resolving
+
+```bash
+uinotes comment <note-id> "Comment text here"
+uinotes comments <note-id>  # List existing comments
+```
+
+## Changelog
+
+Generate a changelog from notes resolved since a git ref or date.
+
+### When to use
+- After resolving notes, to generate a summary for PR descriptions
+- For release notes listing UI fixes
+- To audit what was fixed in a time period
+
+```bash
+uinotes changelog --since HEAD~5
+uinotes changelog --since v1.2.0 --format conventional
+uinotes changelog --since 2026-02-01 --format json
+```
+
+Formats: `markdown` (default), `conventional` (conventional commits), `json`.
+
+## Batch
+
+Execute multiple operations (resolve, wontfix, comment, reopen) in one invocation.
+
+### When to use
+- After triaging multiple notes and deciding actions for each
+- When resolving several notes as part of a single fix
+- For bulk operations that span multiple notes
+
+```bash
+echo '{"op":"resolve","id":"abc123","message":"Fixed overflow"}
+{"op":"comment","id":"def456","text":"Needs design input"}
+{"op":"wontfix","id":"ghi789","message":"Deprecated component"}' | uinotes batch -
+```
+
+Operations: `resolve`, `wontfix`, `comment` (requires `text`), `reopen`.
+Add `--dry-run` to preview without executing.
+
+## Pull
+
+Fetch raw note data from the API.
+
+```bash
+uinotes pull
+uinotes pull --project my-app --status open --type bug --limit 50
+```
+
+| Option | Description |
+|--------|-------------|
+| `--project <name>` | Filter by project |
+| `--status <status>` | Filter by status (`open`, `resolved`, `wontfix`) |
+| `--type <type>` | Filter by type (`bug`, `ux`, `feature`, `question`) |
+| `--limit <n>` | Max number of results |
+| `--resolve-files` | Map notes to source files |
+
+## Projects
+
+Manage projects.
+
+```bash
+uinotes projects                              # List all projects
+uinotes projects create <slug> <name>         # Create a project
+uinotes projects get <slug>                   # Get project details
+uinotes projects rename <slug> <name>         # Rename a project
+uinotes projects add-url <slug> <pattern>     # Add URL pattern
+uinotes projects remove-url <slug> <pattern>  # Remove URL pattern
+uinotes projects delete <slug>                # Archive a project
+```
+
+## Visual Diff
+
+Capture and compare page screenshots.
+
+```bash
+uinotes visual-diff --url https://myapp.com --project my-app
+uinotes visual-diff --compare  # Compare against previous screenshots
+```