@upgraide/ui-notes-cli 0.2.0 → 0.2.2

package/README.md

@@ -45,10 +45,12 @@ uinotes config
 
 # Set a value
 uinotes config set apiUrl https://my-api.example.com
-uinotes config set defaultProject my-app
+
+# Bind a project to the current directory
+uinotes set project my-app
 ```
 
-**Config keys:** `apiUrl`, `apiKey`, `defaultProject`
+**Config keys:** `apiUrl`, `apiKey`
 
 ### `uinotes projects`
 
@@ -122,11 +124,19 @@ The CLI looks for config in two places (local takes priority):
 ```json
 {
   "apiUrl": "http://localhost:3000",
-  "apiKey": "your-api-key",
-  "defaultProject": "my-app"
+  "apiKey": "your-api-key"
 }
 ```
 
+### Project Binding
+
+Run `uinotes set project <slug>` to create a `.uinotes` file in the current directory. This binds the project to the directory tree so all commands automatically use it — no `--project` flag needed.
+
+The CLI resolves the project in this order:
+1. `--project` flag (explicit override)
+2. `.uinotes` file in current directory or nearest parent
+3. No project (commands that require one will error)
+
 API keys are redacted when displayed with `uinotes config`.
 
 ## Global Options

package/api.ts

@@ -11,7 +11,7 @@ export async function apiFetch(
     'x-api-key': config.apiKey,
   };
 
-  const targetProject = project || config.defaultProject;
+  const targetProject = project || config.project;
   if (targetProject) {
     headers['x-project'] = targetProject;
   }

package/commands/bulk-resolve.ts

@@ -31,9 +31,9 @@ async function bulkResolve(
   filterValue: string,
   opts: BulkResolveOptions,
 ): Promise<void> {
-  const project = opts.project || config.defaultProject;
+  const project = opts.project || config.project;
   if (!project) {
-    console.error('No project specified. Use --project or set defaultProject in config.');
+    console.error('No project specified. Use --project or run: uinotes set project <slug>');
     process.exit(1);
   }
 

package/commands/config.ts

@@ -1,6 +1,6 @@
 import { getConfig, getConfigPath, setConfigValue } from '../config.js';
 
-const VALID_KEYS = ['apiUrl', 'apiKey', 'defaultProject'];
+const VALID_KEYS = ['apiUrl', 'apiKey'];
 
 function redactKey(value: string): string {
   if (!value || value.length <= 4) return '****';

package/commands/context.ts

@@ -55,7 +55,7 @@ export async function context(config: Config, opts: ContextOptions): Promise<voi
   const output = formatNotesForAI(notes, {
     format: opts.format || 'markdown',
     componentFilter: opts.component,
-    projectName: opts.project || config.defaultProject || 'unknown',
+    projectName: opts.project || config.project || 'unknown',
     resolvedNotes: resolvedMap,
   });
 

package/commands/install-skills.ts

@@ -0,0 +1,58 @@
+import type { Config } from '../config.js';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+interface InstallSkillsOptions {
+  dir?: string;
+  check?: boolean;
+}
+
+const DEFAULT_DIR = '.claude/skills';
+
+export async function installSkills(_config: Config, opts: InstallSkillsOptions): Promise<void> {
+  const targetDir = opts.dir || join(process.cwd(), DEFAULT_DIR);
+  const skillsSourceDir = join(import.meta.dir, '..', 'skills');
+
+  // List available skills
+  let skillFiles: string[];
+  try {
+    skillFiles = readdirSync(skillsSourceDir).filter(f => f.endsWith('.md'));
+  } catch {
+    console.error('Could not read bundled skill files.');
+    process.exit(1);
+  }
+
+  if (skillFiles.length === 0) {
+    console.error('No skill files found in package.');
+    process.exit(1);
+  }
+
+  if (opts.check) {
+    // Check installed vs bundled
+    console.log('Skill status:');
+    for (const file of skillFiles) {
+      const targetPath = join(targetDir, file);
+      if (existsSync(targetPath)) {
+        console.log(`  ${file}: installed`);
+      } else {
+        console.log(`  ${file}: not installed`);
+      }
+    }
+    return;
+  }
+
+  // Install skills
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const file of skillFiles) {
+    const sourcePath = join(skillsSourceDir, file);
+    const targetPath = join(targetDir, file);
+    const content = readFileSync(sourcePath, 'utf-8');
+    writeFileSync(targetPath, content);
+  }
+
+  console.log(`Installed ${skillFiles.length} skills to ${targetDir}/`);
+  for (const file of skillFiles) {
+    console.log(`  ${file}`);
+  }
+}

package/commands/set.ts

@@ -0,0 +1,9 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export function setProject(slug: string): void {
+  const filePath = join(process.cwd(), '.uinotes');
+  writeFileSync(filePath, JSON.stringify({ project: slug }, null, 2) + '\n');
+  console.log(`Bound project "${slug}" to ${process.cwd()}`);
+  console.log(`Created .uinotes — commit this file so your team and AI agents inherit it.`);
+}

package/commands/visual-diff.ts

@@ -37,9 +37,9 @@ async function loadPlaywright() {
 }
 
 export async function visualDiff(config: Config, opts: VisualDiffOptions): Promise<void> {
-  const project = opts.project || config.defaultProject;
+  const project = opts.project || config.project;
   if (!project) {
-    console.error('Error: --project is required (or set defaultProject in config)');
+    console.error('Error: --project is required (or run: uinotes set project <slug>)');
     process.exit(1);
   }
 

package/config.ts

@@ -11,7 +11,7 @@ export interface ResolveConfig {
 export interface Config {
   apiUrl: string;
   apiKey: string;
-  defaultProject?: string;
+  project?: string;
   resolve?: ResolveConfig;
 }
 
@@ -23,11 +23,34 @@ const DEFAULT_CONFIG: Config = {
   apiKey: '',
 };
 
-function readJsonFile(path: string): Config | null {
+function readJsonFile(path: string): Record<string, any> | null {
   if (!existsSync(path)) return null;
   return JSON.parse(readFileSync(path, 'utf-8'));
 }
 
+/**
+ * Walk up the directory tree from cwd looking for a .uinotes file
+ * that binds a project slug to this directory tree.
+ */
+function findDirectoryProject(startDir: string): string | undefined {
+  let dir = startDir;
+  while (true) {
+    const filePath = join(dir, '.uinotes');
+    if (existsSync(filePath)) {
+      try {
+        const content = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (content.project) return content.project;
+      } catch {
+        // Invalid JSON — skip
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return undefined;
+}
+
 export function getConfigPath(): string {
   if (existsSync(LOCAL_PATH)) return LOCAL_PATH;
   return GLOBAL_PATH;
@@ -36,14 +59,22 @@ export function getConfigPath(): string {
 export function getConfig(): Config {
   // Per-repo config takes priority
   const local = readJsonFile(LOCAL_PATH);
-  if (local) return { ...DEFAULT_CONFIG, ...local };
+  const base = local
+    ? { ...DEFAULT_CONFIG, ...local }
+    : (() => {
+        const global = readJsonFile(GLOBAL_PATH);
+        if (global) return { ...DEFAULT_CONFIG, ...global };
+        // Create default global config
+        writeFileSync(GLOBAL_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+        return { ...DEFAULT_CONFIG };
+      })();
 
-  const global = readJsonFile(GLOBAL_PATH);
-  if (global) return { ...DEFAULT_CONFIG, ...global };
+  // Resolve project from .uinotes directory binding (if not already set)
+  if (!base.project) {
+    base.project = findDirectoryProject(process.cwd());
+  }
 
-  // Create default global config
-  writeFileSync(GLOBAL_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
-  return DEFAULT_CONFIG;
+  return base as Config;
 }
 
 export function setConfigValue(key: string, value: string): Config {

package/index.ts

@@ -22,6 +22,7 @@ Commands:
   projects add-url <slug> <pattern>     Add URL pattern to project
   projects remove-url <slug> <pattern>  Remove URL pattern
   projects delete <slug>                Archive a project
+  set project <slug>                    Bind project to current directory
   login                                 Login and create API key
   pull                                  Fetch open notes
   context                               AI-optimized digest of open notes
@@ -36,6 +37,7 @@ Commands:
   visual-diff                           Capture & compare page screenshots
   batch <file|->                        Execute NDJSON batch operations
   schema                                List or print API resource schemas
+  install-skills                        Install Claude Code skill files
   config                                View/edit configuration
 
 Options:
@@ -53,6 +55,8 @@ Options:
   --width <px>      Viewport width for screenshots (default: 1280)
   --full-page       Capture full page height (default: true)
   --since <ref>     Git ref or ISO date for changelog start
+  --dir <path>      Target directory for skill installation
+  --check           Check installed skill versions
   --resource <name> Resource name for schema command
   --concurrency <n> Concurrent batch operations (default: 5)
   --dry-run         Preview batch operations without executing`;
