@upgraide/ui-notes-cli 0.2.4 → 0.2.6

package/README.md

@@ -31,44 +31,32 @@ uinotes resolve 42 "Fixed in latest deploy"
 View or update configuration.
 
 ```bash
-# Show current config
-uinotes config
-
-# Set a value
+uinotes config                              # Show current config
 uinotes config set apiUrl https://my-api.example.com
+uinotes config set apiKey <your-key>
+```
+
+### `uinotes set project`
+
+Bind a project to the current directory (creates `.uinotes` file).
 
-# Bind a project to the current directory
+```bash
 uinotes set project my-app
 ```
 
-**Config keys:** `apiUrl`, `apiKey`
-
 ### `uinotes projects`
 
 Manage projects.
 
 ```bash
-# List all projects
-uinotes projects
-
-# Include archived projects
-uinotes projects --archived
-
-# Create a project with URL patterns
-uinotes projects create my-app "My Application" --url "https://myapp.com/*"
-
-# Get project details
+uinotes projects                              # List all projects
+uinotes projects --archived                   # Include archived
+uinotes projects create my-app "My App" --url "https://myapp.com/*"
 uinotes projects get my-app
-
-# Rename a project
 uinotes projects rename my-app "New Name"
-
-# Add/remove URL patterns
 uinotes projects add-url my-app "https://staging.myapp.com/*"
 uinotes projects remove-url my-app "https://old.myapp.com/*"
-
-# Archive a project
-uinotes projects delete my-app
+uinotes projects delete my-app                # Archive
 ```
 
 ### `uinotes pull`
@@ -78,31 +66,117 @@ Fetch notes from the API.
 ```bash
 uinotes pull
 uinotes pull --project my-app --status open --type bug --limit 50
+uinotes pull --resolve-files --root-dir .     # Map notes to source files
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--project <name>` | Filter by project (overrides default) |
-| `--status <status>` | Filter by status (`open`, `resolved`, `wontfix`) |
-| `--type <type>` | Filter by type (`bug`, `ux`, `feature`, `question`) |
-| `--limit <n>` | Max number of results |
+### `uinotes context`
+
+AI-optimized digest of open notes.
+
+```bash
+uinotes context --project my-app
+uinotes context --format xml --component Header
+uinotes context --resolve-files --root-dir .
+```
 
-### `uinotes resolve`
+### `uinotes explain`
 
-Mark a note as resolved.
+Full context for a single note (body, comments, history, visual diffs).
 
 ```bash
-uinotes resolve <id> [message]
-uinotes resolve 42 "Fixed in v2.1" --project my-app
+uinotes explain <note-id>
+uinotes explain <note-id> --format json
 ```
 
-### `uinotes wontfix`
+### `uinotes resolve` / `uinotes wontfix`
 
-Mark a note as won't fix.
+Mark a note as resolved or won't fix.
 
 ```bash
+uinotes resolve <id> [message]
 uinotes wontfix <id> [message]
-uinotes wontfix 99 "Out of scope for this release"
+```
+
+### `uinotes comment` / `uinotes comments`
+
+Add or list comments on a note.
+
+```bash
+uinotes comment <id> "Comment text"
+uinotes comments <id>
+```
+
+### `uinotes resolve-by-component` / `uinotes resolve-by-selector`
+
+Bulk resolve notes matching a component or selector.
+
+```bash
+uinotes resolve-by-component OldWidget "Replaced with NewWidget"
+uinotes resolve-by-selector ".deprecated" "Removed" --dry-run
+```
+
+### `uinotes changelog`
+
+Generate a changelog from resolved notes.
+
+```bash
+uinotes changelog --since HEAD~5
+uinotes changelog --since v1.2.0 --format conventional
+```
+
+### `uinotes visual-diff`
+
+Capture and compare page screenshots.
+
+```bash
+uinotes visual-diff --project my-app
+uinotes visual-diff --compare --width 1440
+```
+
+### `uinotes batch`
+
+Execute NDJSON batch operations.
+
+```bash
+echo '{"op":"resolve","id":"abc","message":"Fixed"}' | uinotes batch -
+uinotes batch ops.ndjson --dry-run --concurrency 10
+```
+
+### `uinotes schema`
+
+List or print API resource schemas.
+
+```bash
+uinotes schema
+uinotes schema --resource notes
+```
+
+### `uinotes install-skills`
+
+Install Claude Code skill files into `.claude/skills/`.
+
+```bash
+uinotes install-skills
+uinotes install-skills --dir /path/to/project/.claude/skills
+uinotes install-skills --check
+```
+
+### `uinotes doctor`
+
+Check CLI configuration, API connectivity, and version.
+
+```bash
+uinotes doctor
+```
+
+Checks: config file, API URL, API key, API reachability, project binding, skills installed, CLI version.
+
+### `uinotes update`
+
+Check for and install CLI updates.
+
+```bash
+uinotes update
 ```
 
 ## Configuration

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.4",
+  "version": "0.2.6",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],