fix(#152): harden cli - limit validation, error isolation, stale metadata

Author: vildanbina

README.md

@@ -1,30 +1,52 @@
 # Yavy CLI
 
-Generate AI skills from your indexed documentation on [Yavy](https://yavy.dev).
+Search and manage your AI-ready documentation on [Yavy](https://yavy.dev).
 
 ## Installation
 
 ```bash
 npm install -g @yavydev/cli
 ```
 
-Requires Node.js >= 18.
+Requires Node.js >= 20.
 
 ## Quick Start
 
 ```bash
-# Authenticate with your Yavy account
+# Interactive setup: authenticate, select projects, configure AI tools
+yavy init
+
+# Or authenticate manually
 yavy login
 
+# Search your indexed documentation
+yavy search "how do I get started?"
+
 # List your projects
 yavy projects
-
-# Generate a skill for a project
-yavy generate my-org/my-project
 ```
 
 ## Commands
 
+### `yavy init`
+
+Interactive setup wizard that authenticates, selects projects, and configures your AI tools (skills + MCP config) in one step.
+
+| Flag            | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| `--tool <name>` | Configure a specific tool only                          |
+| `--yes`         | Non-interactive mode: all detected tools + all projects |
+
+### `yavy search <query>`
+
+Search your indexed documentation directly from the terminal.
+
+| Flag                      | Description                        |
+| ------------------------- | ---------------------------------- |
+| `--project <org/project>` | Scope search to a specific project |
+| `--limit <number>`        | Maximum results (1-20, default 10) |
+| `--json`                  | Output as JSON                     |
+
 ### `yavy login`
 
 Opens your browser to authenticate with your Yavy account using OAuth (PKCE). Credentials are stored in `~/.yavy/credentials.json`.
@@ -57,8 +79,8 @@ By default, skills are saved to `.claude/skills/<project>/` in the current direc
 ## How It Works
 
 1. Yavy indexes your documentation sources (websites, GitHub repos, Confluence, Notion)
-2. The CLI calls the Yavy API to download a skill using the indexed content
-3. The skill file is saved locally for your AI coding tools to discover
+2. The CLI calls the Yavy API to search or download skills using the indexed content
+3. Skills and MCP configs are saved locally for your AI coding tools to discover
 4. AI coding assistants automatically activate the skill when working with relevant code
 
 ## Configuration
@@ -71,7 +93,7 @@ By default, skills are saved to `.claude/skills/<project>/` in the current direc
 ## Related
 
 - [Yavy Claude Code Plugin](https://github.com/yavydev/claude-code) — Claude Code plugin with interactive setup
-- [Yavy](https://yavy.dev) — Index documentation, generate AI skills
+- [Yavy](https://yavy.dev) — Index documentation, search with AI
 
 ## License
 

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@yavydev/cli",
     "version": "0.1.0",
-    "description": "Generate AI skills from your indexed documentation on Yavy",
+    "description": "Search and manage your AI-ready documentation on Yavy",
     "type": "module",
     "bin": {
         "yavy": "./bin/yavy.js"
@@ -13,8 +13,8 @@
         "typecheck": "tsc --noEmit",
         "test": "vitest run",
         "test:watch": "vitest",
-        "format": "prettier --write \"src/**/*.{ts,js}\" \"*.{json,md}\"",
-        "format:check": "prettier --check \"src/**/*.{ts,js}\" \"*.{json,md}\""
+        "format": "prettier --write \"src/**/*.{ts,js}\" \"tests/**/*.{ts,js}\" \"*.{json,md}\"",
+        "format:check": "prettier --check \"src/**/*.{ts,js}\" \"tests/**/*.{ts,js}\" \"*.{json,md}\""
     },
     "keywords": [
         "yavy",

src/commands/init.ts

@@ -3,8 +3,8 @@ import chalk from 'chalk';
 import { Command } from 'commander';
 import { type ApiProject, YavyApiClient } from '@/api/client';
 import { getAccessToken } from '@/auth/store';
-import { error } from '@/utils';
-import { configureTool } from '@/commands/init/configure-tool';
+import { error, warn } from '@/utils';
+import { configureTool, type ConfigureResult } from '@/commands/init/configure-tool';
 import { resolveToolFromFlag, scanForTools } from '@/commands/init/scan-tools';
 import { AiTool, TOOL_CONFIGS, type InitOptions } from '@/commands/init/types';
 
@@ -53,7 +53,14 @@ async function runInit(options: InitOptions): Promise<void> {
     const s = p.spinner();
     s.start('Configuring tools...');
 
-    const results = selectedTools.map((tool) => configureTool(tool, selectedProjects, process.cwd()));
+    const results: ConfigureResult[] = [];
+    for (const tool of selectedTools) {
+        try {
+            results.push(configureTool(tool, selectedProjects, process.cwd()));
+        } catch (err) {
+            warn(`Failed to configure ${TOOL_CONFIGS[tool].name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
 
     s.stop('Tools configured.');
 

src/commands/init/configure-tool.ts

@@ -4,6 +4,7 @@ import type { ApiProject } from '@/api/client';
 import { YAVY_BASE_URL } from '@/config';
 import { generateProjectContent, generateSkillContent, slugify } from '@/commands/init/generate-skill';
 import { type AiTool, TOOL_CONFIGS } from '@/commands/init/types';
+import { warn } from '@/utils';
 
 export interface ConfigureResult {
     tool: AiTool;
@@ -50,8 +51,8 @@ function buildMcpUrl(projects: ApiProject[]): string {
     const orgSlugs = [...new Set(projects.map((proj) => proj.organization.slug))];
 
     if (orgSlugs.length > 1) {
-        console.warn(
-            `Warning: Projects span multiple organizations (${orgSlugs.join(', ')}). ` +
+        warn(
+            `Projects span multiple organizations (${orgSlugs.join(', ')}). ` +
                 `MCP will be configured for "${orgSlugs[0]}" only. Run yavy init per organization for full coverage.`,
         );
     }

src/commands/search.ts

@@ -13,6 +13,12 @@ export function searchCommand(): Command {
         .option('--json', 'Output as JSON')
         .action(async (query: string, options: { project?: string; limit: string; json?: boolean }) => {
             const limit = parseInt(options.limit, 10);
+
+            if (isNaN(limit) || limit < 1 || limit > 20) {
+                error('--limit must be a number between 1 and 20');
+                process.exit(1);
+            }
+
             const spinner = options.json ? null : ora('Searching...').start();
 
             try {

src/config.ts

@@ -1,5 +1,5 @@
 export const YAVY_BASE_URL = process.env.YAVY_BASE_URL ?? 'https://yavy.dev';
 export const YAVY_CLIENT_ID = process.env.YAVY_CLIENT_ID ?? '01965e6a-0000-7000-8000-000000000001';
-export const YAVY_USER_AGENT = `@yavydev/cli`;
+export const YAVY_USER_AGENT = `@yavydev/cli/${process.env.npm_package_version ?? 'unknown'}`;
 export const REQUEST_TIMEOUT_MS = 30_000;
 export const MAX_RETRIES = 3;

tests/commands/init/configure-tool.test.ts

@@ -177,7 +177,7 @@ describe('configureTool', () => {
     });
 
     it('warns when projects span multiple organizations', () => {
-        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const stderrSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
         const projects = [
             makeProject({ organization: { name: 'Org A', slug: 'org-a' } }),
@@ -186,9 +186,9 @@ describe('configureTool', () => {
 
         configureTool(AiTool.Cursor, projects, '/project');
 
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('multiple organizations'));
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('org-a'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('multiple organizations'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('org-a'));
 
-        warnSpy.mockRestore();
+        stderrSpy.mockRestore();
     });
 });

tsup.config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'tsup';
 export default defineConfig({
     entry: ['src/index.ts'],
     format: ['esm'],
-    target: 'node18',
+    target: 'node20',
     clean: true,
     dts: true,
     sourcemap: true,