skillsets 0.1.2 → 0.2.0

package/README.md

@@ -8,6 +8,9 @@ Command-line tool for discovering, installing, and contributing verified Claude
 # Browse available skillsets
 npx skillsets list
 
+# Sort by popularity
+npx skillsets list --sort downloads
+
 # Search by keyword
 npx skillsets search "sdlc"
 
@@ -19,7 +22,7 @@ npx skillsets install @supercollectible/The_Skillset
 
 | Command | Purpose |
 |---------|---------|
-| `list` | Browse all available skillsets |
+| `list` | Browse all skillsets with live star/download counts |
 | `search <query>` | Fuzzy search by name, description, or tags |
 | `install <id>` | Install skillset to current directory |
 | `verify` | Verify installed skillset checksums |
@@ -27,6 +30,25 @@ npx skillsets install @supercollectible/The_Skillset
 | `audit` | Validate skillset before submission |
 | `submit` | Open PR to registry (requires `gh` CLI) |
 
+## Options
+
+### list
+- `-l, --limit <n>` - Limit number of results
+- `-s, --sort <field>` - Sort by: `name`, `stars`, `downloads`
+- `--json` - Output as JSON
+
+### search
+- `-t, --tags <tags...>` - Filter by tags
+- `-l, --limit <n>` - Limit results (default: 10)
+
+### install
+- `-f, --force` - Overwrite existing files
+- `-b, --backup` - Backup existing files before install
+
+## Live Stats
+
+The CLI fetches live star and download counts from the API, so you always see current numbers (not stale build-time data).
+
 ## Development
 
 ```bash

package/dist/commands/install.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { detectConflicts, backupFiles } from '../lib/filesystem.js';
 import { verifyChecksums } from '../lib/checksum.js';
-import { REGISTRY_REPO } from '../lib/constants.js';
+import { REGISTRY_REPO, DOWNLOADS_URL } from '../lib/constants.js';
 export async function install(skillsetId, options) {
     const spinner = ora(`Installing ${skillsetId}...`).start();
     // Check for conflicts
@@ -45,6 +45,12 @@ export async function install(skillsetId, options) {
         process.exit(1);
     }
     spinner.succeed(`Successfully installed ${skillsetId}`);
+    // Track download (non-blocking, silent fail)
+    fetch(DOWNLOADS_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ skillset: skillsetId }),
+    }).catch(() => { });
     // Print next steps
     console.log(chalk.green('\n✓ Installation complete!'));
     console.log(chalk.gray('\nNext steps:'));

package/dist/commands/list.d.ts

@@ -1,6 +1,6 @@
 interface ListOptions {
     limit?: string;
-    sort?: 'name' | 'stars' | 'recent';
+    sort?: 'name' | 'stars' | 'downloads' | 'recent';
     json?: boolean;
 }
 export declare function list(options: ListOptions): Promise<void>;

package/dist/commands/list.js

@@ -1,17 +1,22 @@
 import chalk from 'chalk';
 import ora from 'ora';
-import { fetchSearchIndex } from '../lib/api.js';
+import { fetchSearchIndex, fetchStats, mergeStats } from '../lib/api.js';
 export async function list(options) {
     const spinner = ora('Fetching skillsets...').start();
     try {
-        const index = await fetchSearchIndex();
+        // Fetch index and live stats in parallel
+        const [index, stats] = await Promise.all([fetchSearchIndex(), fetchStats()]);
         spinner.stop();
-        let skillsets = [...index.skillsets];
+        // Merge live stats into skillsets
+        let skillsets = mergeStats(index.skillsets, stats);
         // Sort
         const sortBy = options.sort || 'name';
         if (sortBy === 'stars') {
             skillsets.sort((a, b) => b.stars - a.stars);
         }
+        else if (sortBy === 'downloads') {
+            skillsets.sort((a, b) => (b.downloads ?? 0) - (a.downloads ?? 0));
+        }
         else if (sortBy === 'name') {
             skillsets.sort((a, b) => a.name.localeCompare(b.name));
         }
@@ -38,17 +43,20 @@ export async function list(options) {
         console.log(chalk.gray(padEnd('NAME', 30) +
             padEnd('AUTHOR', 20) +
             padEnd('STARS', 8) +
+            padEnd('INSTALLS', 10) +
             'DESCRIPTION'));
-        console.log(chalk.gray('─'.repeat(100)));
+        console.log(chalk.gray('─'.repeat(110)));
         // Rows
         for (const s of skillsets) {
             const name = padEnd(s.name, 30);
             const author = padEnd(s.author.handle, 20);
             const stars = padEnd(`★ ${s.stars}`, 8);
-            const desc = truncate(s.description, 40);
+            const downloads = padEnd(`↓ ${s.downloads ?? 0}`, 10);
+            const desc = truncate(s.description, 32);
             console.log(chalk.bold(name) +
                 chalk.gray(author) +
                 chalk.yellow(stars) +
+                chalk.gray(downloads) +
                 desc);
         }
         console.log('');

package/dist/commands/search.js

@@ -1,13 +1,15 @@
 import Fuse from 'fuse.js';
 import chalk from 'chalk';
-import { fetchSearchIndex } from '../lib/api.js';
+import { fetchSearchIndex, fetchStats, mergeStats } from '../lib/api.js';
 import { DEFAULT_SEARCH_LIMIT } from '../lib/constants.js';
 export async function search(query, options) {
     console.log(chalk.blue(`Searching for: ${query}`));
-    // Fetch index from CDN
-    const index = await fetchSearchIndex();
+    // Fetch index and live stats in parallel
+    const [index, stats] = await Promise.all([fetchSearchIndex(), fetchStats()]);
+    // Merge live stats into skillsets
+    const skillsetsWithStats = mergeStats(index.skillsets, stats);
     // Filter by tags if provided
-    let filtered = index.skillsets;
+    let filtered = skillsetsWithStats;
     if (options.tags && options.tags.length > 0) {
         filtered = filtered.filter((skillset) => options.tags.some((tag) => skillset.tags.includes(tag)));
     }
@@ -28,7 +30,7 @@ export async function search(query, options) {
         console.log(chalk.bold(item.name));
         console.log(`  ${item.description}`);
         console.log(`  ${chalk.gray(`by ${item.author.handle}`)}`);
-        console.log(`  ${chalk.yellow(`★ ${item.stars}`)} ${chalk.gray(`• v${item.version}`)}`);
+        console.log(`  ${chalk.yellow(`★ ${item.stars}`)} ${chalk.gray(`↓ ${item.downloads ?? 0}`)} ${chalk.gray(`• v${item.version}`)}`);
         console.log(`  ${chalk.cyan(`npx skillsets install ${item.id}`)}`);
         console.log();
     });

package/dist/index.js

@@ -17,7 +17,7 @@ program
     .command('list')
     .description('List all available skillsets')
     .option('-l, --limit <number>', 'Limit results')
-    .option('-s, --sort <field>', 'Sort by: name, stars (default: name)')
+    .option('-s, --sort <field>', 'Sort by: name, stars, downloads (default: name)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     try {

package/dist/lib/api.d.ts

@@ -1,4 +1,4 @@
-import type { SearchIndex, SearchIndexEntry } from '../types/index.js';
+import type { SearchIndex, SearchIndexEntry, StatsResponse } from '../types/index.js';
 /**
  * Fetches the search index from the CDN.
  * Implements 1-hour local cache to reduce network requests.
@@ -8,3 +8,12 @@ export declare function fetchSearchIndex(): Promise<SearchIndex>;
  * Fetches metadata for a specific skillset by ID.
  */
 export declare function fetchSkillsetMetadata(skillsetId: string): Promise<SearchIndexEntry | undefined>;
+/**
+ * Fetches live star and download counts from the API.
+ * Implements 1-minute local cache.
+ */
+export declare function fetchStats(): Promise<StatsResponse>;
+/**
+ * Merges live stats into skillset entries.
+ */
+export declare function mergeStats(skillsets: SearchIndexEntry[], stats: StatsResponse): SearchIndexEntry[];

package/dist/lib/api.js

@@ -1,6 +1,8 @@
-import { SEARCH_INDEX_URL, CACHE_TTL_MS } from './constants.js';
+import { SEARCH_INDEX_URL, STATS_URL, CACHE_TTL_MS } from './constants.js';
 let cachedIndex = null;
 let cacheTime = 0;
+let cachedStats = null;
+let statsCacheTime = 0;
 /**
  * Fetches the search index from the CDN.
  * Implements 1-hour local cache to reduce network requests.
@@ -27,3 +29,40 @@ export async function fetchSkillsetMetadata(skillsetId) {
     const index = await fetchSearchIndex();
     return index.skillsets.find((s) => s.id === skillsetId);
 }
+/**
+ * Fetches live star and download counts from the API.
+ * Implements 1-minute local cache.
+ */
+export async function fetchStats() {
+    const now = Date.now();
+    const STATS_CACHE_TTL_MS = 60 * 1000; // 1 minute for stats
+    // Return cached if still valid
+    if (cachedStats && now - statsCacheTime < STATS_CACHE_TTL_MS) {
+        return cachedStats;
+    }
+    try {
+        const response = await fetch(STATS_URL);
+        if (!response.ok) {
+            // Return empty stats on error, don't break the command
+            return { stars: {}, downloads: {} };
+        }
+        const data = (await response.json());
+        cachedStats = data;
+        statsCacheTime = now;
+        return data;
+    }
+    catch {
+        // Return empty stats on network error
+        return { stars: {}, downloads: {} };
+    }
+}
+/**
+ * Merges live stats into skillset entries.
+ */
+export function mergeStats(skillsets, stats) {
+    return skillsets.map((s) => ({
+        ...s,
+        stars: stats.stars[s.id] ?? s.stars,
+        downloads: stats.downloads[s.id] ?? 0,
+    }));
+}

package/dist/lib/constants.d.ts

@@ -1,5 +1,7 @@
 export declare const CDN_BASE_URL = "https://skillsets.cc";
 export declare const SEARCH_INDEX_URL = "https://skillsets.cc/search-index.json";
+export declare const STATS_URL = "https://skillsets.cc/api/stats/counts";
+export declare const DOWNLOADS_URL = "https://skillsets.cc/api/downloads";
 export declare const REGISTRY_REPO = "skillsets-cc/main";
 export declare const CACHE_TTL_MS: number;
 export declare const DEFAULT_SEARCH_LIMIT = 10;

package/dist/lib/constants.js

@@ -1,5 +1,7 @@
 export const CDN_BASE_URL = 'https://skillsets.cc';
 export const SEARCH_INDEX_URL = `${CDN_BASE_URL}/search-index.json`;
+export const STATS_URL = `${CDN_BASE_URL}/api/stats/counts`;
+export const DOWNLOADS_URL = `${CDN_BASE_URL}/api/downloads`;
 export const REGISTRY_REPO = 'skillsets-cc/main';
 export const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 export const DEFAULT_SEARCH_LIMIT = 10;

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export interface SearchIndexEntry {
         url?: string;
     };
     stars: number;
+    downloads?: number;
     version: string;
     status: 'active' | 'deprecated' | 'archived';
     verification: {
@@ -28,6 +29,10 @@ export interface SearchIndexEntry {
     checksum: string;
     files: Record<string, string>;
 }
+export interface StatsResponse {
+    stars: Record<string, number>;
+    downloads: Record<string, number>;
+}
 export interface Skillset {
     schema_version: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsets",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "CLI tool for discovering and installing verified skillsets",
   "type": "module",
   "bin": {