quiver-skill-manager 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# Quiver
+
+A local web UI and CLI for browsing, installing, and managing Claude Code skills.
+
+Quiver scans your local skills (`~/.claude/skills/`) and marketplace plugins, showing everything in one searchable interface with source-based colour coding.
+
+## Features
+
+- **Unified inventory** — local skills and marketplace plugins in one view
+- **Web UI** — tabs, search, drag-and-drop import, skill detail with file paths
+- **CLI** — list, add, remove, import, export skills from the terminal
+- **macOS app** — standalone Quiver.app bundle (~1.8MB)
+- **Launch on startup** — optional auto-start so your bookmark always works
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Launch the web UI
+node bin/quiver.js ui
+```
+
+Opens http://localhost:3456 in your browser.
+
+## CLI Usage
+
+```bash
+# List all skills
+node bin/quiver.js list
+
+# Add a skill (symlink)
+node bin/quiver.js add /path/to/my-skill
+
+# Add a skill (copy)
+node bin/quiver.js add /path/to/my-skill --copy
+
+# Remove a skill
+node bin/quiver.js remove my-skill
+
+# Export a skill as .zip
+node bin/quiver.js export my-skill -o ./exports
+
+# Import a skill from .zip
+node bin/quiver.js import ./my-skill.skill.zip
+```
+
+## Global Install
+
+```bash
+npm install -g .
+quiver ui
+```
+
+## Build macOS App
+
+```bash
+bash build/build-macos.sh
+```
+
+Creates `dist/Quiver.app` and `dist/Quiver.zip`.
+
+Requires Node.js on the machine — the app uses a shell launcher to find your Node installation.
+
+## How It Works
+
+Quiver reads skills from two locations:
+
+| Source | Path | Badge Colour |
+|--------|------|-------------|
+| Local | `~/.claude/skills/` | Indigo |
+| Marketplace | `~/.claude/plugins/marketplaces/*/plugins/*/` | Teal |
+
+Skills are `.md` files with optional YAML frontmatter for metadata (name, description, tags).
+
+## Tech Stack
+
+- Node.js + Express
+- Preact + HTM (CDN, no build step)
+- Commander.js (CLI)
+- esbuild (app bundling)
+- gray-matter (frontmatter parsing)
+
+## License
+
+MIT

package/bin/quiver.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "quiver-skill-manager",
+  "version": "0.1.0",
+  "description": "Manage Claude Code skills with a web UI and CLI",
+  "type": "module",
+  "bin": {
+    "quiver": "./bin/quiver.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "ui/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scribblesvurt-crypto/quiver.git"
+  },
+  "homepage": "https://skillquiver.com",
+  "scripts": {
+    "start": "node src/cli.js",
+    "ui": "node src/cli.js ui"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "skill-manager",
+    "quiver",
+    "cli"
+  ],
+  "author": "Sam",
+  "license": "MIT",
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "commander": "^13.1.0",
+    "express": "^5.1.0",
+    "gray-matter": "^4.0.3",
+    "multer": "^1.4.5-lts.2",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,307 @@
+import { program } from 'commander';
+import { listAll, getSkillContent } from './core/inventory.js';
+import { addSkill } from './core/add.js';
+import { removeSkill } from './core/remove.js';
+import { exportSkill, exportAll } from './core/export.js';
+import { importSkill } from './core/import.js';
+import { loadConfig, getConfigValue, setConfigValue } from './core/config.js';
+import { syncInit, syncSetRemote, syncPush, syncPull, syncStatus } from './core/sync/index.js';
+import { listAvailablePlugins, listCategories, listSources, setSourceEnabled } from './core/registry.js';
+import { startServer } from './server.js';
+
+program
+  .name('quiver')
+  .description('Quiver — manage Claude Code skills')
+  .version('0.1.0');
+
+// --- list ---
+program
+  .command('list')
+  .alias('ls')
+  .description('List all installed skills')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const skills = listAll();
+    if (skills.length === 0) {
+      console.log('No skills found.');
+      return;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(skills, null, 2));
+      return;
+    }
+    const maxName = Math.max(...skills.map(s => s.name.length), 4);
+    const maxSource = Math.max(...skills.map(s => (s.pluginName || s.source).length), 6);
+    console.log(`${'NAME'.padEnd(maxName)}  ${'SOURCE'.padEnd(maxSource)}  ${'FILES'}  DESCRIPTION`);
+    console.log(`${'─'.repeat(maxName)}  ${'─'.repeat(maxSource)}  ${'─────'}  ${'─'.repeat(40)}`);
+    for (const s of skills) {
+      const source = s.pluginName || s.source;
+      const desc = s.description.length > 50 ? s.description.slice(0, 47) + '...' : s.description;
+      console.log(`${s.name.padEnd(maxName)}  ${source.padEnd(maxSource)}  ${String(s.fileCount).padStart(5)}  ${desc}`);
+    }
+  });
+
+// --- add ---
+program
+  .command('add <path>')
+  .description('Add a skill to ~/.claude/skills/ (symlink by default)')
+  .option('--copy', 'Copy instead of symlink')
+  .action((path, opts) => {
+    try {
+      const name = addSkill(path, { copy: opts.copy });
+      console.log(`Added skill: ${name}`);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+// --- remove ---
+program
+  .command('remove <name>')
+  .alias('rm')
+  .description('Remove a skill from ~/.claude/skills/')
+  .action((name) => {
+    try {
+      removeSkill(name);
+      console.log(`Removed skill: ${name}`);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+// --- export ---
+program
+  .command('export <name>')
+  .description('Export a skill as a .skill.zip')
+  .option('--all', 'Export all skills')
+  .option('-o, --output <dir>', 'Output directory', '.')
+  .action((name, opts) => {
+    try {
+      if (opts.all) {
+        const files = exportAll(opts.output);
+        console.log(`Exported ${files.length} skills to ${opts.output}`);
+      } else {
+        const outPath = exportSkill(name, opts.output);
+        console.log(`Exported: ${outPath}`);
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+// --- import ---
+program
+  .command('import <zip>')
+  .description('Import a skill from a .zip file')
+  .action((zip) => {
+    try {
+      const name = importSkill(zip);
+      console.log(`Imported skill: ${name}`);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+// --- ui ---
+program
+  .command('ui')
+  .description('Launch the web UI')
+  .option('-p, --port <port>', 'Port number', '3456')
+  .action((opts) => {
+    startServer(parseInt(opts.port));
+  });
+
+// --- config ---
+program
+  .command('config [key] [value]')
+  .description('Get or set config values')
+  .action((key, value) => {
+    if (!key) {
+      console.log(JSON.stringify(loadConfig(), null, 2));
+    } else if (value === undefined) {
+      console.log(getConfigValue(key) ?? '(not set)');
+    } else {
+      setConfigValue(key, value);
+      console.log(`Set ${key} = ${value}`);
+    }
+  });
+
+// --- browse ---
+program
+  .command('browse')
+  .description('Browse available marketplace plugins')
+  .option('--category <cat>', 'Filter by category')
+  .option('--search <term>', 'Search plugins')
+  .option('--json', 'Output as JSON')
+  .option('--categories', 'List categories only')
+  .option('--sources', 'List marketplace sources and their status')
+  .option('--enable <id>', 'Enable a marketplace source')
+  .option('--disable <id>', 'Disable a marketplace source')
+  .action(async (opts) => {
+    if (opts.sources) {
+      const sources = listSources();
+      console.log('Marketplace sources:\n');
+      for (const s of sources) {
+        const status = s.enabled ? '[ON] ' : '[OFF]';
+        console.log(`  ${status} ${s.id}`);
+        console.log(`        ${s.description}`);
+      }
+      console.log('\nUse --enable <id> or --disable <id> to toggle.');
+      return;
+    }
+
+    if (opts.enable) {
+      setSourceEnabled(opts.enable, true);
+      console.log(`Enabled: ${opts.enable}`);
+      return;
+    }
+
+    if (opts.disable) {
+      setSourceEnabled(opts.disable, false);
+      console.log(`Disabled: ${opts.disable}`);
+      return;
+    }
+
+    if (opts.categories) {
+      const cats = await listCategories();
+      if (cats.length === 0) {
+        console.log('No marketplaces found. Add one with: claude /plugin marketplace add anthropics/claude-plugins-official');
+        return;
+      }
+      for (const c of cats) {
+        console.log(`  ${c.name} (${c.count})`);
+      }
+      return;
+    }
+
+    const plugins = await listAvailablePlugins({ search: opts.search, category: opts.category });
+    if (plugins.length === 0) {
+      console.log('No plugins found.');
+      return;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(plugins, null, 2));
+      return;
+    }
+
+    const maxName = Math.max(...plugins.map(p => p.name.length), 4);
+    const maxCat = Math.max(...plugins.map(p => (p.category || '—').length), 8);
+    console.log(`${'NAME'.padEnd(maxName)}  ${'CATEGORY'.padEnd(maxCat)}  ${'STATUS'}    DESCRIPTION`);
+    console.log(`${'─'.repeat(maxName)}  ${'─'.repeat(maxCat)}  ${'─'.repeat(9)}  ${'─'.repeat(40)}`);
+    for (const p of plugins) {
+      const cat = (p.category || '—').padEnd(maxCat);
+      const status = p.installed ? 'installed' : 'available';
+      const desc = p.description.length > 50 ? p.description.slice(0, 47) + '...' : p.description;
+      console.log(`${p.name.padEnd(maxName)}  ${cat}  ${status.padEnd(9)}  ${desc}`);
+    }
+    console.log(`\n${plugins.length} plugins (${plugins.filter(p => p.installed).length} installed)`);
+  });
+
+// --- sync ---
+const sync = program.command('sync').description('Sync skills across machines');
+
+sync
+  .command('init')
+  .description('Initialize sync (creates git repo in ~/.quiver/sync/)')
+  .action(() => {
+    try {
+      const result = syncInit();
+      console.log(result.message);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+sync
+  .command('remote <url>')
+  .description('Set the git remote URL')
+  .action((url) => {
+    try {
+      const result = syncSetRemote(url);
+      if (!result.ok) { console.error(`Error: ${result.error}`); process.exit(1); }
+      console.log(result.message);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+sync
+  .command('push')
+  .description('Push local skills to remote')
+  .action(() => {
+    try {
+      const result = syncPush();
+      if (!result.ok) { console.error(`Error: ${result.error}`); process.exit(1); }
+      console.log(result.message);
+      if (result.changes) {
+        for (const s of result.changes.added || []) console.log(`  + ${s}`);
+        for (const s of result.changes.modified || []) console.log(`  ~ ${s}`);
+        for (const s of result.changes.removed || []) console.log(`  - ${s}`);
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+sync
+  .command('pull')
+  .description('Pull skills from remote')
+  .action(() => {
+    try {
+      const result = syncPull();
+      if (!result.ok) { console.error(`Error: ${result.error}`); process.exit(1); }
+      console.log(result.message);
+      if (result.changes) {
+        for (const s of result.changes.added || []) console.log(`  + ${s}`);
+        for (const s of result.changes.modified || []) console.log(`  ~ ${s}`);
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+sync
+  .command('status')
+  .description('Show sync status')
+  .action(() => {
+    try {
+      const status = syncStatus();
+      if (!status.initialized) {
+        console.log('Sync not initialized. Run "quiver sync init" to get started.');
+        return;
+      }
+      console.log(`Backend:  ${status.backend}`);
+      console.log(`Remote:   ${status.remote || '(none)'}`);
+      console.log(`Last sync: ${status.lastSync || 'never'}`);
+
+      const { added, modified, removed } = status.localChanges;
+      const localTotal = added.length + modified.length + removed.length;
+
+      if (localTotal === 0 && status.remoteChanges === 0) {
+        console.log('\nEverything up to date.');
+      } else {
+        if (localTotal > 0) {
+          console.log(`\nLocal changes (${localTotal}):`);
+          for (const s of added) console.log(`  + ${s} (new)`);
+          for (const s of modified) console.log(`  ~ ${s} (modified)`);
+          for (const s of removed) console.log(`  - ${s} (removed)`);
+        }
+        if (status.remoteChanges > 0) {
+          console.log(`\nRemote: ${status.remoteChanges} new commit${status.remoteChanges !== 1 ? 's' : ''} to pull.`);
+        }
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/core/add.js

@@ -0,0 +1,33 @@
+import { existsSync, symlinkSync, cpSync, readFileSync } from 'fs';
+import { join, resolve, basename } from 'path';
+import { SKILLS_DIR, ensureDirs } from './paths.js';
+
+export function addSkill(sourcePath, opts = {}) {
+  ensureDirs();
+  const absPath = resolve(sourcePath);
+
+  if (!existsSync(absPath)) {
+    throw new Error(`Path not found: ${absPath}`);
+  }
+
+  // Check for SKILL.md
+  const skillFile = join(absPath, 'SKILL.md');
+  if (!existsSync(skillFile)) {
+    throw new Error(`No SKILL.md found in ${absPath}. Skills must contain a SKILL.md file.`);
+  }
+
+  const dirName = basename(absPath);
+  const target = join(SKILLS_DIR, dirName);
+
+  if (existsSync(target)) {
+    throw new Error(`Skill "${dirName}" already exists in ~/.claude/skills/`);
+  }
+
+  if (opts.copy) {
+    cpSync(absPath, target, { recursive: true });
+  } else {
+    symlinkSync(absPath, target, 'dir');
+  }
+
+  return dirName;
+}

package/src/core/config.js

@@ -0,0 +1,48 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { CONFIG_FILE, ensureDirs } from './paths.js';
+
+const DEFAULTS = {
+  port: 3456,
+  sync: {
+    backend: 'local',
+    remote: null
+  }
+};
+
+export function loadConfig() {
+  ensureDirs();
+  try {
+    const raw = readFileSync(CONFIG_FILE, 'utf-8');
+    const saved = JSON.parse(raw);
+    return {
+      ...DEFAULTS,
+      ...saved,
+      sync: { ...DEFAULTS.sync, ...(saved.sync || {}) }
+    };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function saveConfig(config) {
+  ensureDirs();
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+}
+
+export function getConfigValue(key) {
+  const config = loadConfig();
+  return key.split('.').reduce((obj, k) => obj?.[k], config);
+}
+
+export function setConfigValue(key, value) {
+  const config = loadConfig();
+  const keys = key.split('.');
+  let obj = config;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (typeof obj[keys[i]] !== 'object') obj[keys[i]] = {};
+    obj = obj[keys[i]];
+  }
+  obj[keys[keys.length - 1]] = value;
+  saveConfig(config);
+  return config;
+}

package/src/core/export.js

@@ -0,0 +1,48 @@
+import AdmZip from 'adm-zip';
+import { join, resolve, relative } from 'path';
+import { readdirSync, statSync } from 'fs';
+import { getSkill, listSkills } from './inventory.js';
+
+const SENSITIVE_PATTERNS = [/^\.env/, /^\.git\//, /^node_modules\//, /^\.DS_Store$/];
+
+function walkFiltered(dir, base = '') {
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (SENSITIVE_PATTERNS.some(p => p.test(rel) || p.test(entry.name))) continue;
+    if (entry.isDirectory()) {
+      results.push(...walkFiltered(join(dir, entry.name), rel));
+    } else {
+      results.push({ rel, abs: join(dir, entry.name) });
+    }
+  }
+  return results;
+}
+
+export function exportSkill(name, outputDir = '.') {
+  const skill = getSkill(name);
+  if (!skill) {
+    throw new Error(`Skill "${name}" not found`);
+  }
+
+  const zip = new AdmZip();
+  const files = walkFiltered(skill.path);
+  for (const file of files) {
+    const dir = file.rel.includes('/') ? file.rel.substring(0, file.rel.lastIndexOf('/')) : '';
+    zip.addLocalFile(file.abs, dir);
+  }
+
+  const outPath = resolve(outputDir, `${skill.dirName}.skill.zip`);
+  zip.writeZip(outPath);
+  return outPath;
+}
+
+export function exportAll(outputDir = '.') {
+  const skills = listSkills();
+  const paths = [];
+  for (const skill of skills) {
+    paths.push(exportSkill(skill.dirName, outputDir));
+  }
+  return paths;
+}

package/src/core/import.js

@@ -0,0 +1,57 @@
+import AdmZip from 'adm-zip';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve, basename } from 'path';
+import matter from 'gray-matter';
+import { SKILLS_DIR, ensureDirs } from './paths.js';
+
+export function importSkill(zipPath) {
+  ensureDirs();
+  const absPath = resolve(zipPath);
+
+  if (!existsSync(absPath)) {
+    throw new Error(`File not found: ${absPath}`);
+  }
+
+  const zip = new AdmZip(absPath);
+  const entries = zip.getEntries();
+
+  // Check for SKILL.md in the zip
+  const skillEntry = entries.find(e => e.entryName === 'SKILL.md' || e.entryName.endsWith('/SKILL.md'));
+  if (!skillEntry) {
+    throw new Error('Zip does not contain a SKILL.md file');
+  }
+
+  // Determine skill name from frontmatter or zip filename
+  let skillName;
+  try {
+    const content = skillEntry.getData().toString('utf-8');
+    const parsed = matter(content);
+    skillName = parsed.data.name;
+  } catch {
+    // Fall through to filename
+  }
+
+  if (!skillName) {
+    skillName = basename(absPath, '.skill.zip').replace('.zip', '');
+  }
+
+  // Sanitize skill name to prevent path traversal
+  skillName = skillName.replace(/[/\\]/g, '-').replace(/\.\./g, '');
+  if (!skillName || skillName.startsWith('.')) throw new Error('Invalid skill name in zip');
+
+  const target = join(SKILLS_DIR, skillName);
+  if (existsSync(target)) {
+    throw new Error(`Skill "${skillName}" already exists. Remove it first.`);
+  }
+
+  // Zip slip protection: verify no entries escape the target directory
+  for (const entry of entries) {
+    const resolved = resolve(target, entry.entryName);
+    if (!resolved.startsWith(target + '/') && resolved !== target) {
+      throw new Error('Zip contains unsafe path: ' + entry.entryName);
+    }
+  }
+
+  zip.extractAllTo(target, true);
+  return skillName;
+}