claudepluginhub 0.4.2 → 0.6.0

package/README.md

@@ -42,10 +42,18 @@ npx claudepluginhub list                List (u/ collections only)
 npx claudepluginhub remove <identifier> Remove
 ```
 
+## Examples
+
+```bash
+# Install a specific plugin from a marketplace repo
+npx claudepluginhub vercel/next.js --plugin cache-components
+```
+
 ## Options
 
 | Option | Description |
 |--------|-------------|
+| `--plugin <name>` | Install a specific plugin from a marketplace repo |
 | `--yes, -y` | Skip prompts (install all, project scope) |
 | `--scope <scope>` | Set scope: `user`, `project` (default), `local` |
 | `-h, --help` | Show help |

package/dist/args.d.ts

@@ -0,0 +1,10 @@
+import type { Scope } from './prompts.js';
+export interface ParsedArgs {
+    command: string;
+    identifier: string | null;
+    plugin: string | null;
+    yes: boolean;
+    scope: Scope | null;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function validatePlugin(args: ParsedArgs): void;

package/dist/args.js

@@ -0,0 +1,62 @@
+import { VALID_NAME_RE, isOwnerRepo } from './validation.js';
+import { printError } from './output.js';
+const VALID_SCOPES = ['user', 'project', 'local'];
+export function parseArgs(argv) {
+    const yes = argv.includes('--yes') || argv.includes('-y');
+    let scope = null;
+    let plugin = null;
+    const scopeIdx = argv.indexOf('--scope');
+    if (scopeIdx !== -1) {
+        const val = argv[scopeIdx + 1];
+        if (!val || val.startsWith('-')) {
+            printError('Missing value for --scope. Must be: user, project, or local');
+            process.exit(1);
+        }
+        if (!VALID_SCOPES.includes(val)) {
+            printError(`Invalid scope "${val}". Must be: user, project, or local`);
+            process.exit(1);
+        }
+        scope = val;
+    }
+    const pluginIdx = argv.indexOf('--plugin');
+    if (pluginIdx !== -1) {
+        const val = argv[pluginIdx + 1];
+        if (!val || val.startsWith('-')) {
+            printError('Missing value for --plugin');
+            process.exit(1);
+        }
+        if (!VALID_NAME_RE.test(val)) {
+            printError(`Invalid plugin name "${val}". Must match [a-zA-Z0-9_.-]+`);
+            process.exit(1);
+        }
+        plugin = val;
+    }
+    // Filter out flags and their values
+    const positional = argv.filter((a, i) => !a.startsWith('-') &&
+        (i === 0 || (argv[i - 1] !== '--scope' && argv[i - 1] !== '--plugin')));
+    const first = positional[0] ?? null;
+    const second = positional[1] ?? null;
+    // Route commands
+    if (first === 'list')
+        return { command: 'list', identifier: null, plugin, yes, scope };
+    if (first === 'update')
+        return { command: 'update', identifier: second, plugin, yes, scope };
+    if (first === 'remove')
+        return { command: 'remove', identifier: second, plugin, yes, scope };
+    if (first === 'add')
+        return { command: 'add', identifier: second, plugin, yes, scope };
+    // Default: treat first positional as identifier for install
+    return { command: 'add', identifier: first, plugin, yes, scope };
+}
+export function validatePlugin(args) {
+    if (!args.plugin)
+        return;
+    if (args.command !== 'add') {
+        printError('--plugin is only valid for install commands');
+        process.exit(1);
+    }
+    if (!args.identifier || !isOwnerRepo(args.identifier)) {
+        printError('--plugin is only valid with owner/repo identifiers');
+        process.exit(1);
+    }
+}

package/dist/detect.d.ts

@@ -1,5 +1,6 @@
 import type { TreeEntry } from './github.js';
-export declare function isOwnerRepo(identifier: string): boolean;
+import { isOwnerRepo } from './validation.js';
+export { isOwnerRepo };
 export interface MarketplaceDetection {
     kind: 'marketplace';
     manifest: {

package/dist/detect.js

@@ -1,17 +1,8 @@
 import { fetchDefaultBranch, fetchTree, downloadFile } from './github.js';
 import { printError } from './output.js';
+import { VALID_NAME_RE, isOwnerRepo } from './validation.js';
 import { sanitizeName } from './wrapper.js';
-const OWNER_REPO_RE = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
-const VALID_NAME_RE = /^[a-zA-Z0-9_.-]+$/;
-export function isOwnerRepo(identifier) {
-    if (!OWNER_REPO_RE.test(identifier))
-        return false;
-    const [owner, repo] = identifier.split('/');
-    // Reject segments that are purely dots (e.g. "..", ".")
-    if (/^\.+$/.test(owner) || /^\.+$/.test(repo))
-        return false;
-    return true;
-}
+export { isOwnerRepo };
 const COMPONENT_PATTERNS = [
     /^commands\/.*\.md$/,
     /^agents\/.*\.md$/,
@@ -95,7 +86,8 @@ export async function detectRepo(ownerRepo) {
             const source = rawSource &&
                 typeof rawSource === 'object' &&
                 typeof rawSource.source === 'string' &&
-                typeof rawSource.repo === 'string'
+                typeof rawSource.repo === 'string' &&
+                isOwnerRepo(rawSource.repo)
                 ? rawSource
                 : { source: 'github', repo: ownerRepo };
             validPlugins.push({
@@ -136,7 +128,7 @@ export async function detectRepo(ownerRepo) {
             printError(`plugin.json has an invalid name: "${pluginJson.name}". Must match [a-zA-Z0-9_.-]+`);
             process.exit(1);
         }
-        const strict = pluginJson.strict !== false;
+        const strict = pluginJson.strict === false ? false : true;
         return { kind: 'plugin', name: pluginJson.name, strict };
     }
     // Plugin without manifest — check for component files at root

package/dist/download.js

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { fetchDefaultBranch, fetchTree, downloadFile, findTreeSha, findBlobSha, listFilesUnder, } from './github.js';
-import { printError } from './output.js';
+import { printError, printProgress } from './output.js';
 function getBaseDir(scope) {
     if (scope === 'user') {
         return join(homedir(), '.claude');
@@ -63,18 +63,26 @@ export async function downloadSkill(component, scope) {
         printError(`Skipping unsafe skill name: ${componentName}`);
         return null;
     }
-    for (const file of files) {
-        const relativePath = file.path.slice(dirPath.length + 1); // remove dir prefix + /
-        const destPath = join(installDir, relativePath);
-        if (!isSafePath(destPath, installDir)) {
-            printError(`Skipping unsafe path: ${file.path}`);
-            continue;
-        }
-        const content = await downloadFile(source, branch, file.path);
-        if (content === null)
+    printProgress(`${componentName} (skill) — downloading ${files.length} file(s)...`);
+    const BATCH_SIZE = 5;
+    for (let i = 0; i < files.length; i += BATCH_SIZE) {
+        const batch = files.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(batch.map(async (file) => {
+            const relativePath = file.path.slice(dirPath.length + 1);
+            const destPath = join(installDir, relativePath);
+            if (!isSafePath(destPath, installDir)) {
+                printError(`Skipping unsafe path: ${file.path}`);
+                return true;
+            }
+            const content = await downloadFile(source, branch, file.path);
+            if (content === null)
+                return false;
+            ensureDir(destPath);
+            writeFileSync(destPath, content);
+            return true;
+        }));
+        if (results.includes(false))
             return null;
-        ensureDir(destPath);
-        writeFileSync(destPath, content);
     }
     const hash = findTreeSha(tree, dirPath) ?? 'unknown';
     return {

package/dist/github-install.d.ts

@@ -1,3 +1,3 @@
 import type { Scope } from './prompts.js';
-export declare function runGithubInstall(ownerRepo: string, yes: boolean, scopeOverride: Scope | null): Promise<void>;
+export declare function runGithubInstall(ownerRepo: string, yes: boolean, scopeOverride: Scope | null, pluginName?: string | null): Promise<void>;
 export declare function runGithubRemove(ownerRepo: string, scopeOverride: Scope | null): Promise<void>;

package/dist/github-install.js

@@ -3,7 +3,7 @@ import { detectRepo } from './detect.js';
 import { checkClaudeCli, claudeMarketplaceAdd, claudePluginInstall, claudePluginUninstall, claudeMarketplaceRemove, } from './native.js';
 import { writeWrapperMarketplace, readWrapperMeta, findWrapperScopes, removeWrapperDir, getWrapperDir, } from './wrapper.js';
 import { print, printStep, printSuccess, printFail, printError, printWarning, BOLD, RESET, DIM, GREEN, YELLOW, } from './output.js';
-export async function runGithubInstall(ownerRepo, yes, scopeOverride) {
+export async function runGithubInstall(ownerRepo, yes, scopeOverride, pluginName = null) {
     if (!checkClaudeCli())
         process.exit(1);
     printStep('Detecting repository type...');
@@ -12,23 +12,36 @@ export async function runGithubInstall(ownerRepo, yes, scopeOverride) {
         printError(`No plugin or marketplace found in ${ownerRepo}. Expected .claude-plugin/ directory or component files (commands/, agents/, skills/, hooks/, .mcp.json, .lsp.json).`);
         process.exit(1);
     }
+    if (pluginName && detection.kind === 'plugin') {
+        printError(`--plugin is only valid for marketplace repos. "${ownerRepo}" is a standalone plugin.`);
+        process.exit(1);
+    }
     if (detection.kind === 'marketplace') {
-        await installMarketplace(ownerRepo, detection, yes, scopeOverride);
+        await installMarketplace(ownerRepo, detection, yes, scopeOverride, pluginName);
     }
     else {
         await installStandalone(ownerRepo, detection, yes, scopeOverride);
     }
 }
-async function installMarketplace(ownerRepo, detection, yes, scopeOverride) {
+async function installMarketplace(ownerRepo, detection, yes, scopeOverride, pluginName = null) {
     const { manifest } = detection;
     printSuccess(`Marketplace "${manifest.name}" — ${manifest.plugins.length} plugin(s)`);
     if (manifest.plugins.length === 0) {
         printError('No valid plugins found in marketplace.');
         process.exit(1);
     }
-    // Plugin picker
+    // Plugin selection
     let selectedPlugins = manifest.plugins;
-    if (!yes && manifest.plugins.length > 1) {
+    if (pluginName) {
+        const match = manifest.plugins.find((p) => p.name === pluginName);
+        if (!match) {
+            printError(`Plugin "${pluginName}" not found in marketplace "${manifest.name}". ` +
+                `Available: ${manifest.plugins.map((p) => p.name).join(', ')}`);
+            process.exit(1);
+        }
+        selectedPlugins = [match];
+    }
+    else if (!yes && manifest.plugins.length > 1) {
         print('');
         const items = manifest.plugins.map((p) => ({
             label: p.name,

package/dist/index.js

@@ -7,8 +7,8 @@ import { runRemove } from './remove.js';
 import { runList } from './list.js';
 import { isOwnerRepo } from './detect.js';
 import { runGithubInstall, runGithubRemove } from './github-install.js';
+import { parseArgs, validatePlugin } from './args.js';
 import { print, printBanner, printStep, printSuccess, printError, DIM, RESET, GREEN, CYAN, YELLOW, } from './output.js';
-const VALID_SCOPES = ['user', 'project', 'local'];
 const TYPE_BADGES = {
     skill: `${GREEN}[skill]${RESET}`,
     command: `${CYAN}[cmd]${RESET}`,
@@ -38,39 +38,12 @@ Note: owner/repo installs use Claude Code's plugin system.
   - Standalone: \`npx claudepluginhub remove owner/repo\` for cleanup
 
 Options:
+  --plugin <name> Install a specific plugin from a marketplace repo
   --yes, -y       Skip prompts (install all, project scope)
   --scope <scope> Set scope: user, project (default), local
   -h, --help      Show this help
 `);
 }
