claudepluginhub 0.2.0 → 0.3.0

package/dist/download.d.ts

@@ -0,0 +1,21 @@
+import type { Scope } from './prompts.js';
+import type { ComponentLock } from './lock.js';
+export interface FlatComponent {
+    source: string;
+    type: 'command' | 'agent' | 'skill' | 'hook' | 'mcp' | 'lsp';
+    componentName: string;
+    sourcePath: string;
+    inlineConfig: unknown | null;
+}
+export type InstallResult = {
+    status: 'installed';
+    lock: ComponentLock;
+} | {
+    status: 'skipped';
+} | {
+    status: 'failed';
+};
+export declare function downloadSkill(component: FlatComponent, scope: Scope): Promise<ComponentLock | null>;
+export declare function downloadSingleFile(component: FlatComponent, scope: Scope): Promise<ComponentLock | null>;
+export declare function mergeConfig(component: FlatComponent, scope: Scope): Promise<ComponentLock | null>;
+export declare function installComponent(component: FlatComponent, scope: Scope, checkExisting: boolean): Promise<InstallResult>;

package/dist/download.js

@@ -0,0 +1,264 @@
+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';
+function getBaseDir(scope) {
+    if (scope === 'user') {
+        return join(homedir(), '.claude');
+    }
+    return join(process.cwd(), '.claude');
+}
+function getSettingsFile(scope) {
+    const base = getBaseDir(scope);
+    if (scope === 'local') {
+        return join(base, 'settings.local.json');
+    }
+    return join(base, 'settings.json');
+}
+function ensureDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function readJsonFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJsonFile(path, data) {
+    ensureDir(path);
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+function isSafePath(destPath, baseDir) {
+    const resolved = resolve(destPath);
+    const base = resolve(baseDir);
+    return resolved.startsWith(base + sep) || resolved === base;
+}
+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 branch = await fetchDefaultBranch(source);
+    if (!branch)
+        return null;
+    const tree = await fetchTree(source, branch);
+    if (!tree)
+        return null;
+    const files = listFilesUnder(tree, dirPath);
+    if (files.length === 0) {
+        printError(`No files found for skill ${componentName} at ${dirPath}`);
+        return null;
+    }
+    const baseDir = getBaseDir(scope);
+    const skillsRoot = join(baseDir, 'skills');
+    const installDir = join(skillsRoot, componentName);
+    if (!isSafePath(installDir, skillsRoot)) {
+        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)
+            return null;
+        ensureDir(destPath);
+        writeFileSync(destPath, content);
+    }
+    const hash = findTreeSha(tree, dirPath) ?? 'unknown';
+    return {
+        source,
+        type: 'skill',
+        componentName,
+        sourcePath,
+        installedPath: installDir,
+        hash,
+        configFile: null,
+        configKeys: null,
+        configFragment: null,
+    };
+}
+export async function downloadSingleFile(component, scope) {
+    const { source, type, sourcePath, componentName } = component;
+    const branch = await fetchDefaultBranch(source);
+    if (!branch)
+        return null;
+    const tree = await fetchTree(source, branch);
+    if (!tree)
+        return null;
+    const baseDir = getBaseDir(scope);
+    const subdir = type === 'command' ? 'commands' : 'agents';
+    // Preserve nested path: "commands/git/commit.md" -> .claude/commands/git/commit.md
+    const prefix = subdir + '/';
+    const relPath = sourcePath.startsWith(prefix) ? sourcePath.slice(prefix.length) : sourcePath;
+    const destPath = join(baseDir, subdir, relPath);
+    if (!isSafePath(destPath, join(baseDir, subdir))) {
+        printError(`Skipping unsafe path: ${sourcePath}`);
+        return null;
+    }
+    const content = await downloadFile(source, branch, sourcePath);
+    if (content === null)
+        return null;
+    ensureDir(destPath);
+    writeFileSync(destPath, content);
+    const hash = findBlobSha(tree, sourcePath) ?? 'unknown';
+    return {
+        source,
+        type,
+        componentName,
+        sourcePath,
+        installedPath: destPath,
+        hash,
+        configFile: null,
+        configKeys: null,
+        configFragment: null,
+    };
+}
+async function resolveConfig(component) {
+    const { inlineConfig, source, sourcePath } = component;
+    // Inline config object — use directly
+    if (inlineConfig && typeof inlineConfig === 'object') {
+        return inlineConfig;
+    }
+    // String path — download and parse
+    if (typeof inlineConfig === 'string' || !inlineConfig) {
+        const filePath = typeof inlineConfig === 'string' ? inlineConfig : sourcePath;
+        const branch = await fetchDefaultBranch(source);
+        if (!branch)
+            return null;
+        const content = await downloadFile(source, branch, filePath);
+        if (!content)
+            return null;
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            printError(`Failed to parse config from ${filePath}`);
+            return null;
+        }
+    }
+    return null;
+}
+export async function mergeConfig(component, scope) {
+    const { source, type, componentName, sourcePath } = component;
+    const config = await resolveConfig(component);
+    if (!config)
+        return null;
+    const settingsPath = getSettingsFile(scope);
+    const settings = readJsonFile(settingsPath);
+    const configKeys = [];
+    let configFragment = null;
+    if (type === 'mcp') {
+        const servers = (settings.mcpServers ?? {});
+        const mcpConfig = config.mcpServers
+            ? config.mcpServers
+            : config;
+        const ownedFragment = {};
+        for (const [key, value] of Object.entries(mcpConfig)) {
+            if (key in servers) {
+                printError(`MCP server "${key}" already exists in settings — skipping`);
+                continue;
+            }
+            servers[key] = value;
+            ownedFragment[key] = value;
+            configKeys.push(`mcpServers.${key}`);
+        }
+        settings.mcpServers = servers;
+        configFragment = ownedFragment;
+    }
+    else if (type === 'lsp') {
+        const servers = (settings.lspServers ?? {});
+        const lspConfig = config.lspServers
+            ? config.lspServers
+            : config;
+        const ownedFragment = {};
+        for (const [key, value] of Object.entries(lspConfig)) {
+            if (key in servers) {
+                printError(`LSP server "${key}" already exists in settings — skipping`);
+                continue;
+            }
+            servers[key] = value;
+            ownedFragment[key] = value;
+            configKeys.push(`lspServers.${key}`);
+        }
+        settings.lspServers = servers;
+        configFragment = ownedFragment;
+    }
+    else if (type === 'hook') {
+        const hooks = (settings.hooks ?? {});
+        const hookConfig = config.hooks
+            ? config.hooks
+            : config;
+        for (const [event, handlers] of Object.entries(hookConfig)) {
+            if (!Array.isArray(handlers))
+                continue;
+            const existing = (hooks[event] ?? []);
+            // Only add handlers not already present (by deep equality)
+            const newHandlers = handlers.filter((h) => !existing.some((e) => JSON.stringify(e) === JSON.stringify(h)));
+            if (newHandlers.length > 0) {
+                hooks[event] = [...existing, ...newHandlers];
+            }
+            configKeys.push(`hooks.${event}`);
+        }
+        settings.hooks = hooks;
+        configFragment = hookConfig;
+    }
+    writeJsonFile(settingsPath, settings);
+    const branch = await fetchDefaultBranch(source);
+    const tree = branch ? await fetchTree(source, branch) : null;
+    const hash = tree ? (findBlobSha(tree, sourcePath) ?? 'unknown') : 'unknown';
+    return {
+        source,
+        type,
+        componentName,
+        sourcePath,
+        installedPath: settingsPath,
+        hash,
+        configFile: settingsPath,
+        configKeys,
+        configFragment,
+    };
+}
+export async function installComponent(component, scope, checkExisting) {
+    if (component.type === 'skill') {
+        if (checkExisting) {
+            const baseDir = getBaseDir(scope);
+            const destDir = join(baseDir, 'skills', component.componentName);
+            if (existsSync(destDir)) {
+                return { status: 'skipped' };
+            }
+        }
+        const lock = await downloadSkill(component, scope);
+        return lock ? { status: 'installed', lock } : { status: 'failed' };
+    }
+    if (component.type === 'command' || component.type === 'agent') {
+        if (checkExisting) {
+            const baseDir = getBaseDir(scope);
+            const subdir = component.type === 'command' ? 'commands' : 'agents';
+            const prefix = subdir + '/';
+            const relPath = component.sourcePath.startsWith(prefix)
+                ? component.sourcePath.slice(prefix.length)
+                : component.sourcePath;
+            const destPath = join(baseDir, subdir, relPath);
+            if (existsSync(destPath)) {
+                return { status: 'skipped' };
+            }
+        }
+        const lock = await downloadSingleFile(component, scope);
+        return lock ? { status: 'installed', lock } : { status: 'failed' };
+    }
+    // Config-based: hook, mcp, lsp
+    const lock = await mergeConfig(component, scope);
+    return lock ? { status: 'installed', lock } : { status: 'failed' };
+}

