claudepluginhub 0.6.0 → 0.7.1

package/dist/args.d.ts

@@ -1,10 +1,19 @@
 import type { Scope } from './prompts.js';
+declare const COMPONENT_FLAGS: readonly ["--skill", "--command", "--agent"];
+export type ComponentType = (typeof COMPONENT_FLAGS)[number] extends `--${infer T}` ? T : never;
 export interface ParsedArgs {
     command: string;
     identifier: string | null;
     plugin: string | null;
     yes: boolean;
     scope: Scope | null;
+    componentFlag: {
+        type: ComponentType;
+        repoPath: string;
+        pluginPath: string;
+    } | null;
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function validatePlugin(args: ParsedArgs): void;
+export declare function validateComponentFlag(args: ParsedArgs): void;
+export {};

package/dist/args.js

@@ -1,10 +1,12 @@
 import { VALID_NAME_RE, isOwnerRepo } from './validation.js';
 import { printError } from './output.js';
 const VALID_SCOPES = ['user', 'project', 'local'];
+const COMPONENT_FLAGS = ['--skill', '--command', '--agent'];
 export function parseArgs(argv) {
     const yes = argv.includes('--yes') || argv.includes('-y');
     let scope = null;
     let plugin = null;
+    let componentFlag = null;
     const scopeIdx = argv.indexOf('--scope');
     if (scopeIdx !== -1) {
         const val = argv[scopeIdx + 1];
@@ -31,22 +33,66 @@ export function parseArgs(argv) {
         }
         plugin = val;
     }
+    // Parse component flags (--skill, --command, --agent)
+    const foundComponentFlags = [];
+    for (const flag of COMPONENT_FLAGS) {
+        const idx = argv.indexOf(flag);
+        if (idx !== -1) {
+            foundComponentFlags.push({ flag, type: flag.slice(2), idx });
+        }
+    }
+    if (foundComponentFlags.length > 1) {
+        printError('Only one of --skill, --command, or --agent can be specified');
+        process.exit(1);
+    }
+    if (foundComponentFlags.length === 1) {
+        const { type, idx } = foundComponentFlags[0];
+        const val = argv[idx + 1];
+        if (!val || val.startsWith('-')) {
+            printError(`Missing value for --${type}`);
+            process.exit(1);
+        }
+        if (plugin) {
+            printError('--plugin and component flags (--skill, --command, --agent) cannot be used together');
+            process.exit(1);
+        }
+        // Parse optional --source-path
+        let pluginPath = val;
+        const sourcePathIdx = argv.indexOf('--source-path');
+        if (sourcePathIdx !== -1) {
+            const spVal = argv[sourcePathIdx + 1];
+            if (!spVal || spVal.startsWith('-')) {
+                printError('Missing value for --source-path');
+                process.exit(1);
+            }
+            pluginPath = spVal;
+        }
+        componentFlag = { type, repoPath: val, pluginPath };
+    }
+    // --source-path without a component flag
+    if (!componentFlag && argv.includes('--source-path')) {
+        printError('--source-path requires a component flag (--skill, --command, or --agent)');
+        process.exit(1);
+    }
     // Filter out flags and their values
+    const flagsWithValues = new Set(['--scope', '--plugin', '--source-path']);
+    for (const f of COMPONENT_FLAGS)
+        flagsWithValues.add(f);
     const positional = argv.filter((a, i) => !a.startsWith('-') &&
-        (i === 0 || (argv[i - 1] !== '--scope' && argv[i - 1] !== '--plugin')));
+        (i === 0 || !flagsWithValues.has(argv[i - 1])));
     const first = positional[0] ?? null;
     const second = positional[1] ?? null;
     // Route commands
     if (first === 'list')
-        return { command: 'list', identifier: null, plugin, yes, scope };
+        return { command: 'list', identifier: null, plugin, yes, scope, componentFlag };
     if (first === 'update')
-        return { command: 'update', identifier: second, plugin, yes, scope };
+        return { command: 'update', identifier: second, plugin, yes, scope, componentFlag };
     if (first === 'remove')
-        return { command: 'remove', identifier: second, plugin, yes, scope };
+        return { command: 'remove', identifier: second, plugin, yes, scope, componentFlag };
     if (first === 'add')
-        return { command: 'add', identifier: second, plugin, yes, scope };
+        return { command: 'add', identifier: second, plugin, yes, scope, componentFlag };
     // Default: treat first positional as identifier for install
-    return { command: 'add', identifier: first, plugin, yes, scope };
+    return { command: 'add', identifier: first, plugin, yes, scope, componentFlag };
 }
 export function validatePlugin(args) {
     if (!args.plugin)
@@ -60,3 +106,15 @@ export function validatePlugin(args) {
         process.exit(1);
     }
 }