-function parseArgs(argv) {
-    const yes = argv.includes('--yes') || argv.includes('-y');
-    let scope = null;
-    const scopeIdx = argv.indexOf('--scope');
-    if (scopeIdx !== -1 && argv[scopeIdx + 1]) {
-        const val = argv[scopeIdx + 1];
-        if (!VALID_SCOPES.includes(val)) {
-            printError(`Invalid scope "${val}". Must be: user, project, or local`);
-            process.exit(1);
-        }
-        scope = val;
-    }
-    // Filter out flags and their values
-    const positional = argv.filter((a, i) => !a.startsWith('-') && (i === 0 || argv[i - 1] !== '--scope'));
-    const first = positional[0] ?? null;
-    const second = positional[1] ?? null;
-    // Route commands
-    if (first === 'list')
-        return { command: 'list', identifier: null, yes, scope };
-    if (first === 'update')
-        return { command: 'update', identifier: second, yes, scope };
-    if (first === 'remove')
-        return { command: 'remove', identifier: second, yes, scope };
-    if (first === 'add')
-        return { command: 'add', identifier: second, yes, scope };
-    // Default: treat first positional as identifier for install
-    return { command: 'add', identifier: first, yes, scope };
-}
 async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
@@ -78,7 +51,9 @@ async function main() {
         printUsage();
         process.exit(0);
     }