package/dist/fetch.d.ts

@@ -1,3 +1,4 @@
+import type { FlatComponent } from './download.js';
 export interface MarketplacePlugin {
     name: string;
     source: {
@@ -22,3 +23,4 @@ export interface MarketplaceJSON {
 }
 export declare function resolveMarketplaceUrl(input: string): string | null;
 export declare function fetchMarketplace(url: string): Promise<MarketplaceJSON | null>;
+export declare function flattenComponents(manifest: MarketplaceJSON): FlatComponent[];

package/dist/fetch.js

@@ -42,7 +42,7 @@ export async function fetchMarketplace(url) {
         });
         if (!response.ok) {
             if (response.status === 404) {
-                printError('Plugin not found. Check the identifier and try again.');
+                printError('Collection not found. Check the identifier and try again.');
             }
             else {
                 printError(`HTTP ${response.status}: ${response.statusText}`);
@@ -53,7 +53,7 @@ export async function fetchMarketplace(url) {
         if (!data.name ||
             !Array.isArray(data.plugins) ||
             data.plugins.some((p) => !p.name)) {
-            printError('Invalid marketplace JSON format.');
+            printError('Invalid collection JSON format.');
             return null;
         }
         return data;
@@ -63,3 +63,79 @@ export async function fetchMarketplace(url) {
         return null;
     }
 }
+export function flattenComponents(manifest) {
+    const components = [];
+    for (const plugin of manifest.plugins) {
+        const repo = plugin.source.repo;
+        if (plugin.commands) {
+            for (const path of plugin.commands) {
+                // Preserve full path under commands/ prefix, e.g. "commands/git/commit.md"
+                const relPath = path.startsWith('commands/') ? path.slice('commands/'.length) : path;
+                const name = relPath.replace(/\.md$/, '');
+                components.push({
+                    source: repo,
+                    type: 'command',
+                    componentName: name,
+                    sourcePath: path,
+                    inlineConfig: null,
+                });
+            }
+        }
+        if (plugin.agents) {
+            for (const path of plugin.agents) {
+                const relPath = path.startsWith('agents/') ? path.slice('agents/'.length) : path;
+                const name = relPath.replace(/\.md$/, '');
+                components.push({
+                    source: repo,
+                    type: 'agent',
+                    componentName: name,
+                    sourcePath: path,
+                    inlineConfig: null,
+                });
+            }
+        }
+        if (plugin.skills) {
+            for (const path of plugin.skills) {
+                // Preserve full path under skills/ prefix, e.g. "skills/review/SKILL.md" -> "review"
+                // But "skills/nested/deep/SKILL.md" -> "nested/deep"
+                const withoutSkillMd = path.replace(/\/SKILL\.md$/, '');
+                const relPath = withoutSkillMd.startsWith('skills/') ? withoutSkillMd.slice('skills/'.length) : withoutSkillMd;
+                components.push({
+                    source: repo,
+                    type: 'skill',
+                    componentName: relPath,
+                    sourcePath: path,
+                    inlineConfig: null,
+                });
+            }
+        }
+        if (plugin.hooks) {
+            components.push({
+                source: repo,
+                type: 'hook',
+                componentName: `${plugin.name}-hooks`,
+                sourcePath: typeof plugin.hooks === 'string' ? plugin.hooks : 'hooks/hooks.json',
+                inlineConfig: plugin.hooks,
+            });
+        }
+        if (plugin.mcpServers) {
+            components.push({
+                source: repo,
+                type: 'mcp',
+                componentName: `${plugin.name}-mcp`,
+                sourcePath: typeof plugin.mcpServers === 'string' ? plugin.mcpServers : '.mcp.json',
+                inlineConfig: plugin.mcpServers,
+            });
+        }
+        if (plugin.lspServers) {
+            components.push({
+                source: repo,
+                type: 'lsp',
+                componentName: `${plugin.name}-lsp`,
+                sourcePath: typeof plugin.lspServers === 'string' ? plugin.lspServers : '.lsp.json',
+                inlineConfig: plugin.lspServers,
+            });
+        }
+    }
+    return components;
+}

package/dist/github.d.ts

@@ -0,0 +1,19 @@
+interface TreeEntry {
+    path: string;
+    mode: string;
+    type: 'blob' | 'tree';
+    sha: string;
+    size?: number;
+}
+interface TreeResponse {
+    sha: string;
+    tree: TreeEntry[];
+    truncated: boolean;
+}
+export declare function fetchDefaultBranch(repo: string): Promise<string | null>;
+export declare function fetchTree(repo: string, branch: string): Promise<TreeResponse | null>;
+export declare function downloadFile(repo: string, branch: string, path: string): Promise<string | null>;
+export declare function findTreeSha(tree: TreeResponse, dirPath: string): string | null;
+export declare function findBlobSha(tree: TreeResponse, filePath: string): string | null;
+export declare function listFilesUnder(tree: TreeResponse, dirPath: string): TreeEntry[];
+export {};

package/dist/github.js

@@ -0,0 +1,93 @@
+import { printError } from './output.js';
+function getHeaders() {
+    const headers = {
+        Accept: 'application/vnd.github.v3+json',
+        'User-Agent': 'claudepluginhub-cli',
+    };
+    const token = process.env.GITHUB_TOKEN;
+    if (token) {
+        headers.Authorization = `token ${token}`;
+    }
+    return headers;
+}
+const branchCache = new Map();
+export async function fetchDefaultBranch(repo) {
+    const cached = branchCache.get(repo);
+    if (cached)
+        return cached;
+    try {
+        const response = await fetch(`https://api.github.com/repos/${repo}`, {
+            headers: getHeaders(),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            if (response.status === 403 || response.status === 404) {
+                printError(`Cannot access repo ${repo}. ${!process.env.GITHUB_TOKEN ? 'Set GITHUB_TOKEN for private repos.' : 'Check permissions.'}`);
+            }
+            else {
+                printError(`GitHub API error for ${repo}: ${response.status}`);
+            }
+            return null;
+        }
+        const data = (await response.json());
+        branchCache.set(repo, data.default_branch);
+        return data.default_branch;
+    }
+    catch (err) {
+        printError(`Failed to fetch repo info for ${repo}: ${err.message}`);
+        return null;
+    }
+}
+const treeCache = new Map();
+export async function fetchTree(repo, branch) {
+    const key = `${repo}@${branch}`;
+    const cached = treeCache.get(key);
+    if (cached)
+        return cached;
+    try {
+        const response = await fetch(`https://api.github.com/repos/${repo}/git/trees/${branch}?recursive=1`, {
+            headers: getHeaders(),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok) {
+            printError(`Failed to fetch file tree for ${repo}: ${response.status}`);
+            return null;
+        }
+        const data = (await response.json());
+        treeCache.set(key, data);
+        return data;
+    }
+    catch (err) {
+        printError(`Failed to fetch file tree for ${repo}: ${err.message}`);
+        return null;
+    }
+}
+export async function downloadFile(repo, branch, path) {
+    try {
+        const url = `https://raw.githubusercontent.com/${repo}/${branch}/${path}`;
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            printError(`Failed to download ${path} from ${repo}: ${response.status}`);
+            return null;
+        }
+        return await response.text();
+    }
+    catch (err) {
+        printError(`Failed to download ${path}: ${err.message}`);
+        return null;
+    }
+}
+export function findTreeSha(tree, dirPath) {
+    const entry = tree.tree.find((e) => e.type === 'tree' && e.path === dirPath);
+    return entry?.sha ?? null;
+}
+export function findBlobSha(tree, filePath) {
+    const entry = tree.tree.find((e) => e.type === 'blob' && e.path === filePath);
+    return entry?.sha ?? null;
+}
+export function listFilesUnder(tree, dirPath) {
+    const prefix = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+    return tree.tree.filter((e) => e.type === 'blob' && e.path.startsWith(prefix));
+}

package/dist/index.js

@@ -1,31 +1,33 @@
 #!/usr/bin/env node
-import { resolveMarketplaceUrl, fetchMarketplace } from './fetch.js';
-import { detectClaude, addMarketplace, installPlugin } from './install.js';
-import { checkboxPrompt, scopePrompt } from './prompts.js';
-import { print, printBanner, printStep, printSuccess, printFail, printSummary, printError, } from './output.js';
+import { resolveMarketplaceUrl, fetchMarketplace, flattenComponents } from './fetch.js';
+import { checkboxPrompt, scopePrompt, confirmPrompt } from './prompts.js';
+import { runInstall } from './install.js';
+import { runUpdate } from './update.js';
+import { runRemove } from './remove.js';
+import { runList } from './list.js';
+import { print, printBanner, printStep, printSuccess, printError, DIM, RESET, GREEN, CYAN, YELLOW, } from './output.js';
 const VALID_SCOPES = ['user', 'project', 'local'];
-function formatComponents(plugin) {
-    const parts = [];
-    if (plugin.commands?.length)
-        parts.push(`${plugin.commands.length} command(s)`);
-    if (plugin.agents?.length)
-        parts.push(`${plugin.agents.length} agent(s)`);
-    if (plugin.skills?.length)
-        parts.push(`${plugin.skills.length} skill(s)`);
-    if (plugin.hooks)
-        parts.push('hooks');
-    if (plugin.mcpServers)
-        parts.push('MCP');
-    if (plugin.lspServers)
-        parts.push('LSP');
-    return parts.length > 0 ? parts.join(', ') : '';
-}
+const TYPE_BADGES = {
+    skill: `${GREEN}[skill]${RESET}`,
+    command: `${CYAN}[cmd]${RESET}`,
+    agent: `${YELLOW}[agent]${RESET}`,
+    hook: `\x1b[35m[hook]${RESET}`,
+    mcp: `${CYAN}[mcp]${RESET}`,
+    lsp: `\x1b[34m[lsp]${RESET}`,
+};
 function printUsage() {
-    print(`Usage: npx claudepluginhub <identifier> [options]
+    print(`Usage: npx claudepluginhub <command> [options]
+
+Commands:
+  <identifier>              Install components from a user-plugin collection
+  add <identifier>          Same as above (explicit)
+  update [identifier]       Update installed components
+  list                      List installed components
+  remove <identifier>       Remove installed components
 
-Examples:
-  npx claudepluginhub u/<userId>/<slug>
-  npx claudepluginhub https://claudepluginhub.com/api/user-plugins/.../marketplace.json
+Identifiers:
+  u/<userId>/<slug>         Short form
+  https://claudepluginhub.com/api/user-plugins/.../marketplace.json
 
 Options:
   --yes, -y       Skip prompts (install all, project scope)
@@ -45,9 +47,21 @@ function parseArgs(argv) {
         }
         scope = val;
     }
+    // Filter out flags and their values
     const positional = argv.filter((a, i) => !a.startsWith('-') && (i === 0 || argv[i - 1] !== '--scope'));
-    const input = positional[0] ?? null;
-    return { input, yes, 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);
@@ -56,57 +70,71 @@ async function main() {
         printUsage();
         process.exit(0);
     }
-    const { input, yes, scope: scopeOverride } = parseArgs(args);
-    if (!input) {
-        printBanner();
+    const { command, identifier, yes, scope: scopeOverride } = parseArgs(args);
+    printBanner();
+    // Handle non-install commands
+    if (command === 'list') {
+        runList();
+        process.exit(0);
+    }
+    if (command === 'update') {
+        await runUpdate(identifier ?? undefined);
+        process.exit(0);
+    }
+    if (command === 'remove') {
+        if (!identifier) {
+            printError('Missing identifier. Usage: npx claudepluginhub remove <identifier>');
+            process.exit(1);
+        }
+        await runRemove(identifier);
+        process.exit(0);
+    }
+    // Install flow
+    if (!identifier) {
         printUsage();
         process.exit(1);
     }
-    printBanner();
-    // Resolve to marketplace URL
-    const url = resolveMarketplaceUrl(input);
+    // Resolve identifier to API URL
+    const url = resolveMarketplaceUrl(identifier);
     if (!url) {
-        printError(`Invalid input: ${input}`);
+        printError(`Invalid identifier: ${identifier}`);
         print('');
-        printUsage();
-        process.exit(1);
-    }
-    // Check claude CLI is available
-    printStep('Checking for Claude CLI...');
-    const claudePath = detectClaude();
-    if (!claudePath) {
-        printError('Claude CLI not found in PATH.\nInstall it from: https://docs.anthropic.com/en/docs/claude-code/overview');
+        print(`Expected: u/<userId>/<slug> or a claudepluginhub.com URL`);
         process.exit(1);
     }
-    printSuccess('Claude CLI found');
-    // Fetch marketplace JSON
-    printStep('Fetching marketplace...');
-    const marketplace = await fetchMarketplace(url);
-    if (!marketplace) {
+    // Derive the collection identifier from the input
+    const collectionId = identifier.startsWith('http')
+        ? extractIdentifierFromUrl(identifier)
+        : identifier;
+    // Fetch manifest
+    printStep('Fetching collection...');
+    const manifest = await fetchMarketplace(url);
+    if (!manifest) {
         process.exit(1);
     }
-    printSuccess(`"${marketplace.name}" - ${marketplace.plugins.length} plugin(s)`);
-    if (marketplace.plugins.length === 0) {
-        printError('No plugins found in this marketplace.');
+    const allComponents = flattenComponents(manifest);
+    printSuccess(`"${manifest.name}" - ${allComponents.length} component(s)`);
+    if (allComponents.length === 0) {
+        printError('No components found in this collection.');
         process.exit(0);
     }
-    // Plugin selection (interactive, >1 plugin)
-    let selectedPlugins = marketplace.plugins;
-    if (!yes && marketplace.plugins.length > 1) {
+    // Component selection (interactive)
+    let selectedComponents = allComponents;
+    if (!yes && allComponents.length > 1) {
         print('');
-        const items = marketplace.plugins.map((p) => ({
-            label: p.source.repo,
-            description: formatComponents(p),
+        const items = allComponents.map((c) => ({
+            label: `${TYPE_BADGES[c.type] ?? `[${c.type}]`} ${c.componentName}`,
+            description: `${DIM}${c.source}${RESET}`,
             selected: true,
         }));
-        const chosen = await checkboxPrompt('Select plugins to install:', items);
+        const chosen = await checkboxPrompt('Select components to install:', items);
         if (chosen === null) {
             print('\nCancelled.');
             process.exit(0);
         }
-        selectedPlugins = chosen.map((i) => marketplace.plugins[i]);
-        if (selectedPlugins.length === 0) {
-            printError('No plugins selected.');
+        selectedComponents = chosen.map((i) => allComponents[i]);
+        if (selectedComponents.length === 0) {
+            printError('No components selected.');
             process.exit(0);
         }
     }
@@ -121,35 +149,31 @@ async function main() {
         }
         scope = chosenScope;
     }
-    // Add marketplace
-    print('');
-    printStep('Adding marketplace...');
-    const addResult = addMarketplace(claudePath, url);
-    if (!addResult.ok) {
-        printError(`Failed to add marketplace: ${addResult.error}`);
-        process.exit(1);
-    }
-    printSuccess('Marketplace registered');
-    // Install each plugin
-    print('');
-    printStep(`Installing plugins (${scope} scope)...`);
-    const results = [];
-    for (const plugin of selectedPlugins) {
-        const installName = `${plugin.name}@${marketplace.name}`;
-        const result = installPlugin(claudePath, installName, scope);
-        results.push({ name: plugin.name, ...result });
-        if (result.ok) {
-            printSuccess(plugin.name);
-        }
-        else {
-            printFail(plugin.name, result.error);
+    // Safety warning for hooks/mcp/lsp
+    const hasUnsafe = selectedComponents.some((c) => c.type === 'hook' || c.type === 'mcp' || c.type === 'lsp');
+    if (hasUnsafe) {
+        print('');
+        print(`${YELLOW}Warning:${RESET} This collection includes hooks, MCP, or LSP config`);
+        print(`that will be merged into your settings file.`);
+        print(`Review the source repos before proceeding.`);
+        if (!yes) {
+            const confirmed = await confirmPrompt('Continue?');
+            if (!confirmed) {
+                print('\nCancelled.');
+                process.exit(0);
+            }
         }
+        print('');
     }
-    printSummary(results);
-    const failed = results.filter((r) => !r.ok).length;
-    if (failed > 0) {
-        process.exit(1);
+    await runInstall(collectionId, url, selectedComponents, scope);
+}
+function extractIdentifierFromUrl(url) {
+    // Extract u/<userId>/<slug> from URL path
+    const match = url.match(/\/api\/user-plugins\/([^/]+)\/([^/]+)/);
+    if (match) {
+        return `u/${match[1]}/${match[2]}`;
     }
+    return url;
 }
 main().catch((err) => {
     printError(`Unexpected error: ${err.message}`);

package/dist/install.d.ts

@@ -1,8 +1,3 @@
-interface CommandResult {
-    ok: boolean;
-    error?: string;
-}
-export declare function detectClaude(): string | null;
-export declare function addMarketplace(claudePath: string, url: string): CommandResult;
-export declare function installPlugin(claudePath: string, installName: string, scope?: 'user' | 'project' | 'local'): CommandResult;
-export {};
+import type { Scope } from './prompts.js';
+import type { FlatComponent } from './download.js';
+export declare function runInstall(identifier: string, apiUrl: string, components: FlatComponent[], scope: Scope): Promise<void>;

package/dist/install.js

@@ -1,41 +1,56 @@
-import { execFileSync } from 'node:child_process';
-export function detectClaude() {
-    try {
-        execFileSync('claude', ['--version'], { stdio: 'pipe' });
-        return 'claude';
+import { installComponent } from './download.js';
+import { readLock, writeLock, addCollection, componentKey } from './lock.js';
+import { print, printStep, printSuccess, printFail, printError, BOLD, RESET, DIM, GREEN, } from './output.js';
+export async function runInstall(identifier, apiUrl, components, scope) {
+    // Check if already installed
+    const lock = readLock(scope);
+    if (lock.collections[identifier]) {
+        printError(`Collection "${identifier}" is already installed.`);
+        print(`Run ${DIM}npx claudepluginhub update ${identifier}${RESET} to update.`);
+        process.exit(1);
     }
-    catch {
-        return null;
+    print('');
+    printStep(`Installing ${components.length} component(s) to ${scope} scope...`);
+    const installed = {};
+    let succeeded = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const component of components) {
+        const result = await installComponent(component, scope, true);
+        if (result.status === 'installed') {
+            const key = componentKey(component.source, component.sourcePath);
+            installed[key] = result.lock;
+            succeeded++;
+            printSuccess(`${component.componentName} (${component.type})`);
+        }
+        else if (result.status === 'skipped') {
+            skipped++;
+            printFail(`${component.componentName} (${component.type})`, 'already exists');
+        }
+        else {
+            failed++;
+            printFail(`${component.componentName} (${component.type})`, 'download failed');
+        }
     }
-}
-export function addMarketplace(claudePath, url) {
-    try {
-        execFileSync(claudePath, ['plugin', 'marketplace', 'add', url], {
-            stdio: 'pipe',
-            timeout: 30_000,
-        });
-        return { ok: true };
+    // Write lock file (even for partial success)
+    if (succeeded > 0) {
+        addCollection(lock, identifier, apiUrl, scope, installed);
+        writeLock(scope, lock);
     }
-    catch (err) {
-        const message = err.message;
-        // Marketplace already added is fine (idempotent)
-        if (message.includes('already') || message.includes('exists')) {
-            return { ok: true };
-        }
-        return { ok: false, error: message.split('\n')[0] };
+    print('');
+    if (failed === 0 && skipped === 0) {
+        print(`${GREEN}${BOLD}Done!${RESET} ${succeeded} component(s) installed.`);
     }
-}
-export function installPlugin(claudePath, installName, scope = 'project') {
-    try {
-        execFileSync(claudePath, ['plugin', 'install', installName, '--scope', scope], { stdio: 'pipe', timeout: 60_000 });
-        return { ok: true };
+    else {
+        const parts = [`${succeeded} installed`];
+        if (skipped > 0)
+            parts.push(`${skipped} skipped`);
+        if (failed > 0)
+            parts.push(`${failed} failed`);
+        print(`${BOLD}Done.${RESET} ${parts.join(', ')}.`);
     }
-    catch (err) {
-        const message = err.message;
-        // Already installed is fine (idempotent)
-        if (message.includes('already installed')) {
-            return { ok: true };
-        }
-        return { ok: false, error: message.split('\n')[0] };
+    print('');
+    if (failed > 0) {
+        process.exit(1);
     }
 }

package/dist/list.d.ts

@@ -0,0 +1 @@
+export declare function runList(): void;

package/dist/list.js

@@ -0,0 +1,39 @@
+import { readLock } from './lock.js';
+import { print, BOLD, RESET, DIM, CYAN, GREEN, YELLOW } from './output.js';
+const TYPE_COLORS = {
+    skill: GREEN,
+    command: CYAN,
+    agent: YELLOW,
+    hook: '\x1b[35m', // magenta
+    mcp: '\x1b[36m', // cyan
+    lsp: '\x1b[34m', // blue
+};
+function typeBadge(type) {
+    const color = TYPE_COLORS[type] ?? DIM;
+    return `${color}[${type}]${RESET}`;
+}
+export function runList() {
+    const scopes = ['user', 'project', 'local'];
+    let totalCollections = 0;
+    for (const scope of scopes) {
+        const lock = readLock(scope);
+        const collections = Object.values(lock.collections);
+        if (collections.length === 0)
+            continue;
+        totalCollections += collections.length;
+        print(`${BOLD}${scope}${RESET} scope:`);
+        for (const col of collections) {
+            const componentCount = Object.keys(col.components).length;
+            print(`  ${CYAN}${col.identifier}${RESET} ${DIM}(${componentCount} component(s))${RESET}`);
+            for (const comp of Object.values(col.components)) {
+                print(`    ${typeBadge(comp.type)} ${comp.componentName} ${DIM}${comp.source}${RESET}`);
+            }
+        }
+        print('');
+    }
+    if (totalCollections === 0) {
+        print(`No installed collections found.`);
+        print(`Run ${DIM}npx claudepluginhub <identifier>${RESET} to install.`);
+        print('');
+    }
+}

package/dist/lock.d.ts

@@ -0,0 +1,30 @@
+import type { Scope } from './prompts.js';
+export interface ComponentLock {
+    source: string;
+    type: string;
+    componentName: string;
+    sourcePath: string;
+    installedPath: string;
+    hash: string;
+    configFile: string | null;
+    configKeys: string[] | null;
+    configFragment: unknown | null;
+}
+export interface CollectionLock {
+    identifier: string;
+    apiUrl: string;
+    scope: Scope;
+    installedAt: string;
+    updatedAt: string;
+    components: Record<string, ComponentLock>;
+}
+export interface LockFile {
+    version: 1;
+    collections: Record<string, CollectionLock>;
+}
+export declare function getLockFilePath(scope: Scope): string;
+export declare function readLock(scope: Scope): LockFile;
+export declare function writeLock(scope: Scope, lock: LockFile): void;
+export declare function addCollection(lock: LockFile, identifier: string, apiUrl: string, scope: Scope, components: Record<string, ComponentLock>): LockFile;
+export declare function removeCollection(lock: LockFile, identifier: string): LockFile;
+export declare function componentKey(source: string, sourcePath: string): string;

package/dist/lock.js

@@ -0,0 +1,53 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export function getLockFilePath(scope) {
+    if (scope === 'user') {
+        return join(homedir(), '.claude', '.claudepluginhub-lock.json');
+    }
+    const filename = scope === 'local'
+        ? '.claudepluginhub-lock.local.json'
+        : '.claudepluginhub-lock.json';
+    return join(process.cwd(), '.claude', filename);
+}
+export function readLock(scope) {
+    const path = getLockFilePath(scope);
+    if (!existsSync(path)) {
+        return { version: 1, collections: {} };
+    }
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { version: 1, collections: {} };
+    }
+}
+export function writeLock(scope, lock) {
+    const path = getLockFilePath(scope);
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(lock, null, 2) + '\n');
+}
+export function addCollection(lock, identifier, apiUrl, scope, components) {
+    const now = new Date().toISOString();
+    const existing = lock.collections[identifier];
+    lock.collections[identifier] = {
+        identifier,
+        apiUrl,
+        scope,
+        installedAt: existing?.installedAt ?? now,
+        updatedAt: now,
+        components,
+    };
+    return lock;
+}
+export function removeCollection(lock, identifier) {
+    delete lock.collections[identifier];
+    return lock;
+}
+export function componentKey(source, sourcePath) {
+    return `${source}:${sourcePath}`;
+}

package/dist/prompts.d.ts

@@ -5,4 +5,5 @@ export interface SelectableItem {
     selected: boolean;
 }
 export declare function checkboxPrompt(title: string, items: SelectableItem[]): Promise<number[] | null>;
+export declare function confirmPrompt(message: string): Promise<boolean>;
 export declare function scopePrompt(defaultScope?: Scope): Promise<Scope | null>;

package/dist/prompts.js

@@ -82,6 +82,24 @@ export async function checkboxPrompt(title, items) {
         write(SHOW_CURSOR);
     }
 }
+export async function confirmPrompt(message) {
+    if (!isInteractive())
+        return true;
+    write(`${message} ${DIM}[y/N]${RESET} `);
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    try {
+        const key = await readKey();
+        const str = key.toString().toLowerCase();
+        write(str + '\n');
+        return str === 'y';
+    }
+    finally {
+        process.stdin.setRawMode(wasRaw ?? false);
+        process.stdin.pause();
+    }
+}
 const SCOPE_OPTIONS = [
     { value: 'user', label: 'User', hint: 'available across all projects' },
     {

package/dist/remove.d.ts

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

package/dist/remove.js

@@ -0,0 +1,117 @@
+import { rmSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { readLock, writeLock, removeCollection } from './lock.js';
+import { printStep, printSuccess, printError, print, BOLD, RESET, DIM } from './output.js';
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function removeConfigKeys(lock) {
+    if (!lock.configFile || !existsSync(lock.configFile))
+        return;
+    try {
+        const settings = JSON.parse(readFileSync(lock.configFile, 'utf-8'));
+        if (lock.type === 'hook' && lock.configFragment) {
+            // Remove hooks by deep equality
+            const hooks = settings.hooks;
+            if (hooks) {
+                const fragment = lock.configFragment;
+                for (const [event, handlers] of Object.entries(fragment)) {
+                    if (!Array.isArray(hooks[event]))
+                        continue;
+                    hooks[event] = hooks[event].filter((h) => !handlers.some((fh) => deepEqual(h, fh)));
+                    if (hooks[event].length === 0) {
+                        delete hooks[event];
+                    }
+                }
+                if (Object.keys(hooks).length === 0) {
+                    delete settings.hooks;
+                }
+            }
+        }
+        else if (lock.configKeys) {
+            // Remove by key path (mcpServers.x, lspServers.x)
+            for (const keyPath of lock.configKeys) {
+                const parts = keyPath.split('.');
+                if (parts.length === 2) {
+                    const [section, key] = parts;
+                    const obj = settings[section];
+                    if (obj) {
+                        delete obj[key];
+                        if (Object.keys(obj).length === 0) {
+                            delete settings[section];
+                        }
+                    }
+                }
+            }
+        }
+        writeFileSync(lock.configFile, JSON.stringify(settings, null, 2) + '\n');
+    }
+    catch {
+        // Settings file corrupted — skip cleanup
+    }
+}
+function isSafeRemovePath(targetPath) {
+    const resolved = resolve(targetPath);
+    const userBase = resolve(join(homedir(), '.claude'));
+    const projectBase = resolve(join(process.cwd(), '.claude'));
+    return (resolved.startsWith(userBase + sep) ||
+        resolved.startsWith(projectBase + sep));
+}
+function removeFiles(lock) {
+    if (lock.configFile) {
+        // Config-based component — remove config keys, not the settings file
+        removeConfigKeys(lock);
+        return;
+    }
+    if (!isSafeRemovePath(lock.installedPath)) {
+        printError(`Skipping unsafe remove path: ${lock.installedPath}`);
+        return;
+    }
+    if (!existsSync(lock.installedPath))
+        return;
+    try {
+        if (lock.type === 'skill') {
+            rmSync(lock.installedPath, { recursive: true, force: true });
+        }
+        else {
+            rmSync(lock.installedPath, { force: true });
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+export function removeComponentByLock(comp) {
+    removeFiles(comp);
+}
+export async function runRemove(identifier) {
+    // Try all scopes to find the collection
+    const scopes = ['project', 'local', 'user'];
+    let foundScope = null;
+    let foundCollection = null;
+    for (const scope of scopes) {
+        const lock = readLock(scope);
+        if (lock.collections[identifier]) {
+            foundScope = scope;
+            foundCollection = lock.collections[identifier];
+            break;
+        }
+    }
+    if (!foundScope || !foundCollection) {
+        printError(`Collection "${identifier}" not found in any lock file.`);
+        print(`Run ${DIM}npx claudepluginhub list${RESET} to see installed collections.`);
+        process.exit(1);
+    }
+    printStep(`Removing ${Object.keys(foundCollection.components).length} component(s)...`);
+    for (const [, comp] of Object.entries(foundCollection.components)) {
+        removeFiles(comp);
+        printSuccess(`${comp.componentName} (${comp.type})`);
+    }
+    const lock = readLock(foundScope);
+    removeCollection(lock, identifier);
+    writeLock(foundScope, lock);
+    print('');
+    print(`${BOLD}Removed${RESET} ${identifier}`);
+    print('');
+}

package/dist/update.d.ts

@@ -0,0 +1 @@
+export declare function runUpdate(identifier?: string): Promise<void>;

package/dist/update.js

@@ -0,0 +1,117 @@
+import { readLock, writeLock, componentKey } from './lock.js';
+import { fetchMarketplace, flattenComponents } from './fetch.js';
+import { installComponent } from './download.js';
+import { removeComponentByLock } from './remove.js';
+import { fetchDefaultBranch, fetchTree, findTreeSha, findBlobSha, } from './github.js';
+import { print, printSuccess, printFail, printError, BOLD, RESET, DIM, } from './output.js';
+async function getRemoteHash(component) {
+    const branch = await fetchDefaultBranch(component.source);
+    if (!branch)
+        return null;
+    const tree = await fetchTree(component.source, branch);
+    if (!tree)
+        return null;
+    if (component.type === 'skill') {
+        const dirPath = component.sourcePath.replace(/\/SKILL\.md$/, '');
+        return findTreeSha(tree, dirPath);
+    }
+    return findBlobSha(tree, component.sourcePath);
+}
+export async function runUpdate(identifier) {
+    const scopes = ['user', 'project', 'local'];
+    let found = false;
+    for (const scope of scopes) {
+        const lock = readLock(scope);
+        const collections = Object.values(lock.collections);
+        if (collections.length === 0)
+            continue;
+        for (const collection of collections) {
+            if (identifier && collection.identifier !== identifier)
+                continue;
+            found = true;
+            print(`${BOLD}Updating${RESET} ${collection.identifier}...`);
+            const manifest = await fetchMarketplace(collection.apiUrl);
+            if (!manifest) {
+                printError(`Failed to fetch manifest for ${collection.identifier}`);
+                continue;
+            }
+            const freshComponents = flattenComponents(manifest);
+            const freshKeys = new Set(freshComponents.map((c) => componentKey(c.source, c.sourcePath)));
+            const lockedKeys = new Set(Object.keys(collection.components));
+            const added = [];
+            const toCheck = [];
+            const removed = [];
+            for (const comp of freshComponents) {
+                const key = componentKey(comp.source, comp.sourcePath);
+                if (!lockedKeys.has(key)) {
+                    added.push(comp);
+                }
+                else {
+                    toCheck.push(comp);
+                }
+            }
+            for (const key of lockedKeys) {
+                if (!freshKeys.has(key)) {
+                    removed.push(key);
+                }
+            }
+            // Check hashes before downloading to avoid unnecessary re-downloads
+            const changed = [];
+            for (const comp of toCheck) {
+                const key = componentKey(comp.source, comp.sourcePath);
+                const existing = collection.components[key];
+                const remoteHash = await getRemoteHash(comp);
+                if (remoteHash && remoteHash !== existing.hash) {
+                    changed.push(comp);
+                }
+            }
+            if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+                printSuccess('Already up to date');
+                continue;
+            }
+            // Remove deleted components (including config cleanup)
+            for (const key of removed) {
+                const comp = collection.components[key];
+                removeComponentByLock(comp);
+                delete collection.components[key];
+                printSuccess(`Removed ${comp.componentName} (${comp.type})`);
+            }
+            // Add new components
+            for (const comp of added) {
+                const result = await installComponent(comp, scope, false);
+                if (result.status === 'installed') {
+                    const key = componentKey(comp.source, comp.sourcePath);
+                    collection.components[key] = result.lock;
+                    printSuccess(`Added ${comp.componentName} (${comp.type})`);
+                }
+                else {
+                    printFail(`${comp.componentName} (${comp.type})`, 'download failed');
+                }
+            }
+            // Re-download changed components: clean up old files/config, then reinstall
+            for (const comp of changed) {
+                const key = componentKey(comp.source, comp.sourcePath);
+                const existing = collection.components[key];
+                removeComponentByLock(existing);
+                const result = await installComponent(comp, scope, false);
+                if (result.status === 'installed') {
+                    collection.components[key] = result.lock;
+                    printSuccess(`Updated ${comp.componentName} (${comp.type})`);
+                }
+            }
+            collection.updatedAt = new Date().toISOString();
+            lock.collections[collection.identifier] = collection;
+            writeLock(scope, lock);
+        }
+    }
+    if (!found) {
+        if (identifier) {
+            printError(`Collection "${identifier}" not found.`);
+            print(`Run ${DIM}npx claudepluginhub list${RESET} to see installed collections.`);
+        }
+        else {
+            print('No collections installed. Nothing to update.');
+        }
+    }
+    print('');
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "claudepluginhub",
-  "version": "0.2.0",
-  "description": "Install Claude Code plugins from ClaudePluginHub",
+  "version": "0.3.0",
+  "description": "Install Claude Code components from ClaudePluginHub",
   "bin": {
-    "claudepluginhub": "./dist/index.js"
+    "claudepluginhub": "dist/index.js"
   },
   "type": "module",
   "engines": {