+export function validateComponentFlag(args) {
+    if (!args.componentFlag)
+        return;
+    if (args.command !== 'add') {
+        printError(`--${args.componentFlag.type} is only valid for install commands`);
+        process.exit(1);
+    }
+    if (!args.identifier || !isOwnerRepo(args.identifier)) {
+        printError(`--${args.componentFlag.type} is only valid with owner/repo identifiers`);
+        process.exit(1);
+    }
+}

package/dist/component-install.d.ts

@@ -0,0 +1,3 @@
+import type { Scope } from './prompts.js';
+import type { ComponentType } from './args.js';
+export declare function runDirectComponentInstall(ownerRepo: string, componentType: ComponentType, repoPath: string, pluginPath: string, yes: boolean, scopeOverride: Scope | null): Promise<void>;

package/dist/component-install.js

@@ -0,0 +1,186 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scopePrompt } from './prompts.js';
+import { installComponent, getBaseDir } from './download.js';
+import { readLock, writeLock, addCollection, componentKey } from './lock.js';
+import { fetchDefaultBranch, fetchTree } from './github.js';
+import { print, printStep, printSuccess, printError, BOLD, RESET, DIM, GREEN, } from './output.js';
+const DIRECT_SENTINEL = '';
+/**
+ * Validate that pluginPath has the expected path suffix for its type
+ * (/SKILL.md for skills, .md for commands/agents).
+ */
+function validatePathFormat(componentType, pluginPath) {
+    if (componentType === 'skill') {
+        if (!pluginPath.endsWith('/SKILL.md')) {
+            printError('Invalid skill path: must end with /SKILL.md');
+            process.exit(1);
+        }
+    }
+    else {
+        if (!pluginPath.endsWith('.md')) {
+            printError(`Invalid ${componentType} path: must end with .md`);
+            process.exit(1);
+        }
+    }
+}
+/**
+ * Validate that repoPath and pluginPath are aligned.
+ * Either they are equal (no subdir) or repoPath ends with '/' + pluginPath (monorepo).
+ */
+function validatePathAlignment(repoPath, pluginPath) {
+    if (!repoPath || !pluginPath) {
+        printError('Both repo path and source path must be non-empty');
+        process.exit(1);
+    }
+    if (repoPath !== pluginPath && !repoPath.endsWith('/' + pluginPath)) {
+        printError('Repo path and --source-path do not match: repo path must equal source path or end with /<source-path>');
+        process.exit(1);
+    }
+}
+/**
+ * Derive componentName from pluginPath, matching flattenComponents() semantics in fetch.ts.
+ */
+function deriveComponentName(componentType, pluginPath) {
+    if (componentType === 'skill') {
+        // "skills/review/SKILL.md" → "review"
+        // "tools/helpers/my-skill/SKILL.md" → "my-skill"
+        const withoutSuffix = pluginPath.replace(/\/SKILL\.md$/, '');
+        return withoutSuffix.split('/').pop();
+    }
+    // Commands/agents: strip type prefix if present, then strip .md
+    // "commands/git/commit.md" → "git/commit"
+    // "custom/cmds/deploy.md" → "custom/cmds/deploy"
+    const typeDir = componentType === 'command' ? 'commands/' : 'agents/';
+    const relPath = pluginPath.startsWith(typeDir)
+        ? pluginPath.slice(typeDir.length)
+        : pluginPath;
+    return relPath.replace(/\.md$/, '');
+}
+/**
+ * Compute the local destination path for a component.
+ */
+function computeDestPath(scope, componentType, pluginPath, componentName) {
+    const baseDir = getBaseDir(scope);
+    if (componentType === 'skill') {
+        return join(baseDir, 'skills', componentName);
+    }
+    const subdir = componentType === 'command' ? 'commands' : 'agents';
+    const prefix = subdir + '/';
+    const relPath = pluginPath.startsWith(prefix)
+        ? pluginPath.slice(prefix.length)
+        : pluginPath;
+    return join(baseDir, subdir, relPath);
+}
+export async function runDirectComponentInstall(ownerRepo, componentType, repoPath, pluginPath, yes, scopeOverride) {
+    // Step 1: Validate path format and alignment
+    validatePathFormat(componentType, pluginPath);
+    validatePathAlignment(repoPath, pluginPath);
+    // Step 2: Fetch tree, handle truncation
+    printStep('Fetching repository tree...');
+    const branch = await fetchDefaultBranch(ownerRepo);
+    if (!branch) {
+        printError(`Could not access repository ${ownerRepo}`);
+        process.exit(1);
+    }
+    const tree = await fetchTree(ownerRepo, branch);
+    if (!tree) {
+        printError(`Could not fetch file tree for ${ownerRepo}`);
+        process.exit(1);
+    }
+    if (tree.truncated) {
+        printError('Repository tree is too large (truncated). Cannot verify component path.');
+        printError(`Install the full plugin instead: npx claudepluginhub ${ownerRepo}`);
+        process.exit(1);
+    }
+    // Step 3: Verify exact repoPath in tree
+    const exists = tree.tree.some((e) => e.type === 'blob' && e.path === repoPath);
+    if (!exists) {
+        printError(`File not found: ${repoPath}`);
+        printError(`Verify the path exists in ${ownerRepo} on branch ${branch}`);
+        process.exit(1);
+    }
+    // Step 4: Skill — reject nested template SKILL.md
+    if (componentType === 'skill') {
+        const skillDir = repoPath.replace(/\/SKILL\.md$/, '').toLowerCase();
+        const isNested = tree.tree.some((e) => e.type === 'blob' &&
+            e.path.toLowerCase().endsWith('/skill.md') &&
+            e.path.toLowerCase() !== repoPath.toLowerCase() &&
+            skillDir.startsWith(e.path.replace(/\/skill\.md$/i, '').toLowerCase() + '/'));
+        if (isNested) {
+            printError('Cannot install nested SKILL.md (template or asset file inside another skill directory).');
+            process.exit(1);
+        }
+    }
+    // Step 5: Derive component name
+    const componentName = deriveComponentName(componentType, pluginPath);
+    printSuccess(`${componentName} (${componentType})`);
+    // Step 6: Scope picker
+    let scope = scopeOverride ?? 'project';
+    if (!yes && !scopeOverride) {
+        print('');
+        const chosenScope = await scopePrompt('project');
+        if (chosenScope === null) {
+            print('\nCancelled.');
+            process.exit(0);
+        }
+        scope = chosenScope;
+    }
+    // Step 7: Collision detection (two layers)
+    const lock = readLock(scope);
+    const existing = lock.collections[ownerRepo];
+    const newKey = componentKey(ownerRepo, repoPath);
+    // Layer 1: Lock collision — different repoPath, same pluginPath
+    if (existing) {
+        for (const [key, comp] of Object.entries(existing.components)) {
+            if (key !== newKey && comp.sourcePath === pluginPath) {
+                printError(`Collision: "${pluginPath}" is already installed from a different path in this repo.`);
+                printError(`Existing source: ${key}`);
+                printError('Remove the existing install first, or install the full plugin instead.');
+                process.exit(1);
+            }
+        }
+    }
+    // Layer 2: Filesystem collision — destination already occupied
+    const isReinstall = existing?.components[newKey] !== undefined;
+    if (!isReinstall) {
+        const destPath = computeDestPath(scope, componentType, pluginPath, componentName);
+        if (existsSync(destPath)) {
+            printError(`Destination already exists: ${destPath}`);
+            printError('Another plugin, collection, or manual install may be using this path.');
+            printError('Remove the existing file/directory first, or install the full plugin instead.');
+            process.exit(1);
+        }
+    }
+    // Step 8: Build FlatComponent and install
+    print('');
+    printStep(`Installing ${componentName}...`);
+    const component = {
+        source: ownerRepo,
+        type: componentType,
+        componentName,
+        sourcePath: pluginPath,
+        downloadPath: repoPath,
+        inlineConfig: null,
+    };
+    const result = await installComponent(component, scope, false);
+    if (result.status !== 'installed') {
+        printError(`Failed to install ${componentName}. Check the error messages above for details.`);
+        process.exit(1);
+    }
+    // Step 9: Merge into lock file
+    const mergedComponents = {
+        ...(existing?.components ?? {}),
+        [newKey]: result.lock,
+    };
+    addCollection(lock, ownerRepo, DIRECT_SENTINEL, scope, mergedComponents);
+    writeLock(scope, lock);
+    // Step 10: Print result
+    printSuccess(componentName);
+    print('');
+    print(`${GREEN}${BOLD}Done!${RESET} ${componentType} "${componentName}" installed.`);
+    print('');
+    print(`${DIM}Manage with:${RESET}`);
+    print(`  ${DIM}npx claudepluginhub remove ${ownerRepo} --scope ${scope}${RESET}`);
+    print('');
+}

