@nebutra/next-unicorn-skill 1.0.4 → 1.0.5

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://www.npmjs.com/package/@nebutra/next-unicorn-skill"><img src="https://img.shields.io/npm/v/@nebutra/next-unicorn-skill.svg?color=blue" alt="npm version" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript" /></a>
-  <a href="./tests/"><img src="https://img.shields.io/badge/tests-198%20passed-brightgreen.svg" alt="Tests" /></a>
+  <a href="./tests/"><img src="https://img.shields.io/badge/tests-210%20passed-brightgreen.svg" alt="Tests" /></a>
   <a href="./tests/"><img src="https://img.shields.io/badge/properties-29%20verified-purple.svg" alt="Property Tests" /></a>
 </p>
 
@@ -31,9 +31,9 @@
 
 Every codebase accumulates hand-rolled implementations that should be mature libraries. Custom date formatters, DIY loggers, bespoke state machines, ad-hoc i18n — **Vibe Coding debt**.
 
-Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't find code you wrote that *should become* a dependency.
+Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't find code you wrote that *should become* a dependency — or capabilities your project is *missing entirely*.
 
-**Next-Unicorn does both** — and verifies every recommendation against real documentation via [Context7 MCP](https://context7.com).
+**Next-Unicorn does all three** — replacement, gap analysis, and dependency management — verified against real documentation via [Context7 MCP](https://context7.com).
 
 ## Quick Start
 
@@ -61,18 +61,36 @@ npm install @nebutra/next-unicorn-skill
 
 ```typescript
 import { analyze, scanCodebase } from '@nebutra/next-unicorn-skill';
-import type { Recommender } from '@nebutra/next-unicorn-skill';
-
-// The recommender function: AI agent decides which library fits each detection
-const recommender: Recommender = (detection) => {
-  // AI agent uses its knowledge + project context to recommend
-  // Return null to skip a detection (false positive, intentional custom code)
-  return {
-    library: 'zustand',       // dynamically chosen, not hardcoded
-    version: '^5.0.0',        // verified via Context7
-    license: 'MIT',
-  };
-};
+import type { Recommender, GapRecommendation } from '@nebutra/next-unicorn-skill';
+
+// The recommender: AI agent decides which library fits each detection
+const recommender: Recommender = (detection) => ({
+  library: '@lingui/core',
+  version: '^4.0.0',
+  license: 'MIT',
+  rationale: 'Compile-time i18n with near-zero runtime overhead',
+  ecosystem: [
+    { library: '@lingui/macro', version: '^4.0.0', role: 'Tagged templates' },
+    { library: '@lingui/cli', version: '^4.0.0', role: 'CI message extraction' },
+  ],
+  antiPatterns: ['Avoid i18next if bundle size matters — Lingui compiles away'],
+  alternatives: [
+    { library: 'next-intl', when: 'Next.js App Router with server components' },
+  ],
+});
+
+// Gap analysis: capabilities the project should have but doesn't
+const gaps: GapRecommendation[] = [
+  {
+    domain: 'observability',
+    description: 'No structured logging detected',
+    recommendedLibrary: {
+      name: 'pino', version: '^9.0.0', license: 'MIT',
+      rationale: 'Fastest Node.js JSON logger with redaction and child loggers',
+    },
+    priority: 'critical',
+  },
+];
 
 const result = await analyze({
   input: {
@@ -83,27 +101,22 @@ const result = await analyze({
       currentLibraries: { react: '18.2.0', next: '14.1.0' },
     },
     optimizationGoals: ['reduce custom code', 'improve maintainability'],
-    constraints: {
-      licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'],
-    },
+    constraints: { licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'] },
     priorityFocusAreas: ['i18n', 'observability', 'auth-security'],
   },
   context7Client: myContext7Client,
-  recommender,  // AI agent provides library recommendations
-  // Optional Phase 2 clients:
-  vulnClient: myOsvClient,          // vulnerability scanning
-  registryClient: myRegistryClient,  // auto-update
-  platformClient: myGitHubClient,    // PR creation
-  gitOps: myGitOperations,           // PR creation
+  recommender,
+  gaps,
 });
 
 if (result.success) {
   console.log(result.prettyJson);
-  // result.scanResult contains raw detections for further AI analysis
+  // result.scanResult — raw detections + structural findings for AI analysis
+  // result.output.gapAnalysis — Context7-verified gap recommendations
 }
 ```
 
-Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent (Claude Code, Kiro, etc.).
+Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent (Claude Code, Kiro, Cursor, etc.).
 
 ## Features
 
@@ -111,17 +124,19 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 
 | Feature | Description |
 |---------|-------------|
-| **Pattern-based scanning** | Detects hand-rolled code across 68 Vibe Coding Domains (ISO 25010-aligned) |
-| **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't (e.g., no error monitoring, no rate limiting, no event-driven workflows) |
-| **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives — not just "use library X" |
-| **Context7 verification** | Every recommendation verified against real, version-correct documentation |
+| **Pattern-based scanning** | Detects hand-rolled code across 30 domains with 40+ regex patterns (design-system, auth, state-management, etc.) |
+| **Structural analysis** | Detects monorepo architecture gaps: missing token layers, dependency flow violations, hardcoded config values |
+| **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't |
+| **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives |
+| **Context7 verification** | Every recommendation (replacements AND gaps) verified with exponential backoff retry |
 | **7-dimension impact scoring** | Scalability, performance, security, maintainability, feature richness, UX, UI aesthetics |
 | **Phased migration plans** | Low / medium / high risk phases with adapter strategies |
 | **Deletion checklists** | Every file and line range to remove, with estimated lines saved |
 | **UX completeness audit** | A11y, error/empty/loading states, form validation, design system alignment |
+| **Design system support** | Two paths: scaffold from reference repos (Primer, Polaris, Supabase, Dub) or extract from existing code |
 | **Monorepo support** | Detects npm, pip, cargo, go workspaces independently |
 
-### Dependency Management (v2.0)
+### Dependency Management
 
 | Feature | Description |
 |---------|-------------|
@@ -133,13 +148,14 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 ## How It Works
 
 ```
-Input ─> Validator ─> Scanner ─> Recommender (AI Agent) ─> Context7 Verifier
+Input ─> Validator ─> Scanner + Structure Analyzer
+  ─> Gap Analysis (AI Agent) ─> Recommender (AI Agent) ─> Context7 Verifier
   ─> Impact Scorer ─> Conflict Detection ─> Vuln Scanner ─> License Filter
   ─> Migration Planner ─> UX Auditor ─> Auto-Updater
   ─> Serializer ─> PR Creator ─> Output
 ```
 
-**Key architecture**: The scanner detects WHAT is hand-rolled; the **Recommender** (AI agent or caller) decides WHAT library to use. No library recommendations are hardcoded — they are provided dynamically based on project context, ecosystem knowledge, and Context7 verification.
+**Key architecture**: The scanner detects WHAT is hand-rolled; the structure analyzer detects architectural gaps; the **Recommender** (AI agent or caller) decides WHAT to use. No library recommendations are hardcoded — they are provided dynamically based on project context, ecosystem knowledge, and Context7 verification.
 
 Each stage is a pure function with structured I/O. All external dependencies (Context7, OSV, npm registry, GitHub API) are **injected via interfaces** for testability.
 
@@ -166,14 +182,14 @@ function t(key, locale) {
 <td>
 
 ```tsx
-// next-intl — Context7 verified, MIT
-// Impact: 9.2/10 composite
-// Migration risk: low | Effort: 8h
-import { useTranslations } from 'next-intl';
+// @lingui/core — Context7 verified, MIT
+// Ecosystem: @lingui/macro + @lingui/cli
+// Impact: 9.2/10 | Risk: low | Effort: 8h
+import { useLingui } from '@lingui/react';
 
 export default function Page() {
-  const t = useTranslations('common');
-  return <h1>{t('greeting')}</h1>;
+  const { t } = useLingui();
+  return <h1>{t`greeting`}</h1>;
 }
 ```
 
@@ -199,8 +215,8 @@ function logRequest(req) {
 
 ```typescript
 // pino — Context7 verified, MIT
-// Impact: 9.0/10 composite
-// Migration risk: low | Effort: 4h
+// Gap analysis: "No structured logging detected"
+// Priority: critical
 import pino from 'pino';
 const logger = pino({
   level: 'info',
@@ -217,11 +233,15 @@ const logger = pino({
 | Feature | Next-Unicorn | Snyk | Dependabot | Renovate |
 |---------|:---:|:---:|:---:|:---:|
 | Finds hand-rolled code to replace | **Yes** | | | |
+| Identifies missing capabilities (gaps) | **Yes** | | | |
+| Structural architecture analysis | **Yes** | | | |
 | Recommends new libraries | **Yes** | | | |
+| Ecosystem-level solutions | **Yes** | | | |
 | 7-dimension impact scoring | **Yes** | | | |
 | Context7 doc verification | **Yes** | | | |
 | Phased migration plans | **Yes** | | | |
 | UX completeness audit | **Yes** | | | |
+| Design system scaffold/extraction | **Yes** | | | |
 | Deletion checklists | **Yes** | | | |
 | Vulnerability scanning | **Yes** | Yes | Yes | |
 | Scans *recommended* libs for vulns | **Yes** | | | |
@@ -249,14 +269,18 @@ const logger = pino({
 
 ### `scanCodebase(input): Promise<ScanResult>`
 
-Standalone scanner — returns detections and workspace info without recommendations. AI agents can call this first, then provide recommendations via the `Recommender` callback.
+Standalone scanner — returns detections, workspace info, and structural findings (design system layer analysis, dependency flow violations). AI agents can call this first, then provide recommendations via the `Recommender` callback.
+
+### `analyzeStructure(repoPath, workspaces): StructuralAnalysis`
+
+Standalone structure analyzer — detects missing design system layers, dependency flow violations, hardcoded config values, and missing shared presets in monorepos.
 
 ### Output Structure
 
 ```jsonc
 {
   "recommendedChanges": [...],     // Replacement recommendations with impact scores
-  "gapAnalysis": [...],            // (optional) Missing capabilities with prioritized recs
+  "gapAnalysis": [...],            // (optional) Context7-verified gap recommendations
   "filesToDelete": [...],          // Files to remove after migration
   "linesSavedEstimate": 1250,      // Total lines saved
   "uxAudit": [...],                // UX completeness (8 categories)
@@ -272,16 +296,16 @@ Standalone scanner — returns detections and workspace info without recommendat
 
 ## Vibe Coding Domains
 
-68 domains across 11 categories, aligned with ISO/IEC 25010:
+68 domains across 11 categories, aligned with ISO/IEC 25010. 30 domains have scanner patterns; the rest are covered by AI agent gap analysis.
 
 | Category | Count | Examples |
 |----------|:-----:|---------|
-| UX / Design | 14 | `ux-completeness`, `a11y-accessibility`, `forms-ux`, `design-system` |
+| UX / Design | 14 | `design-system`, `a11y-accessibility`, `forms-ux`, `empty-loading-error-states` |
 | SEO / i18n | 5 | `seo`, `i18n`, `content-marketing` |
 | Growth / Data | 7 | `analytics-tracking`, `ab-testing-experimentation` |
-| Frontend Arch | 8 | `state-management`, `data-fetching-caching`, `agent-architecture` |
-| Backend / Platform | 8 | `database-orm-migrations`, `jobs-queue-scheduler`, `feature-flags-config` |
-| Security | 5 | `auth-security`, `permissions-rbac-ux`, `fraud-abuse-prevention` |
+| Frontend Arch | 8 | `state-management`, `data-fetching-caching`, `realtime-collaboration` |
+| Backend / Platform | 8 | `database-orm-migrations`, `caching-rate-limit`, `feature-flags-config` |
+| Security | 5 | `auth-security`, `security-hardening`, `fraud-abuse-prevention` |
 | Observability | 4 | `logging-tracing-metrics`, `error-monitoring` |
 | Delivery / DevEx | 6 | `testing-strategy`, `ci-cd-release`, `dependency-management` |
 | Performance | 3 | `performance-web-vitals`, `cost-optimization` |
@@ -293,7 +317,7 @@ Standalone scanner — returns detections and workspace info without recommendat
 ## Testing
 
 ```bash
-pnpm test          # 198 tests (vitest + fast-check)
+pnpm test          # 210 tests (vitest + fast-check)
 pnpm typecheck     # TypeScript strict mode
 pnpm build         # Compile to dist/
 ```
@@ -330,6 +354,13 @@ pnpm build         # Compile to dist/
 | [`update-plan.md`](./templates/update-plan.md) | Dependency update plan |
 | [`prd-template.md`](./templates/prd-template.md) | PRD for stakeholder presentation |
 
+## References
+
+| Reference | Purpose |
+|-----------|---------|
+| [`design-system-sources.md`](./references/design-system-sources.md) | 25+ curated design system repos for scaffolding (Primer, Polaris, Dub, Supabase, etc.) |
+| [`design-system-extraction.md`](./references/design-system-extraction.md) | Workflow for extracting a design system from existing code (6 principles, 5 phases) |
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
@@ -340,8 +371,8 @@ Releases are automated via GitHub Actions:
 
 ```bash
 # Tag a new version
-git tag v2.0.0
-git push origin v2.0.0
+git tag v1.0.5
+git push origin v1.0.5
 # → CI runs tests → creates GitHub Release → publishes to npmjs + GitHub Packages
 ```
 

package/dist/index.d.ts

@@ -18,7 +18,7 @@ import type { VulnerabilityClient } from './security/osv-client.js';
 import type { RegistryClient } from './updater/registry-client.js';
 import type { PlatformClient } from './pr-creator/platform-client.js';
 import type { GitOperations } from './pr-creator/git-operations.js';
-export declare const VERSION = "1.0.4";
+export declare const VERSION = "1.0.5";
 /**
  * A library recommendation provided by the AI agent (or caller).
  * The scanner detects WHAT is hand-rolled; the recommender decides WHAT to use.

package/dist/index.js

@@ -29,7 +29,7 @@ import { executePRPlans } from './pr-creator/pr-executor.js';
 // ---------------------------------------------------------------------------
 // Version
 // ---------------------------------------------------------------------------
-export const VERSION = '1.0.4';
+export const VERSION = '1.0.5';
 export { analyzeStructure } from './analyzer/structure-analyzer.js';
 export { scanCodebase } from './analyzer/scanner.js';
 export { getPatternCatalog } from './analyzer/pattern-catalog.js';

package/dist/verifier/context7.d.ts

@@ -11,11 +11,27 @@ export interface VerificationResult {
 /**
  * Client interface for Context7 MCP integration.
  * Designed for easy mocking in tests — the real implementation calls
- * Context7 MCP tools (`resolve-library-id` and `get-library-docs`).
+ * Context7 MCP tools (`resolve-library-id` and `query-docs`).
+ *
+ * Per Context7 best practices:
+ * - resolveLibraryId accepts both query (for ranking) and libraryName
+ * - getLibraryDocs accepts libraryId and query
+ * - Implementations should handle 202 (processing), 301 (redirect), 429 (rate limit)
  */
 export interface Context7Client {
-    resolveLibraryId(libraryName: string): Promise<string | null>;
-    getLibraryDocs(libraryId: string, useCase: string): Promise<{
+    /**
+     * Resolve a library name to a Context7-compatible library ID.
+     * @param libraryName — the library to search for
+     * @param query — the user's question/task (used by Context7 to rank results)
+     * @returns library ID string, or null if not found
+     */
+    resolveLibraryId(libraryName: string, query?: string): Promise<string | null>;
+    /**
+     * Fetch documentation for a library by its Context7 ID.
+     * @param libraryId — Context7-compatible library ID (e.g., "/vercel/next.js")
+     * @param query — the question/task to get relevant docs for
+     */
+    getLibraryDocs(libraryId: string, query: string): Promise<{
         url: string;
         version: string;
     } | null>;
@@ -25,14 +41,14 @@ export interface Context7Client {
  *
  * Flow:
  * 1. Call `resolveLibraryId` to get the canonical library ID.
- *    - If it returns `null` → status "unverified" (library not found).
- *    - If it throws → retry once. If still failing → status "unavailable".
+ *    - If it returns `null` → status "unverified" (library not found / 404).
+ *    - If it throws → retry with exponential backoff (handles 429, 202, 5xx).
+ *    - After max retries → status "unavailable".
  * 2. Call `getLibraryDocs` with the library ID and use case.
  *    - If it returns docs → status "verified" with URL and version.
  *    - If it returns `null` → status "unverified" (use case not confirmed).
- *    - If it throws → retry once. If still failing → status "unavailable".
- *
- * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 9.5
+ *    - If it throws → retry with exponential backoff.
+ *    - After max retries → status "unavailable".
  */
 export declare function verifyRecommendation(client: Context7Client, libraryName: string, useCase: string): Promise<VerificationResult>;
 /**
@@ -52,8 +68,6 @@ export interface VerificationItem {
  *
  * Processes each item independently — a failure for one library does
  * not affect others. Returns a Map keyed by detection index.
- *
- * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 9.5
  */
 export declare function verifyAllRecommendations(client: Context7Client, items: Array<VerificationItem | null>): Promise<Map<number, VerificationResult>>;
 //# sourceMappingURL=context7.d.ts.map

package/dist/verifier/context7.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context7.d.ts","sourceRoot":"","sources":["../../src/verifier/context7.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACrD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC,CA0D7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,GACpC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAe1C"}
+{"version":3,"file":"context7.d.ts","sourceRoot":"","sources":["../../src/verifier/context7.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9E;;;;OAIG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACrD;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC,CAoD7B;AAuCD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,GACpC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAe1C"}

package/dist/verifier/context7.js

@@ -1,38 +1,47 @@
-// No longer depends on Detection — recommendations come from the AI agent
 // ---------------------------------------------------------------------------
-// Single recommendation verification (with retry-once logic)
+// Public interfaces
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Retry configuration
+// ---------------------------------------------------------------------------
+/** Maximum retry attempts (Context7 best practice: 3) */
+const MAX_RETRIES = 3;
+/** Base delay for exponential backoff in ms */
+const BASE_DELAY_MS = 1000;
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Single recommendation verification (with exponential backoff retry)
 // ---------------------------------------------------------------------------
 /**
  * Verify a single library recommendation against Context7 MCP.
  *
  * Flow:
  * 1. Call `resolveLibraryId` to get the canonical library ID.
- *    - If it returns `null` → status "unverified" (library not found).
- *    - If it throws → retry once. If still failing → status "unavailable".
+ *    - If it returns `null` → status "unverified" (library not found / 404).
+ *    - If it throws → retry with exponential backoff (handles 429, 202, 5xx).
+ *    - After max retries → status "unavailable".
  * 2. Call `getLibraryDocs` with the library ID and use case.
  *    - If it returns docs → status "verified" with URL and version.
  *    - If it returns `null` → status "unverified" (use case not confirmed).
- *    - If it throws → retry once. If still failing → status "unavailable".
- *
- * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 9.5
+ *    - If it throws → retry with exponential backoff.
+ *    - After max retries → status "unavailable".
  */
 export async function verifyRecommendation(client, libraryName, useCase) {
-    // Step 1: Resolve library ID (with retry-once on failure)
+    // Step 1: Resolve library ID (with exponential backoff)
     let libraryId;
     try {
-        libraryId = await client.resolveLibraryId(libraryName);
+        libraryId = await retryWithBackoff(() => client.resolveLibraryId(libraryName, useCase));
     }
     catch {
-        // Retry once
-        try {
-            libraryId = await client.resolveLibraryId(libraryName);
-        }
-        catch {
-            return {
-                status: 'unavailable',
-                note: `Context7 service error resolving library "${libraryName}" after retry`,
-            };
-        }
+        return {
+            status: 'unavailable',
+            note: `Context7 service error resolving library "${libraryName}" after ${MAX_RETRIES} retries`,
+        };
     }
     // Library not found in Context7
     if (libraryId === null) {
@@ -41,23 +50,17 @@ export async function verifyRecommendation(client, libraryName, useCase) {
             note: `Library "${libraryName}" not found in Context7`,
         };
     }
-    // Step 2: Get library docs (with retry-once on failure)
+    // Step 2: Get library docs (with exponential backoff)
     let docs;
     try {
-        docs = await client.getLibraryDocs(libraryId, useCase);
+        docs = await retryWithBackoff(() => client.getLibraryDocs(libraryId, useCase));
     }
     catch {
-        // Retry once
-        try {
-            docs = await client.getLibraryDocs(libraryId, useCase);
-        }
-        catch {
-            return {
-                status: 'unavailable',
-                libraryId,
-                note: `Context7 service error fetching docs for "${libraryName}" after retry`,
-            };
-        }
+        return {
+            status: 'unavailable',
+            libraryId,
+            note: `Context7 service error fetching docs for "${libraryName}" after ${MAX_RETRIES} retries`,
+        };
     }
     // Use case not confirmed by documentation
     if (docs === null) {
@@ -75,6 +78,34 @@ export async function verifyRecommendation(client, libraryName, useCase) {
         version: docs.version,
     };
 }
+// ---------------------------------------------------------------------------
+// Retry with exponential backoff
+// ---------------------------------------------------------------------------
+/**
+ * Retry a function with exponential backoff.
+ * Delay: BASE_DELAY_MS * 2^attempt (1s, 2s, 4s for 3 attempts).
+ *
+ * Per Context7 best practices:
+ * - 429 (rate limit): exponential backoff
+ * - 202 (processing): wait and retry
+ * - 5xx (server error): retry with backoff
+ */
+async function retryWithBackoff(fn) {
+    let lastError;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < MAX_RETRIES - 1) {
+                const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
 /**
  * Verify all library recommendations provided by the AI agent (or caller).
  *
@@ -83,8 +114,6 @@ export async function verifyRecommendation(client, libraryName, useCase) {
  *
  * Processes each item independently — a failure for one library does
  * not affect others. Returns a Map keyed by detection index.
- *
- * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 9.5
  */
 export async function verifyAllRecommendations(client, items) {
     const results = new Map();

package/dist/verifier/context7.js.map

@@ -1 +1 @@
-{"version":3,"file":"context7.js","sourceRoot":"","sources":["../../src/verifier/context7.ts"],"names":[],"mappings":"AAAA,0EAA0E;AA8B1E,8EAA8E;AAC9E,6DAA6D;AAC7D,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAsB,EACtB,WAAmB,EACnB,OAAe;IAEf,0DAA0D;IAC1D,IAAI,SAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,aAAa;QACb,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;gBACL,MAAM,EAAE,aAAa;gBACrB,IAAI,EAAE,6CAA6C,WAAW,eAAe;aAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,YAAY,WAAW,yBAAyB;SACvD,CAAC;IACJ,CAAC;IAED,wDAAwD;IACxD,IAAI,IAA6C,CAAC;IAClD,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,aAAa;QACb,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;gBACL,MAAM,EAAE,aAAa;gBACrB,SAAS;gBACT,IAAI,EAAE,6CAA6C,WAAW,eAAe;aAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,SAAS;YACT,IAAI,EAAE,sBAAsB,WAAW,gCAAgC,OAAO,GAAG;SAClF,CAAC;IACJ,CAAC;IAED,iBAAiB;IACjB,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,SAAS;QACT,gBAAgB,EAAE,IAAI,CAAC,GAAG;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAsB,EACtB,KAAqC;IAErC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,MAAM,GAAG,MAAM,oBAAoB,CACvC,MAAM,EACN,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,OAAO,CACb,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"context7.js","sourceRoot":"","sources":["../../src/verifier/context7.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/next-unicorn-skill",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Stop Vibe Coding debt: audit your codebase, replace reinvented wheels with unicorn-grade libraries, scan vulnerabilities, auto-update deps, and auto-create PRs — all verified via Context7 MCP.",
   "type": "module",
   "main": "dist/index.js",