-    const { command, identifier, yes, scope: scopeOverride } = parseArgs(args);
+    const parsed = parseArgs(args);
+    validatePlugin(parsed);
+    const { command, identifier, plugin, yes, scope: scopeOverride } = parsed;
     printBanner();
     // Handle non-install commands
     if (command === 'list') {
@@ -109,7 +84,7 @@ async function main() {
     }
     // owner/repo → native Claude Code install
     if (isOwnerRepo(identifier)) {
-        await runGithubInstall(identifier, yes, scopeOverride);
+        await runGithubInstall(identifier, yes, scopeOverride, plugin);
         process.exit(0);
     }
     // Resolve identifier to API URL

package/dist/output.d.ts

@@ -16,6 +16,7 @@ export declare function printBanner(): void;
 export declare function printWarning(message: string): void;
 export declare function printStep(label: string): void;
 export declare function printSuccess(label: string): void;
+export declare function printProgress(label: string): void;
 export declare function printFail(label: string, error?: string): void;
 export declare function printSummary(results: {
     name: string;

package/dist/output.js

@@ -28,6 +28,9 @@ export function printStep(label) {
 export function printSuccess(label) {
     print(`  ${GREEN}ok${RESET} ${label}`);
 }
+export function printProgress(label) {
+    print(`  ${DIM}↓${RESET}  ${label}`);
+}
 export function printFail(label, error) {
     print(`  ${RED}fail${RESET} ${label}${error ? ` ${DIM}(${error})${RESET}` : ''}`);
 }

package/dist/validation.d.ts

@@ -0,0 +1,7 @@
+/** Shared validation constants and helpers for the CLI. */
+/** Matches a single valid name segment: alphanumeric, underscore, dot, hyphen. */
+export declare const VALID_NAME_RE: RegExp;
+/** Matches an owner/repo string (two valid name segments separated by /). */
+export declare const OWNER_REPO_RE: RegExp;
+/** Validates that a string is a well-formed owner/repo identifier. */
+export declare function isOwnerRepo(identifier: string): boolean;

package/dist/validation.js

@@ -0,0 +1,15 @@
+/** Shared validation constants and helpers for the CLI. */
+/** Matches a single valid name segment: alphanumeric, underscore, dot, hyphen. */
+export const VALID_NAME_RE = /^[a-zA-Z0-9_.-]+$/;
+/** Matches an owner/repo string (two valid name segments separated by /). */
+export const OWNER_REPO_RE = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
+/** Validates that a string is a well-formed owner/repo identifier. */
+export function isOwnerRepo(identifier) {
+    if (!OWNER_REPO_RE.test(identifier))
+        return false;
+    const [owner, repo] = identifier.split('/');
+    // Reject segments that are purely dots (e.g. "..", ".")
+    if (/^\.+$/.test(owner) || /^\.+$/.test(repo))
+        return false;
+    return true;
+}

package/dist/wrapper.js

@@ -2,7 +2,7 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
-const VALID_NAME_RE = /^[a-zA-Z0-9_.-]+$/;
+import { VALID_NAME_RE } from './validation.js';
 export function sanitizeName(raw) {
     return (raw
         .toLowerCase()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudepluginhub",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Install Claude Code components from ClaudePluginHub",
   "bin": {
     "claudepluginhub": "dist/index.js"