package/dist/download.d.ts

@@ -5,8 +5,10 @@ export interface FlatComponent {
     type: 'command' | 'agent' | 'skill' | 'hook' | 'mcp' | 'lsp';
     componentName: string;
     sourcePath: string;
+    downloadPath?: string;
     inlineConfig: unknown | null;
 }
+export declare function getBaseDir(scope: Scope): string;
 export type InstallResult = {
     status: 'installed';
     lock: ComponentLock;

package/dist/download.js

@@ -3,7 +3,7 @@ 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, printProgress } from './output.js';
-function getBaseDir(scope) {
+export function getBaseDir(scope) {
     if (scope === 'user') {
         return join(homedir(), '.claude');
     }
@@ -43,8 +43,9 @@ function isSafePath(destPath, baseDir) {
 }
 export async function downloadSkill(component, scope) {
     const { source, sourcePath, componentName } = component;
-    // Strip /SKILL.md to get directory path
-    const dirPath = sourcePath.replace(/\/SKILL\.md$/, '');
+    const downloadSource = component.downloadPath ?? sourcePath;
+    // Strip /SKILL.md to get directory path (repo-root-relative for GitHub API)
+    const dirPath = downloadSource.replace(/\/SKILL\.md$/, '');
     const branch = await fetchDefaultBranch(source);
     if (!branch)
         return null;
@@ -99,6 +100,7 @@ export async function downloadSkill(component, scope) {
 }
 export async function downloadSingleFile(component, scope) {
     const { source, type, sourcePath, componentName } = component;
+    const effectivePath = component.downloadPath ?? sourcePath;
     const branch = await fetchDefaultBranch(source);
     if (!branch)
         return null;
@@ -115,12 +117,12 @@ export async function downloadSingleFile(component, scope) {
         printError(`Skipping unsafe path: ${sourcePath}`);
         return null;
     }
-    const content = await downloadFile(source, branch, sourcePath);
+    const content = await downloadFile(source, branch, effectivePath);
     if (content === null)
         return null;
     ensureDir(destPath);
     writeFileSync(destPath, content);
-    const hash = findBlobSha(tree, sourcePath) ?? 'unknown';
+    const hash = findBlobSha(tree, effectivePath) ?? 'unknown';
     return {
         source,
         type,

package/dist/index.js

@@ -3,11 +3,13 @@ import { resolveMarketplaceUrl, fetchMarketplace, flattenComponents } from './fe
 import { checkboxPrompt, scopePrompt, confirmPrompt } from './prompts.js';
 import { runInstall } from './install.js';
 import { runUpdate } from './update.js';
-import { runRemove } from './remove.js';
+import { runRemove, runDirectRemove } 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 { findWrapperScopes } from './wrapper.js';
+import { findDirectInstallScopes } from './scope-detect.js';
+import { parseArgs, validatePlugin, validateComponentFlag } from './args.js';
 import { print, printBanner, printStep, printSuccess, printError, DIM, RESET, GREEN, CYAN, YELLOW, } from './output.js';
 const TYPE_BADGES = {
     skill: `${GREEN}[skill]${RESET}`,
@@ -23,8 +25,8 @@ function printUsage() {
 Commands:
   <identifier>              Install from a source
   add <identifier>          Same as above
-  update [identifier]       Update (u/ collections only)
-  list                      List (u/ collections only)
+  update [identifier]       Update installed collections
+  list                      List all installed collections
   remove <identifier>       Remove
 
 Identifiers:
@@ -32,16 +34,26 @@ Identifiers:
   u/<userId>/<slug>         ClaudePluginHub collection
   https://claudepluginhub.com/api/user-plugins/.../marketplace.json
 
-Note: owner/repo installs use Claude Code's plugin system.
-  - list/update only show u/ installs
+Install modes:
+  owner/repo                Full plugin install (via Claude Code plugin system)
+  owner/repo --skill <path> Direct single-component install (skill, command, or agent)
+  u/<userId>/<slug>         Collection install
+
+Notes:
+  - list shows all lock-backed installs (collections + direct components)
+  - update applies to collections only; direct installs are skipped
   - Use \`claude plugin list\` for Claude Code plugins
   - 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
+  --plugin <name>         Install a specific plugin from a marketplace repo
+  --skill <path>          Install a single skill directly from a repo
+  --command <path>        Install a single command directly from a repo
+  --agent <path>          Install a single agent directly from a repo
+  --source-path <path>    Plugin-relative path (for monorepo installs)
+  --yes, -y               Skip prompts (install all, project scope)
+  --scope <scope>         Set scope: user, project (default), local
+  -h, --help              Show this help
 `);
 }
 async function main() {
@@ -53,7 +65,8 @@ async function main() {
     }
     const parsed = parseArgs(args);
     validatePlugin(parsed);
-    const { command, identifier, plugin, yes, scope: scopeOverride } = parsed;
+    validateComponentFlag(parsed);
+    const { command, identifier, plugin, yes, scope: scopeOverride, componentFlag } = parsed;
     printBanner();
     // Handle non-install commands
     if (command === 'list') {
@@ -69,9 +82,42 @@ async function main() {
             printError('Missing identifier. Usage: npx claudepluginhub remove <identifier>');
             process.exit(1);
         }
-        // owner/repo remove → github wrapper cleanup
         if (isOwnerRepo(identifier)) {
-            await runGithubRemove(identifier, scopeOverride);
+            // Scope-aware remove: check both direct installs and wrapper installs
+            const directScopes = findDirectInstallScopes(identifier);
+            const wrapperScopes = findWrapperScopes(identifier);
+            const allMatches = [
+                ...directScopes.map((s) => ({ scope: s, kind: 'direct' })),
+                ...wrapperScopes.map((s) => ({ scope: s, kind: 'wrapper' })),
+            ];
+            const filtered = scopeOverride
+                ? allMatches.filter((m) => m.scope === scopeOverride)
+                : allMatches;
+            // Case 1: Nothing found anywhere → fall back for marketplace guidance
+            if (allMatches.length === 0) {
+                await runGithubRemove(identifier, scopeOverride);
+                process.exit(0);
+            }
+            // Case 2: Found in other scopes but not the requested one
+            if (filtered.length === 0) {
+                const scopeList = [...new Set(allMatches.map((m) => m.scope))].join(', ');
+                printError(`"${identifier}" not found in ${scopeOverride} scope (found in: ${scopeList})`);
+                process.exit(1);
+            }
+            // Case 3: Multiple scopes without --scope
+            const uniqueScopes = [...new Set(filtered.map((m) => m.scope))];
+            if (uniqueScopes.length > 1) {
+                printError(`"${identifier}" found in multiple scopes: ${uniqueScopes.join(', ')}. Use --scope to specify.`);
+                process.exit(1);
+            }
+            // Case 4: Single scope — remove all matching kinds
+            const targetScope = uniqueScopes[0];
+            if (filtered.some((m) => m.kind === 'direct')) {
+                await runDirectRemove(identifier, targetScope);
+            }
+            if (filtered.some((m) => m.kind === 'wrapper')) {
+                await runGithubRemove(identifier, targetScope);
+            }
             process.exit(0);
         }
         await runRemove(identifier);
@@ -82,6 +128,12 @@ async function main() {
         printUsage();
         process.exit(1);
     }
+    // Direct component install: owner/repo + --skill/--command/--agent
+    if (componentFlag && isOwnerRepo(identifier)) {
+        const { runDirectComponentInstall } = await import('./component-install.js');
+        await runDirectComponentInstall(identifier, componentFlag.type, componentFlag.repoPath, componentFlag.pluginPath, yes, scopeOverride);
+        process.exit(0);
+    }
     // owner/repo → native Claude Code install
     if (isOwnerRepo(identifier)) {
         await runGithubInstall(identifier, yes, scopeOverride, plugin);

package/dist/remove.d.ts

@@ -1,3 +1,5 @@
+import type { Scope } from './prompts.js';
 import type { ComponentLock } from './lock.js';
 export declare function removeComponentByLock(comp: ComponentLock): void;
+export declare function runDirectRemove(identifier: string, scope: Scope): Promise<void>;
 export declare function runRemove(identifier: string): Promise<void>;

package/dist/remove.js

@@ -85,6 +85,24 @@ function removeFiles(lock) {
 export function removeComponentByLock(comp) {
     removeFiles(comp);
 }
+export async function runDirectRemove(identifier, scope) {
+    const lock = readLock(scope);
+    const collection = lock.collections[identifier];
+    if (!collection) {
+        printError(`"${identifier}" not found in ${scope} scope`);
+        process.exit(1);
+    }
+    printStep(`Removing ${Object.keys(collection.components).length} component(s) from ${scope} scope...`);
+    for (const [, comp] of Object.entries(collection.components)) {
+        removeFiles(comp);
+        printSuccess(`${comp.componentName} (${comp.type})`);
+    }
+    removeCollection(lock, identifier);
+    writeLock(scope, lock);
+    print('');
+    print(`${BOLD}Removed${RESET} ${identifier}`);
+    print('');
+}
 export async function runRemove(identifier) {
     // Try all scopes to find the collection
     const scopes = ['project', 'local', 'user'];

package/dist/scope-detect.d.ts

@@ -0,0 +1,2 @@
+import type { Scope } from './prompts.js';
+export declare function findDirectInstallScopes(identifier: string): Scope[];

package/dist/scope-detect.js

@@ -0,0 +1,12 @@
+import { readLock } from './lock.js';
+export function findDirectInstallScopes(identifier) {
+    const found = [];
+    for (const scope of ['project', 'local', 'user']) {
+        const lock = readLock(scope);
+        const collection = lock.collections[identifier];
+        if (collection && collection.apiUrl === '') {
+            found.push(scope);
+        }
+    }
+    return found;
+}

package/dist/update.js

@@ -29,6 +29,14 @@ export async function runUpdate(identifier) {
             if (identifier && collection.identifier !== identifier)
                 continue;
             found = true;
+            // Skip direct installs (apiUrl === '' sentinel)
+            if (collection.apiUrl === '') {
+                print(`${BOLD}${collection.identifier}${RESET} — direct install, skipped`);
+                for (const comp of Object.values(collection.components)) {
+                    print(`  ${DIM}Re-install: npx claudepluginhub ${collection.identifier} --${comp.type} ${comp.sourcePath}${RESET}`);
+                }
+                continue;
+            }
             print(`${BOLD}Updating${RESET} ${collection.identifier}...`);
             const manifest = await fetchMarketplace(collection.apiUrl);
             if (!manifest) {

package/package.json

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