@@ -124,6 +128,23 @@ async function main() {
     return;
   }
 
+  // set command is local-only, no API key needed
+  if (command === 'set') {
+    const sub = positional[1];
+    if (sub === 'project') {
+      const slug = positional[2];
+      if (!slug) {
+        console.error('Usage: uinotes set project <slug>');
+        process.exit(1);
+      }
+      const { setProject } = await import('./commands/set.js');
+      setProject(slug);
+      return;
+    }
+    console.error(`Unknown set subcommand: ${sub}`);
+    process.exit(1);
+  }
+
   // Schema command is local-only, no API key needed
   if (command === 'schema') {
     const { schema } = await import('./commands/schema.js');
@@ -131,13 +152,23 @@ async function main() {
     return;
   }
 
+  // install-skills is local-only, no API key needed
+  if (command === 'install-skills') {
+    const { installSkills } = await import('./commands/install-skills.js');
+    await installSkills(getConfig(), {
+      dir: flags.dir,
+      check: flags.check === 'true',
+    });
+    return;
+  }
+
   const config = getConfig();
   if (!config.apiKey) {
     console.error('No API key configured. Run: uinotes config set apiKey <your-key>');
     process.exit(1);
   }
 
-  const project = flags.project;
+  const project = flags.project || config.project;
 
   switch (command) {
     case 'projects': {

package/package.json

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

package/skills/uinotes-batch.md

@@ -0,0 +1,23 @@
+---
+name: uinotes-batch
+description: Execute multiple note operations in a single call using NDJSON. Use for bulk triage of multiple notes.
+---
+
+# uinotes-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
+
+## Command
+```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.

package/skills/uinotes-changelog.md

@@ -0,0 +1,22 @@
+---
+name: uinotes-changelog
+description: Generate a changelog from resolved UI notes. Use after resolving notes to create release notes or PR descriptions.
+---
+
+# uinotes-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
+
+## Command
+```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`.

package/skills/uinotes-comment.md

@@ -0,0 +1,19 @@
+---
+name: uinotes-comment
+description: Add a comment to a UI note. Use to document progress, ask questions, or provide status updates on notes.
+---
+
+# uinotes-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
+
+## Command
+```bash
+uinotes comment <note-id> "Comment text here"
+uinotes comments <note-id>  # List existing comments
+```

package/skills/uinotes-context.md

@@ -0,0 +1,22 @@
+---
+name: uinotes-context
+description: Fetch AI-optimized context of open UI notes for the current project. Use when asked to check for UI bugs, feedback, or notes.
+---
+
+# uinotes-context
+
+Run `uinotes context` to get a structured digest of all 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
+
+## Command
+```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.

package/skills/uinotes-explain.md

@@ -0,0 +1,21 @@
+---
+name: uinotes-explain
+description: Get full context for a single note including comments, history, and visual diffs. Use when investigating a specific note.
+---
+
+# uinotes-explain
+
+Get fully-hydrated context for a single note in one call.
+
+## 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
+
+## Command
+```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.

package/skills/uinotes-resolve.md

@@ -0,0 +1,26 @@
+---
+name: uinotes-resolve
+description: Mark a UI note as resolved after fixing it. Use after completing a fix for a UI issue.
+---
+
+# uinotes-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
+
+## Commands
+```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.