moving
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled

This commit is contained in:
Oleg Maslov
2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions

View File

@@ -0,0 +1,100 @@
/**
* Waggle Marketplace — Package Category Taxonomy
*
* Defines the canonical set of categories for marketplace packages
* and provides auto-categorization based on name + description keywords.
*/
import type { MarketplaceDB } from './db.js';
export const PACKAGE_CATEGORIES = [
{ id: 'marketing', name: 'Marketing', icon: '\u{1F4E2}', description: 'Campaign planning, SEO, content marketing, social media' },
{ id: 'knowledge', name: 'Knowledge & Research', icon: '\u{1F52C}', description: 'Research, analysis, literature review, fact-checking' },
{ id: 'sales', name: 'Sales & CRM', icon: '\u{1F3AF}', description: 'Lead research, outreach, pipeline management, proposals' },
{ id: 'social', name: 'Social Presence', icon: '\u{1F4F1}', description: 'Social media management, community, content scheduling' },
{ id: 'coding', name: 'Coding & Development', icon: '\u{1F4BB}', description: 'Code generation, review, debugging, testing, DevOps' },
{ id: 'security', name: 'Security', icon: '\u{1F512}', description: 'Security scanning, vulnerability assessment, compliance' },
{ id: 'documents', name: 'Document Creation', icon: '\u{1F4C4}', description: 'Writing, editing, formatting, PDF, DOCX generation' },
{ id: 'design', name: 'Design', icon: '\u{1F3A8}', description: 'UI/UX, graphics, prototyping, design systems' },
{ id: 'applications', name: 'Applications', icon: '\u{1F9E9}', description: 'App building, web development, deployment' },
{ id: 'data', name: 'Data & Analytics', icon: '\u{1F4CA}', description: 'Data analysis, visualization, SQL, spreadsheets' },
{ id: 'communication', name: 'Communication', icon: '\u{1F4AC}', description: 'Email, Slack, Teams, Discord, messaging' },
{ id: 'project-management', name: 'Project Management', icon: '\u{1F4CB}', description: 'Task tracking, planning, Jira, Linear, Asana' },
{ id: 'finance', name: 'Finance', icon: '\u{1F4B0}', description: 'Accounting, budgets, invoicing, financial analysis' },
{ id: 'legal', name: 'Legal', icon: '\u{2696}\u{FE0F}', description: 'Contract review, compliance, legal research' },
{ id: 'hr', name: 'Human Resources', icon: '\u{1F465}', description: 'Hiring, onboarding, performance reviews, policies' },
{ id: 'ai-ml', name: 'AI & Machine Learning', icon: '\u{1F916}', description: 'Model training, evaluation, prompt engineering' },
{ id: 'education', name: 'Education', icon: '\u{1F4DA}', description: 'Teaching, tutoring, curriculum, learning materials' },
{ id: 'content', name: 'Content Creation', icon: '\u{270D}\u{FE0F}', description: 'Blog posts, newsletters, copywriting, editing' },
{ id: 'devops', name: 'DevOps & Infrastructure', icon: '\u{1F3D7}\u{FE0F}', description: 'CI/CD, Docker, Kubernetes, cloud infrastructure' },
{ id: 'integration', name: 'Integration & Connectors', icon: '\u{1F517}', description: 'API connectors, webhooks, data pipelines' },
{ id: 'productivity', name: 'Productivity', icon: '\u{26A1}', description: 'Task automation, time management, workflow optimization' },
{ id: 'general', name: 'General', icon: '\u{1F4E6}', description: 'General-purpose skills and utilities' },
] as const;
export type PackageCategoryId = (typeof PACKAGE_CATEGORIES)[number]['id'];
/**
* Auto-categorize a package based on name + description keywords.
*
* Rules are ordered from most-specific to least-specific to avoid
* false positives (e.g. "pipeline" must match devops before sales,
* "webhook" must match integration before "web" matches applications).
*/
export function categorizePackage(name: string, description: string): string {
const text = `${name} ${description}`.toLowerCase();
// --- Highly specific categories first (few false positives) ---
if (/financ|budget|invoice|accounting|tax\b/.test(text)) return 'finance';
if (/legal|contract|complian|lawyer|regulat/.test(text)) return 'legal';
if (/\bhr\b|hiring|recruit|onboard|employee/.test(text)) return 'hr';
if (/devops|ci.?cd|docker|kubernetes|infra|cloud|aws/.test(text)) return 'devops';
if (/security|vuln|pentest|cve/.test(text)) return 'security';
// --- Domain categories (medium specificity) ---
if (/market|seo|campaign|brand|advertis/.test(text)) return 'marketing';
if (/research|knowledge|paper|literature|academic/.test(text)) return 'knowledge';
if (/sales|lead\b|crm|outreach|prospect/.test(text)) return 'sales';
if (/social|twitter|instagram|linkedin|facebook|tiktok/.test(text)) return 'social';
if (/email|slack|discord|messag/.test(text)) return 'communication';
if (/webhook|integrat|connect|pipe(?:line)?/.test(text)) return 'integration';
if (/jira|linear|asana|trello|sprint|project.?manag/.test(text)) return 'project-management';
if (/educat|teach|tutor|learn|course|curriculum/.test(text)) return 'education';
// --- Broad technical categories (use word boundaries to reduce false positives) ---
if (/\bcode\b|develop|debug|\btest\b|\bgit\b|\brepo\b|typescript|python|rust/.test(text)) return 'coding';
if (/\bai\b|\bml\b|\bllm\b|prompt.?engineer|model.?train|embed/.test(text)) return 'ai-ml';
if (/document|pdf|docx|\bword\b|\bwrite\b|format|template/.test(text)) return 'documents';
if (/design|\bui\b|\bux\b|figma|css|tailwind|graphic/.test(text)) return 'design';
if (/data|analyt|sql|database|spreadsheet|chart|viz/.test(text)) return 'data';
if (/blog|newsletter|copy|content|edit|article/.test(text)) return 'content';
if (/\bapp\b|\bweb\b|deploy|build|frontend|backend|\bapi\b/.test(text)) return 'applications';
if (/\btask\b|automat|workflow|efficienc|productiv/.test(text)) return 'productivity';
return 'general';
}
/**
* Re-categorize all packages in the database using the keyword-based
* categorizer. Call this during sync and on startup to ensure categories
* stay consistent.
*/
export function recategorizeAll(db: MarketplaceDB): { updated: number; total: number } {
// Access raw DB through the public interface: search all packages
const allResults = db.search({ limit: 10000 });
let updated = 0;
for (const pkg of allResults.packages) {
const newCategory = categorizePackage(pkg.name, pkg.description || '');
if (newCategory !== pkg.category) {
// Use upsertPackage to update just the category
db.upsertPackage({
name: pkg.name,
source_id: pkg.source_id,
category: newCategory,
});
updated++;
}
}
return { updated, total: allResults.packages.length };
}

View File

@@ -0,0 +1,367 @@
/**
* Waggle Marketplace — Cisco AI Defense Skill Scanner Adapter
*
* Wraps the Cisco `skill-scanner` CLI tool (Python) as an optional
* deep-analysis engine for marketplace security scanning.
*
* The scanner is OPTIONAL — Waggle works without it. When not installed,
* the SecurityGate falls back to its built-in JavaScript heuristics.
*
* Install the scanner: pip install cisco-ai-skill-scanner
* Reference: https://github.com/cisco-ai-defense/skill-scanner
*/
import { execFile as execFileCb } from 'child_process';
import { writeFileSync, unlinkSync, mkdirSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
import { randomBytes } from 'crypto';
import { promisify } from 'util';
const defaultExecFile = promisify(execFileCb);
/** Injectable executor for subprocess calls (overridable for tests) */
type ExecFileFn = (cmd: string, args: string[], opts: { timeout: number }) =>
Promise<{ stdout: string; stderr: string }>;
let _execFile: ExecFileFn = defaultExecFile;
/**
* Override the subprocess executor (for testing).
* Pass `null` to restore the default.
*/
export function setExecFile(fn: ExecFileFn | null): void {
_execFile = fn ?? defaultExecFile;
}
// ─── Types ──────────────────────────────────────────────────────────
export interface CiscoScanIssue {
severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
type: string;
message: string;
line?: number;
rule_id?: string;
description?: string;
location?: string;
}
export interface CiscoScanResult {
/** Whether the scan passed (no critical/high findings) */
passed: boolean;
/** Security score 0-100 (100 = clean) */
score: number;
/** Individual findings from the scanner */
issues: CiscoScanIssue[];
/** Version of the Cisco scanner used */
scannerVersion: string;
/** Time taken for the scan in milliseconds */
scanDuration: number;
}
/**
* Shape of a rejected {@link ExecFileFn} call. `child_process.execFile`
* rejects with an Error augmented with `code` (`'ENOENT'` or a numeric exit
* code), `killed` (true on timeout), and the captured `stdout`/`stderr`.
*/
interface ExecFailure {
code?: string | number;
killed?: boolean;
stdout?: string;
stderr?: string;
message?: string;
}
/** Narrow an unknown caught value into an {@link ExecFailure} view. */
function asExecFailure(err: unknown): ExecFailure {
return (typeof err === 'object' && err !== null) ? err as ExecFailure : {};
}
/** Sentinel result returned when the scanner is not installed */
const SCANNER_NOT_AVAILABLE: CiscoScanResult = {
passed: true,
score: -1,
issues: [],
scannerVersion: 'not_installed',
scanDuration: 0,
};
// Scanner availability check timeout (5 seconds)
const VERSION_TIMEOUT_MS = 5_000;
// Scan execution timeout (30 seconds per file)
const SCAN_TIMEOUT_MS = 30_000;
// Cache the availability check for 60 seconds to avoid repeated subprocess calls
let _availabilityCache: { available: boolean; version: string; checkedAt: number } | null = null;
const AVAILABILITY_CACHE_TTL_MS = 60_000;
// ─── Public API ─────────────────────────────────────────────────────
/**
* Check if the Cisco skill-scanner CLI is installed and available.
* Tries `skill-scanner --version` first, then `python -m skill_scanner --version`.
* Results are cached for 60 seconds.
*/
export async function isCiscoScannerAvailable(): Promise<boolean> {
// Return cached result if still fresh
if (_availabilityCache && (Date.now() - _availabilityCache.checkedAt) < AVAILABILITY_CACHE_TTL_MS) {
return _availabilityCache.available;
}
// Try the direct CLI command first
try {
const { stdout } = await _execFile('skill-scanner', ['--version'], {
timeout: VERSION_TIMEOUT_MS,
});
const version = stdout.trim() || 'unknown';
_availabilityCache = { available: true, version, checkedAt: Date.now() };
return true;
} catch {
// Direct CLI not found — try Python module invocation
}
try {
const { stdout } = await _execFile('python', ['-m', 'skill_scanner', '--version'], {
timeout: VERSION_TIMEOUT_MS,
});
const version = stdout.trim() || 'unknown';
_availabilityCache = { available: true, version, checkedAt: Date.now() };
return true;
} catch {
// Also try python3 for Linux/macOS
}
try {
const { stdout } = await _execFile('python3', ['-m', 'skill_scanner', '--version'], {
timeout: VERSION_TIMEOUT_MS,
});
const version = stdout.trim() || 'unknown';
_availabilityCache = { available: true, version, checkedAt: Date.now() };
return true;
} catch {
// Scanner not available
}
_availabilityCache = { available: false, version: '', checkedAt: Date.now() };
return false;
}
/**
* Get the cached version string of the Cisco scanner, or 'not_installed'.
*/
export function getCiscoScannerVersion(): string {
return _availabilityCache?.version || 'not_installed';
}
/**
* Reset the availability cache (useful for tests).
*/
export function resetAvailabilityCache(): void {
_availabilityCache = null;
}
/**
* Scan skill content using the Cisco AI Defense skill-scanner.
*
* 1. Writes content to a temp file
* 2. Runs: skill-scanner scan <tempfile> --format json
* 3. Parses the JSON output into CiscoScanResult
* 4. Cleans up the temp file
*
* If the scanner is not available, returns a sentinel result with
* scannerVersion='not_installed' and score=-1.
*/
export async function ciscoScan(content: string, filename: string): Promise<CiscoScanResult> {
const startTime = Date.now();
// Check availability first
const available = await isCiscoScannerAvailable();
if (!available) {
return { ...SCANNER_NOT_AVAILABLE };
}
// Write content to a temp file
const tempDir = join(tmpdir(), 'waggle-cisco-scan');
mkdirSync(tempDir, { recursive: true });
const safeName = filename.replace(/[^a-zA-Z0-9._-]/g, '_');
const tempFile = join(tempDir, `${safeName}-${randomBytes(4).toString('hex')}.md`);
try {
writeFileSync(tempFile, content, 'utf-8');
// Build the command and args
const args = ['scan', tempFile, '--format', 'json'];
// Try the direct CLI first, fall back to python module
let stdout: string;
let exitCode = 0;
try {
const result = await _execFile('skill-scanner', args, {
timeout: SCAN_TIMEOUT_MS,
});
stdout = result.stdout;
} catch (err: unknown) {
const execErr = asExecFailure(err);
// skill-scanner exits with code 1 when findings are found — that's not an error
if (execErr.code === 'ENOENT' || execErr.killed) {
// CLI not found or timed out — try python module
try {
const result = await _execFile('python', ['-m', 'skill_scanner', ...args], {
timeout: SCAN_TIMEOUT_MS,
});
stdout = result.stdout;
} catch (pyErr: unknown) {
const pyExecErr = asExecFailure(pyErr);
if (pyExecErr.stdout) {
stdout = pyExecErr.stdout;
exitCode = typeof pyExecErr.code === 'number' ? pyExecErr.code : 1;
} else {
// Try python3 as last resort
try {
const result = await _execFile('python3', ['-m', 'skill_scanner', ...args], {
timeout: SCAN_TIMEOUT_MS,
});
stdout = result.stdout;
} catch (py3Err: unknown) {
const py3ExecErr = asExecFailure(py3Err);
if (py3ExecErr.stdout) {
stdout = py3ExecErr.stdout;
exitCode = typeof py3ExecErr.code === 'number' ? py3ExecErr.code : 1;
} else {
return {
passed: true,
score: -1,
issues: [],
scannerVersion: getCiscoScannerVersion(),
scanDuration: Date.now() - startTime,
};
}
}
}
}
} else if (execErr.stdout) {
// Process exited with non-zero but produced output (findings found)
stdout = execErr.stdout;
exitCode = typeof execErr.code === 'number' ? execErr.code : 1;
} else {
// Unexpected error
console.warn(`[cisco-scanner] Scan failed: ${execErr.message || String(err)}`);
return {
passed: true,
score: -1,
issues: [],
scannerVersion: getCiscoScannerVersion(),
scanDuration: Date.now() - startTime,
};
}
}
// Parse the JSON output
const result = parseJsonOutput(stdout, exitCode);
result.scanDuration = Date.now() - startTime;
result.scannerVersion = getCiscoScannerVersion();
return result;
} finally {
// Clean up temp file
try {
unlinkSync(tempFile);
} catch { /* ignore cleanup failures */ }
}
}
// ─── Internal Helpers ───────────────────────────────────────────────
/**
* Parse the JSON output from skill-scanner into a CiscoScanResult.
*
* The scanner outputs a JSON object with:
* - verdict: 'PASS' | 'FAIL'
* - findings: Array of { rule_id, severity, category, title, description, line, location }
* - summary: string
* - score: number (if present)
*/
function parseJsonOutput(stdout: string, exitCode: number): CiscoScanResult {
const issues: CiscoScanIssue[] = [];
let passed = true;
let score = 100;
if (!stdout || !stdout.trim()) {
return { passed: true, score: 100, issues: [], scannerVersion: '', scanDuration: 0 };
}
try {
const data = JSON.parse(stdout.trim());
// Extract verdict
if (data.verdict) {
const verdict = data.verdict.toUpperCase();
passed = verdict === 'PASS' || verdict === 'CLEAN';
} else {
// No explicit verdict — infer from exit code
passed = exitCode === 0;
}
// Extract score if provided
if (typeof data.score === 'number') {
score = data.score;
} else if (typeof data.security_score === 'number') {
score = data.security_score;
}
// Extract findings
const rawFindings = data.findings || data.issues || data.results || [];
if (Array.isArray(rawFindings)) {
for (const f of rawFindings) {
const severity = normalizeSeverity(f.severity || f.level);
issues.push({
severity,
type: f.category || f.type || f.rule_id || 'unknown',
message: f.title || f.message || f.description || '',
line: typeof f.line === 'number' ? f.line : undefined,
rule_id: f.rule_id || f.id,
description: f.description || f.details,
location: f.location,
});
// Adjust score based on severity if no explicit score
if (typeof data.score !== 'number' && typeof data.security_score !== 'number') {
switch (severity) {
case 'critical': score = Math.min(score, 0); break;
case 'high': score = Math.min(score, 25); break;
case 'medium': score = Math.min(score, 60); break;
case 'low': score = Math.min(score, 85); break;
}
}
}
}
// If verdict is FAIL but no findings, add a generic finding
if (!passed && issues.length === 0) {
issues.push({
severity: 'high',
type: 'verdict_fail',
message: data.summary || 'Cisco scanner returned FAIL verdict without specific findings.',
});
score = Math.min(score, 25);
}
} catch (parseErr) {
// JSON parse failed — treat as unparseable output
console.warn(`[cisco-scanner] Failed to parse JSON output: ${(parseErr as Error).message}`);
return { passed: true, score: -1, issues: [], scannerVersion: '', scanDuration: 0 };
}
return { passed, score, issues, scannerVersion: '', scanDuration: 0 };
}
function normalizeSeverity(level: string | undefined): CiscoScanIssue['severity'] {
const normalized = (level || '').toLowerCase().trim();
if (normalized === 'critical' || normalized === 'error') return 'critical';
if (normalized === 'high') return 'high';
if (normalized === 'medium' || normalized === 'warning') return 'medium';
if (normalized === 'low') return 'low';
if (normalized === 'info' || normalized === 'none') return 'info';
return 'medium';
}

View File

@@ -0,0 +1,435 @@
#!/usr/bin/env node
/**
* Waggle Marketplace — CLI Interface
*
* Usage:
* waggle-market search <query> Search packages
* waggle-market install <name|id> Install a package
* waggle-market install-pack <slug> Install a capability pack
* waggle-market uninstall <name|id> Uninstall a package
* waggle-market list List installed packages
* waggle-market packs List available packs
* waggle-market sources List marketplace sources
* waggle-market sync [--source=x] Sync from live sources
* waggle-market info <name|id> Show package details
*/
import { MarketplaceDB } from './db.js';
import { MarketplaceInstaller } from './installer.js';
import { MarketplaceSync } from './sync.js';
import { SecurityGate } from './security.js';
import type { InstallationType, ScannedPackage } from './types.js';
const args = process.argv.slice(2);
const command = args[0];
const HELP_COMMANDS = new Set([undefined, 'help', '--help', '-h']);
const KNOWN_COMMANDS = new Set([
'search',
's',
'install',
'i',
'install-pack',
'ip',
'uninstall',
'u',
'list',
'ls',
'packs',
'sources',
'sync',
'info',
'scan',
'scan-all',
'audit',
'security-config',
]);
// Parse flags
const flags: Record<string, string> = {};
for (const arg of args.slice(1)) {
if (arg.startsWith('--')) {
const [key, ...val] = arg.slice(2).split('=');
flags[key] = val.join('=') || 'true';
}
}
const positionals = args.slice(1).filter(a => !a.startsWith('--'));
function printHelp(): void {
console.log(`
Waggle Marketplace CLI
Usage:
waggle-market search <query> Search packages
waggle-market install <name|id> Install a package
waggle-market install-pack <slug> Install a capability pack
waggle-market uninstall <name|id> Uninstall a package
waggle-market list List installed packages
waggle-market packs List available packs
waggle-market sources List marketplace sources
waggle-market sync [--source=<name>] Sync from live sources
waggle-market info <name|id> Show package details
Security:
waggle-market scan <name|id> Scan a package for security issues
waggle-market scan-all [--type=<type>] Scan all packages in the database
waggle-market audit Security audit summary
waggle-market security-config View/edit security settings
Flags:
--type=<skill|plugin|mcp> Filter by install type
--category=<name> Filter by category
--pack=<slug> Filter by pack membership
--force Force reinstall
--force-insecure Bypass security gate (DANGEROUS)
--limit=<n> Limit search results
`);
}
async function main() {
if (HELP_COMMANDS.has(command)) {
printHelp();
return;
}
if (!KNOWN_COMMANDS.has(command)) {
console.error(`Unknown command: ${command}`);
printHelp();
process.exit(1);
}
const db = new MarketplaceDB();
const installer = new MarketplaceInstaller(db);
try {
switch (command) {
case 'search':
case 's': {
const query = positionals.join(' ');
const result = db.search({
query: query || undefined,
type: flags.type as InstallationType | undefined,
category: flags.category,
pack: flags.pack,
limit: parseInt(flags.limit || '20'),
});
console.log(`\n📦 Found ${result.total} packages${query ? ` for "${query}"` : ''}:\n`);
for (const pkg of result.packages) {
const installed = db.isInstalled(pkg.id);
const badge = installed ? '✅' : ' ';
const type = pkg.waggle_install_type.toUpperCase().padEnd(7);
console.log(` ${badge} [${type}] ${pkg.display_name}`);
console.log(` ${pkg.description.slice(0, 80)}`);
console.log(` ⬇${pkg.downloads} ⭐${pkg.stars} | ${pkg.category} | ID: ${pkg.id}`);
console.log();
}
console.log(`Types: ${Object.entries(result.facets.types).map(([k, v]) => `${k}(${v})`).join(', ')}`);
break;
}
case 'install':
case 'i': {
const target = positionals[0];
if (!target) {
console.error('Usage: waggle-market install <name|id>');
process.exit(1);
}
const pkg = isNaN(Number(target))
? db.search({ query: target, limit: 1 }).packages[0]
: db.getPackage(Number(target));
if (!pkg) {
console.error(`Package "${target}" not found.`);
process.exit(1);
}
console.log(`\n📥 Installing ${pkg.display_name} (${pkg.waggle_install_type})...`);
const result = await installer.install({
packageId: pkg.id,
force: flags.force === 'true',
forceInsecure: flags['force-insecure'] === 'true',
settings: flags.settings ? JSON.parse(flags.settings) : undefined,
});
if (result.success) {
console.log(`✅ ${result.message}`);
} else {
console.error(`❌ ${result.message}`);
if (result.errors) result.errors.forEach(e => console.error(` ${e}`));
process.exit(1);
}
break;
}
case 'install-pack':
case 'ip': {
const slug = positionals[0];
if (!slug) {
console.error('Usage: waggle-market install-pack <slug>');
process.exit(1);
}
console.log(`\n📦 Installing pack "${slug}"...`);
const result = await installer.installPack(slug, { force: flags.force === 'true' });
console.log(`\n${result.packName} — Installation Summary:`);
console.log(` ✅ Installed: ${result.installed.length}`);
console.log(` ⏭ Skipped: ${result.skipped.length}`);
console.log(` ❌ Failed: ${result.failed.length}`);
if (result.installed.length > 0) {
console.log('\nInstalled:');
result.installed.forEach(r => console.log(` • ${r.packageName} → ${r.installPath}`));
}
if (result.failed.length > 0) {
console.log('\nFailed:');
result.failed.forEach(r => console.log(` • ${r.packageName}: ${r.message}`));
}
break;
}
case 'uninstall':
case 'u': {
const target = positionals[0];
if (!target) {
console.error('Usage: waggle-market uninstall <name|id>');
process.exit(1);
}
const pkg = isNaN(Number(target))
? db.search({ query: target, limit: 1 }).packages[0]
: db.getPackage(Number(target));
if (!pkg) {
console.error(`Package "${target}" not found.`);
process.exit(1);
}
const result = await installer.uninstall(pkg.id);
console.log(result.success ? `✅ ${result.message}` : `❌ ${result.message}`);
break;
}
case 'list':
case 'ls': {
const installations = db.listInstallations();
if (installations.length === 0) {
console.log('\nNo packages installed yet. Try: waggle-market search');
break;
}
console.log(`\n📋 Installed packages (${installations.length}):\n`);
for (const inst of installations) {
console.log(` • ${inst.pkg_display_name} v${inst.installed_version}`);
console.log(` Type: ${inst.waggle_install_type} | Path: ${inst.install_path}`);
console.log(` Installed: ${inst.installed_at}`);
console.log();
}
break;
}
case 'packs': {
const packs = db.listPacks();
console.log(`\n🎯 Available Capability Packs (${packs.length}):\n`);
for (const pack of packs) {
const packData = db.getPacksBySlug(pack.slug);
const count = packData?.packages.length || 0;
console.log(` ${pack.icon} ${pack.display_name} (${count} packages)`);
console.log(` ${pack.description}`);
console.log(` Roles: ${pack.target_roles} | Priority: ${pack.priority}`);
console.log(` Install: waggle-market install-pack ${pack.slug}`);
console.log();
}
break;
}
case 'sources': {
const sources = db.listSources();
console.log(`\n🌐 Marketplace Sources (${sources.length}):\n`);
for (const source of sources) {
console.log(` • ${source.display_name}`);
console.log(` ${source.url}`);
console.log(` Type: ${source.source_type} | Packages: ${source.total_packages} | Install: ${source.install_method}`);
console.log();
}
break;
}
case 'sync': {
const sync = new MarketplaceSync(db);
const sourceFilter = flags.source ? [flags.source] : undefined;
console.log('\n🔄 Syncing marketplace data...\n');
const results = await sync.syncAll({ sources: sourceFilter });
let totalAdded = 0;
for (const result of results) {
const status = result.errors.length > 0 ? '⚠️' : '✅';
console.log(` ${status} ${result.source}: +${result.added} packages`);
if (result.errors.length > 0) {
result.errors.forEach(e => console.log(` ❌ ${e}`));
}
totalAdded += result.added;
}
console.log(`\n📊 Total: ${totalAdded} packages synced from ${results.length} sources`);
break;
}
case 'info': {
const target = positionals[0];
if (!target) {
console.error('Usage: waggle-market info <name|id>');
process.exit(1);
}
const pkg = isNaN(Number(target))
? db.search({ query: target, limit: 1 }).packages[0]
: db.getPackage(Number(target));
if (!pkg) {
console.error(`Package "${target}" not found.`);
process.exit(1);
}
console.log(`\n📦 ${pkg.display_name}`);
console.log(`${'─'.repeat(40)}`);
console.log(`Name: ${pkg.name}`);
console.log(`Type: ${pkg.waggle_install_type}`);
console.log(`Category: ${pkg.category}`);
console.log(`Author: ${pkg.author}`);
console.log(`Version: ${pkg.version}`);
console.log(`License: ${pkg.license || 'Unknown'}`);
console.log(`Downloads: ${pkg.downloads}`);
console.log(`Stars: ${pkg.stars}`);
console.log(`Install to: ${pkg.waggle_install_path}`);
console.log(`Platforms: ${pkg.platforms?.join(', ')}`);
console.log(`Packs: ${pkg.packs?.join(', ') || 'none'}`);
if (pkg.repository_url) console.log(`Repository: ${pkg.repository_url}`);
if (pkg.homepage_url) console.log(`Homepage: ${pkg.homepage_url}`);
console.log(`\n${pkg.description}`);
console.log(`\nInstalled: ${db.isInstalled(pkg.id) ? '✅ Yes' : '❌ No'}`);
break;
}
case 'scan': {
const target = positionals[0];
if (!target) {
console.error('Usage: waggle-market scan <name|id>');
process.exit(1);
}
const pkg = isNaN(Number(target))
? db.search({ query: target, limit: 1 }).packages[0]
: db.getPackage(Number(target));
if (!pkg) {
console.error(`Package "${target}" not found.`);
process.exit(1);
}
console.log(`\n🔍 Scanning ${pkg.display_name}...\n`);
const report = await installer.getSecurityReport(pkg.id);
console.log(report);
break;
}
case 'scan-all': {
const type = flags.type as InstallationType | undefined;
const allPkgs = db.search({ type, limit: 999 }).packages;
console.log(`\n🔍 Scanning ${allPkgs.length} packages...\n`);
const stats = { clean: 0, low: 0, medium: 0, high: 0, critical: 0, errors: 0 };
for (const pkg of allPkgs) {
try {
const result = await installer.scanOnly(pkg.id);
if (result) {
const key = result.overall_severity.toLowerCase() as keyof typeof stats;
if (key in stats) stats[key]++;
const icon = result.blocked ? '🚫' : result.overall_severity === 'CLEAN' ? '✅' :
result.overall_severity === 'LOW' ? '🔵' :
result.overall_severity === 'MEDIUM' ? '🟡' :
result.overall_severity === 'HIGH' ? '🟠' : '🔴';
console.log(` ${icon} ${pkg.display_name.padEnd(35)} ${result.overall_severity.padEnd(10)} ${result.security_score}/100`);
}
} catch {
stats.errors++;
console.log(` ❓ ${pkg.display_name.padEnd(35)} ERROR`);
}
}
console.log(`\n📊 Summary:`);
console.log(` ✅ Clean: ${stats.clean}`);
console.log(` 🔵 Low: ${stats.low}`);
console.log(` 🟡 Medium: ${stats.medium}`);
console.log(` 🟠 High: ${stats.high}`);
console.log(` 🔴 Critical: ${stats.critical}`);
if (stats.errors > 0) console.log(` ❓ Errors: ${stats.errors}`);
break;
}
case 'audit': {
// Show security status of all packages in DB. `search()` returns
// `SELECT p.*`, so the persisted scan columns ride along at runtime —
// view them through ScannedPackage rather than the core package type.
const results = db.search({ limit: 999 }).packages as ScannedPackage[];
const unscanned = results.filter(p => !p.security_status || p.security_status === 'unscanned');
const blocked = results.filter(p => p.scan_blocked === 1);
const risky = results.filter(p => ['high', 'critical'].includes(p.security_status || ''));
console.log(`\n🛡️ Marketplace Security Audit`);
console.log(`${'─'.repeat(50)}`);
console.log(` Total packages: ${results.length}`);
console.log(` Unscanned: ${unscanned.length}`);
console.log(` Blocked: ${blocked.length}`);
console.log(` High/Critical: ${risky.length}`);
console.log(` Safe: ${results.length - unscanned.length - blocked.length - risky.length}`);
if (blocked.length > 0) {
console.log('\n🚫 Blocked packages:');
blocked.forEach(p => console.log(` • ${p.display_name} (${p.security_status})`));
}
if (risky.length > 0) {
console.log('\n⚠️ Risky packages:');
risky.forEach(p => console.log(` • ${p.display_name} — score: ${p.security_score}/100`));
}
if (unscanned.length > 0) {
console.log(`\n💡 Run "waggle-market scan-all" to scan ${unscanned.length} unscanned packages.`);
}
break;
}
case 'security-config': {
if (positionals.length === 0) {
// Show current config
const gate = new SecurityGate();
console.log('\n🔧 Security Configuration:');
console.log(' (edit ~/.waggle/security-config.json or use waggle-market security-config <key> <value>)');
// Would read from security_config table
} else if (positionals.length >= 2) {
console.log(` Set ${positionals[0]} = ${positionals[1]}`);
// Would write to security_config table
}
break;
}
default:
printHelp();
}
} finally {
db.close();
}
}
main().catch(err => {
console.error('Error:', err.message);
process.exit(1);
});

View File

@@ -0,0 +1,541 @@
/**
* Waggle Marketplace — Database Access Layer
*
* SQLite database interface for the marketplace catalog.
* Uses better-sqlite3 (same driver Waggle core uses for .mind files).
*/
import Database from 'better-sqlite3';
import { join } from 'path';
import { homedir } from 'os';
import { seedMcpServers } from './mcp-registry.js';
import type {
MarketplacePackage,
MarketplaceSource,
MarketplacePack,
Installation,
InstalledPackageRow,
PackageUpsertInput,
SearchOptions,
SearchResult,
SearchSort,
} from './types.js';
const DEFAULT_DB_PATH = join(homedir(), '.waggle', 'marketplace.db');
export class MarketplaceDB {
private db: Database.Database;
constructor(dbPath: string = DEFAULT_DB_PATH) {
this.db = new Database(dbPath, { readonly: false });
this.db.pragma('journal_mode = WAL');
this.db.pragma('foreign_keys = ON');
// Auto-migrate: ensure is_custom column exists on sources table
this.migrateSchema();
// Seed MCP servers with proper install_manifest only on production DBs
// (skip for fresh/empty test DBs to avoid interfering with test expectations)
try {
const count = (this.db.prepare('SELECT COUNT(*) as cnt FROM packages').get() as { cnt: number })?.cnt ?? 0;
if (count > 0) seedMcpServers(this);
} catch { /* packages table may not exist in empty DBs */ }
}
/**
* Internal escape hatch for sibling marketplace modules (sync, seed,
* mcp-registry) that need to run raw SQL not covered by the typed API.
* Returns the underlying better-sqlite3 handle. Not part of the public
* marketplace surface — prefer the typed methods above where they exist.
*/
getRawDb(): Database.Database {
return this.db;
}
/**
* Apply any necessary schema migrations.
* Safe to call on all database versions.
*/
private migrateSchema(): void {
// Migration: add is_custom column to sources
try {
this.db.prepare("SELECT is_custom FROM sources LIMIT 0").run();
} catch {
try {
this.db.prepare("ALTER TABLE sources ADD COLUMN is_custom BOOLEAN DEFAULT 0").run();
} catch {
// Table might not exist yet (empty DB) — skip migration
}
}
// Migration: add sync_state column to sources (JSON blob for resumable sync)
try {
this.db.prepare("SELECT sync_state FROM sources LIMIT 0").run();
} catch {
try {
this.db.prepare("ALTER TABLE sources ADD COLUMN sync_state TEXT DEFAULT NULL").run();
} catch {
// Table might not exist yet (empty DB) — skip migration
}
}
}
// ─── Package Queries ──────────────────────────────────────────────
/**
* Search packages using FTS5 full-text search + faceted filtering.
*/
search(options: SearchOptions = {}): SearchResult {
const { query, type, category, pack, source, sort, limit = 50, offset = 0 } = options;
const conditions: string[] = [];
const params: Record<string, unknown> = {};
// Full-text search via FTS5. The raw caller string is NEVER passed
// straight into MATCH — it may be a verbose natural-language `need`
// (from the agent's acquire_capability path) or contain FTS5 operators
// / paths like `D:\X` that implicit-AND to zero matches or raise a
// syntax error. toFtsMatchQuery() relaxes it into a safe OR-of-prefix
// expression; null means "no usable terms" → fall back to an
// unfiltered listing instead of throwing.
let baseQuery: string;
const ftsExpr = query ? this.toFtsMatchQuery(query) : null;
if (ftsExpr) {
baseQuery = `
SELECT p.* FROM packages p
INNER JOIN packages_fts fts ON p.id = fts.rowid
WHERE packages_fts MATCH @query
`;
params.query = ftsExpr;
} else {
baseQuery = `SELECT p.* FROM packages p WHERE 1=1`;
}
// Faceted filters
if (type) {
conditions.push(`p.waggle_install_type = @type`);
params.type = type;
}
if (category) {
conditions.push(`p.category = @category`);
params.category = category;
}
if (pack) {
conditions.push(`EXISTS (
SELECT 1 FROM pack_packages pp
INNER JOIN packs pk ON pk.id = pp.pack_id
WHERE pp.package_id = p.id AND pk.slug = @pack
)`);
params.pack = pack;
}
if (source) {
conditions.push(`EXISTS (
SELECT 1 FROM sources s
WHERE s.id = p.source_id AND s.name = @source
)`);
params.source = source;
}
const whereClause = conditions.length > 0
? ` AND ${conditions.join(' AND ')}`
: '';
// Get total count
const countQuery = baseQuery.replace('SELECT p.*', 'SELECT COUNT(*) as total') + whereClause;
const total = (this.db.prepare(countQuery).get(params) as { total: number }).total;
// Determine sort order
// Order by FTS rank only when we actually took the FTS branch — `rank`
// is an FTS5-only column and is absent on the unfiltered fallback.
const orderClause = this.buildOrderClause(sort, !!ftsExpr);
// Get packages
const fullQuery = baseQuery + whereClause + ` ${orderClause} LIMIT @limit OFFSET @offset`;
params.limit = limit;
params.offset = offset;
const packages = this.db.prepare(fullQuery).all(params) as MarketplacePackage[];
// Parse JSON fields
const parsed = packages.map(p => this.parsePackageJson(p));
// Build facets (on unfiltered result set)
const facets = this.buildFacets(baseQuery + whereClause, params);
// Get installed count
const installedCount = this.getInstalledCount();
return { packages: parsed, total, facets, installedCount };
}
/**
* Get a single package by ID.
*/
getPackage(id: number): MarketplacePackage | null {
const row = this.db.prepare('SELECT * FROM packages WHERE id = ?').get(id) as MarketplacePackage | undefined;
return row ? this.parsePackageJson(row) : null;
}
/**
* Get a single package by name.
*/
getPackageByName(name: string): MarketplacePackage | null {
const row = this.db.prepare('SELECT * FROM packages WHERE name = ?').get(name) as MarketplacePackage | undefined;
return row ? this.parsePackageJson(row) : null;
}
/**
* Get all packages in a given pack.
*/
getPacksBySlug(slug: string): { pack: MarketplacePack; packages: MarketplacePackage[] } | null {
const pack = this.db.prepare('SELECT * FROM packs WHERE slug = ?').get(slug) as MarketplacePack | undefined;
if (!pack) return null;
const packages = this.db.prepare(`
SELECT p.*, pp.is_core FROM packages p
INNER JOIN pack_packages pp ON pp.package_id = p.id
WHERE pp.pack_id = ?
ORDER BY pp.is_core DESC, p.downloads DESC
`).all(pack.id) as (MarketplacePackage & { is_core: boolean })[];
return {
pack: { ...pack, connectors_needed: JSON.parse(pack.connectors_needed as unknown as string || '[]') },
packages: packages.map(p => this.parsePackageJson(p)),
};
}
/**
* List all available packs.
*/
listPacks(): MarketplacePack[] {
const rows = this.db.prepare('SELECT * FROM packs ORDER BY priority, display_name').all() as MarketplacePack[];
return rows.map(p => ({
...p,
connectors_needed: JSON.parse(p.connectors_needed as unknown as string || '[]'),
}));
}
/**
* List all sources.
*/
listSources(): MarketplaceSource[] {
return this.db.prepare(`
SELECT *, COALESCE(is_custom, 0) as is_custom FROM sources ORDER BY total_packages DESC
`).all() as MarketplaceSource[];
}
/**
* List all sources with package counts derived from the packages table.
*/
listSourcesWithCounts(): (MarketplaceSource & { package_count: number })[] {
return this.db.prepare(`
SELECT s.*, COALESCE(s.is_custom, 0) as is_custom,
COUNT(p.id) as package_count
FROM sources s
LEFT JOIN packages p ON p.source_id = s.id
GROUP BY s.id
ORDER BY package_count DESC, s.display_name ASC
`).all() as (MarketplaceSource & { package_count: number })[];
}
/**
* Get a single source by ID.
*/
getSource(id: number): MarketplaceSource | null {
const row = this.db.prepare(
'SELECT *, COALESCE(is_custom, 0) as is_custom FROM sources WHERE id = ?'
).get(id) as MarketplaceSource | undefined;
return row ?? null;
}
/**
* Get a single source by name.
*/
getSourceByName(name: string): MarketplaceSource | null {
const row = this.db.prepare(
'SELECT *, COALESCE(is_custom, 0) as is_custom FROM sources WHERE name = ?'
).get(name) as MarketplaceSource | undefined;
return row ?? null;
}
/**
* Add a new user-defined source.
* Returns the source ID.
*/
addSource(source: {
name: string;
display_name: string;
url: string;
source_type: string;
platform?: string;
install_method?: string;
api_endpoint?: string | null;
description?: string;
}): number {
const stmt = this.db.prepare(`
INSERT INTO sources (name, display_name, url, source_type, platform, total_packages, install_method, api_endpoint, description, is_custom)
VALUES (@name, @display_name, @url, @source_type, @platform, 0, @install_method, @api_endpoint, @description, 1)
`);
const result = stmt.run({
name: source.name,
display_name: source.display_name,
url: source.url,
source_type: source.source_type,
platform: source.platform || 'waggle',
install_method: source.install_method || 'git_clone',
api_endpoint: source.api_endpoint ?? null,
description: source.description || '',
});
return result.lastInsertRowid as number;
}
/**
* Delete a user-defined source and all its packages.
* Returns true if deleted, false if source not found or is built-in.
*/
deleteSource(id: number): boolean {
const source = this.getSource(id);
if (!source) return false;
if (!source.is_custom) return false;
// Delete packages belonging to this source first
this.db.prepare('DELETE FROM packages WHERE source_id = ?').run(id);
// Delete the source
const result = this.db.prepare('DELETE FROM sources WHERE id = ? AND is_custom = 1').run(id);
return result.changes > 0;
}
/**
* Ensure the sources table has the is_custom column.
* Safe to call on existing databases — no-ops if column already exists.
*/
ensureIsCustomColumn(): void {
try {
this.db.prepare("SELECT is_custom FROM sources LIMIT 1").get();
} catch {
// Column doesn't exist — add it
this.db.prepare("ALTER TABLE sources ADD COLUMN is_custom BOOLEAN DEFAULT 0").run();
}
}
// ─── Sync State (resumable sync for rate-limited sources) ────────
/**
* Get the sync state for a source (used for resumable pagination).
* Returns null if no state is saved.
*/
getSyncState(sourceId: number): Record<string, unknown> | null {
const row = this.db.prepare(
'SELECT sync_state FROM sources WHERE id = ?'
).get(sourceId) as { sync_state: string | null } | undefined;
if (!row || !row.sync_state) return null;
try {
return JSON.parse(row.sync_state);
} catch {
return null;
}
}
/**
* Save sync state for a source (used for resumable pagination).
* Pass null to clear the state (e.g., when a full sync completes).
*/
setSyncState(sourceId: number, state: Record<string, unknown> | null): void {
this.db.prepare(
'UPDATE sources SET sync_state = ? WHERE id = ?'
).run(state ? JSON.stringify(state) : null, sourceId);
}
// ─── Installation Tracking ────────────────────────────────────────
/**
* Record a successful installation.
*/
recordInstallation(
packageId: number,
version: string,
installPath: string,
config: Record<string, unknown> = {},
): Installation {
const stmt = this.db.prepare(`
INSERT INTO installations (package_id, installed_version, installed_at, install_path, status, config)
VALUES (?, ?, datetime('now'), ?, 'installed', ?)
`);
const result = stmt.run(packageId, version, installPath, JSON.stringify(config));
return this.getInstallation(result.lastInsertRowid as number)!;
}
/**
* Get installation by ID.
*/
getInstallation(id: number): Installation | null {
const row = this.db.prepare('SELECT * FROM installations WHERE id = ?').get(id) as Installation | undefined;
if (!row) return null;
return { ...row, config: JSON.parse(row.config as unknown as string || '{}') };
}
/**
* Get all active installations.
*/
listInstallations(): InstalledPackageRow[] {
return this.db.prepare(`
SELECT i.*, p.name as pkg_name, p.display_name as pkg_display_name,
p.waggle_install_type, p.category
FROM installations i
INNER JOIN packages p ON p.id = i.package_id
WHERE i.status = 'installed'
ORDER BY i.installed_at DESC
`).all() as InstalledPackageRow[];
}
/**
* Check if a package is already installed.
*/
isInstalled(packageId: number): boolean {
const row = this.db.prepare(
`SELECT 1 FROM installations WHERE package_id = ? AND status = 'installed'`
).get(packageId);
return !!row;
}
/**
* Mark an installation as uninstalled.
*/
markUninstalled(packageId: number): void {
this.db.prepare(
`UPDATE installations SET status = 'uninstalled' WHERE package_id = ? AND status = 'installed'`
).run(packageId);
}
// ─── Upsert (for sync) ───────────────────────────────────────────
/**
* Insert or update a package (used by sync scripts).
*/
upsertPackage(pkg: PackageUpsertInput): number {
const existing = this.db.prepare('SELECT id FROM packages WHERE name = ? AND source_id = ?')
.get(pkg.name, pkg.source_id) as { id: number } | undefined;
if (existing) {
const sets: string[] = [];
const params: Record<string, unknown> = { id: existing.id };
for (const [key, value] of Object.entries(pkg)) {
if (key === 'id' || key === 'name' || key === 'source_id') continue;
sets.push(`${key} = @${key}`);
params[key] = typeof value === 'object' ? JSON.stringify(value) : value;
}
sets.push(`updated_at = datetime('now')`);
this.db.prepare(`UPDATE packages SET ${sets.join(', ')} WHERE id = @id`).run(params);
return existing.id;
} else {
const cols = Object.keys(pkg);
const vals = cols.map(c => `@${c}`);
const params: Record<string, unknown> = {};
for (const [key, value] of Object.entries(pkg)) {
params[key] = typeof value === 'object' ? JSON.stringify(value) : value;
}
const result = this.db.prepare(
`INSERT INTO packages (${cols.join(', ')}) VALUES (${vals.join(', ')})`
).run(params);
return result.lastInsertRowid as number;
}
}
// ─── Helpers ──────────────────────────────────────────────────────
private parsePackageJson(pkg: MarketplacePackage): MarketplacePackage {
return {
...pkg,
install_manifest: typeof pkg.install_manifest === 'string'
? JSON.parse(pkg.install_manifest)
: pkg.install_manifest,
platforms: typeof pkg.platforms === 'string'
? JSON.parse(pkg.platforms)
: pkg.platforms || [],
dependencies: typeof pkg.dependencies === 'string'
? JSON.parse(pkg.dependencies)
: pkg.dependencies || [],
packs: typeof pkg.packs === 'string'
? JSON.parse(pkg.packs)
: pkg.packs || [],
};
}
/**
* Relax arbitrary caller text into a safe FTS5 MATCH expression.
*
* Extracts alphanumeric tokens, drops <2-char noise, dedupes, caps the
* term count, then OR-joins as prefix terms (`token*`). OR (not the FTS5
* implicit AND) so a verbose `need` still matches on any salient word,
* with BM25 `rank` floating the best package up. Returns null when no
* usable token remains so the caller degrades to an unfiltered listing
* instead of throwing an FTS5 syntax error.
*/
private toFtsMatchQuery(raw: string): string | null {
const tokens = raw
.toLowerCase()
.split(/[^a-z0-9]+/)
.filter(t => t.length >= 2);
if (tokens.length === 0) return null;
const unique = [...new Set(tokens)].slice(0, 24); // cap term explosion
return unique.map(t => `${t}*`).join(' OR ');
}
private buildOrderClause(sort?: SearchSort, hasQuery?: boolean): string {
switch (sort) {
case 'popular':
return 'ORDER BY p.downloads DESC, p.stars DESC';
case 'recent':
return 'ORDER BY p.updated_at DESC, p.created_at DESC';
case 'name':
return 'ORDER BY p.display_name ASC';
case 'relevance':
// When using FTS, the default rank is relevance; fallback to downloads
return hasQuery ? 'ORDER BY rank, p.downloads DESC' : 'ORDER BY p.downloads DESC, p.stars DESC';
default:
// Default: if query present use relevance, else popularity
return hasQuery ? 'ORDER BY rank, p.downloads DESC' : 'ORDER BY p.downloads DESC, p.stars DESC';
}
}
/**
* Count the total number of installed packages.
*/
getInstalledCount(): number {
const row = this.db.prepare(
`SELECT COUNT(*) as cnt FROM installations WHERE status = 'installed'`
).get() as { cnt: number };
return row.cnt;
}
private buildFacets(baseQuery: string, params: Record<string, unknown>) {
const facetQuery = baseQuery.replace(
/SELECT p\.\*/,
`SELECT p.waggle_install_type, p.category, s.name as source_name`
).replace(
/FROM packages p/,
`FROM packages p LEFT JOIN sources s ON s.id = p.source_id`
);
const rows = this.db.prepare(facetQuery).all(params) as {
waggle_install_type: string;
category: string;
source_name: string;
}[];
const types: Record<string, number> = {};
const categories: Record<string, number> = {};
const sources: Record<string, number> = {};
for (const row of rows) {
types[row.waggle_install_type] = (types[row.waggle_install_type] || 0) + 1;
categories[row.category] = (categories[row.category] || 0) + 1;
if (row.source_name) sources[row.source_name] = (sources[row.source_name] || 0) + 1;
}
return { types, categories, sources };
}
/**
* Close the database connection.
*/
close(): void {
this.db.close();
}
}

View File

@@ -0,0 +1,52 @@
/**
* Enterprise Packs — KVARK-conditional capability packs.
*
* These packs only appear when KVARK is connected (vault has 'kvark:connection').
* They represent enterprise-grade capabilities that depend on KVARK's
* semantic search, governance, and entity resolution subsystems.
*
* The skills referenced may not all exist yet — packs are metadata
* that describe what will be available once KVARK features are fully wired.
*/
export interface EnterprisePack {
slug: string;
display_name: string;
description: string;
target_roles: string;
icon: string;
/** Skills included in this pack */
skills: string[];
/** Which KVARK features this pack requires */
kvarkRequirements: string[];
}
export const ENTERPRISE_PACKS: EnterprisePack[] = [
{
slug: 'enterprise-document-qa',
display_name: 'Enterprise Document Q&A',
description: 'Ask questions across your organization\'s document library using KVARK\'s semantic search and retrieval pipeline',
target_roles: 'knowledge-worker,analyst,researcher',
icon: '\u{1F4DA}',
skills: ['kvark_ask_document', 'kvark_search', 'document_summary'],
kvarkRequirements: ['search', 'ask_document'],
},
{
slug: 'compliance-workflow',
display_name: 'Compliance Workflow',
description: 'Governed document processing with audit trails — every action logged and traceable through KVARK\'s governance layer',
target_roles: 'compliance,legal,admin',
icon: '\u{1F6E1}\uFE0F',
skills: ['kvark_action', 'audit_trail_query', 'compliance_check'],
kvarkRequirements: ['governed_action'],
},
{
slug: 'knowledge-graph-enrichment',
display_name: 'Knowledge Graph Enrichment',
description: 'Automatically link entities, extract relationships, and build knowledge graphs using KVARK\'s entity resolution',
target_roles: 'researcher,analyst,knowledge-manager',
icon: '\u{1F578}\uFE0F',
skills: ['kvark_search', 'entity_extraction', 'relationship_mapping'],
kvarkRequirements: ['search', 'entity_resolution'],
},
];

View File

@@ -0,0 +1,22 @@
/**
* Injectable outbound fetch for the marketplace package.
*
* The marketplace is a standalone package (its own `waggle-market` CLI) and
* must stay free of `@waggle/agent` — importing it would create a dependency
* cycle (agent already type/dynamic-imports `@waggle/marketplace`). So the
* SSRF egress guard (`packages/agent/src/url-egress-guard.ts`) cannot be
* imported here directly; instead the server layer — which owns both packages —
* injects a guard-backed fetch into {@link MarketplaceInstaller} /
* {@link MarketplaceSync}. Standalone/CLI callers fall back to global `fetch`.
*
* The threat this protects (per the guard's THREAT_MODEL.md control 8) is the
* cloud/TEAMS sidecar binding 0.0.0.0: an attacker-influenced source URL that
* resolves to a private / link-local address (169.254.169.254 metadata, RFC1918)
* must be refused. The server injects a fetcher that does exactly that.
*/
/** A `fetch`-compatible function. `globalThis.fetch` is assignable to this. */
export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
/** Default fetcher — plain global fetch (no SSRF guard). Server overrides this. */
export const defaultFetch: FetchFn = (url, init) => fetch(url, init);

View File

@@ -0,0 +1,76 @@
/**
* Waggle Marketplace — Main Entry Point
*
* @module @waggle/marketplace
*
* Provides:
* - MarketplaceDB: SQLite database access for the package catalog
* - MarketplaceInstaller: Install/uninstall skills, plugins, MCP servers
* - MarketplaceSync: Sync packages from live marketplace sources
*
* Usage:
* import { MarketplaceDB, MarketplaceInstaller, MarketplaceSync } from '@waggle/marketplace';
*
* const db = new MarketplaceDB();
* const installer = new MarketplaceInstaller(db);
*
* // Search and install
* const results = db.search({ query: 'code review', type: 'skill' });
* await installer.install({ packageId: results.packages[0].id });
*
* // Install a pack
* await installer.installPack('research_analyst');
*
* // Sync from live sources
* const sync = new MarketplaceSync(db);
* await sync.syncAll();
*/
export { MarketplaceDB } from './db.js';
export { MarketplaceInstaller } from './installer.js';
export { MarketplaceSync, deduplicatePackages, parseAwesomeListMarkdown, parseNpmSearchResults, normalizeName } from './sync.js';
export type { VaultLookupFn } from './sync.js';
export { defaultFetch } from './fetcher.js';
export type { FetchFn } from './fetcher.js';
export { resolveSkillSource, classifySource, isSafeZipEntry, SkillSourceError } from './multi-source.js';
export type { ResolvedSkillSource, SkillSourceType, ResolveOptions, ZipEntry, ZipExtractor } from './multi-source.js';
export { seedNewSources, NEW_SOURCES } from './sources-seed.js';
export { SecurityGate } from './security.js';
export { isCiscoScannerAvailable, ciscoScan, getCiscoScannerVersion, resetAvailabilityCache, setExecFile } from './cisco-scanner.js';
export type { CiscoScanResult, CiscoScanIssue } from './cisco-scanner.js';
export { ENTERPRISE_PACKS } from './enterprise-packs.js';
export type { EnterprisePack } from './enterprise-packs.js';
export { MCP_SERVERS, seedMcpServers } from './mcp-registry.js';
export type { McpServerEntry } from './mcp-registry.js';
export { PACKAGE_CATEGORIES, categorizePackage, recategorizeAll } from './categories.js';
export type { PackageCategoryId } from './categories.js';
export type {
MarketplaceSource,
MarketplacePackage,
MarketplacePack,
Installation,
InstallManifest,
PluginManifest,
McpServerConfig,
SettingField,
PostInstallHook,
InstallationType,
InstallRequest,
InstallResult,
PackInstallResult,
SearchOptions,
SearchResult,
SearchSort,
SyncOptions,
SyncResult,
} from './types.js';
export type {
Severity,
SecurityFinding,
SecurityCategory,
SecurityEngine,
ScanResult,
SecurityGateConfig,
} from './security.js';

View File

@@ -0,0 +1,782 @@
/**
* Waggle Marketplace — Package Installer
*
* Handles installation of skills, plugins, and MCP servers from the
* marketplace database into the user's ~/.waggle/ directory.
*
* Installation strategies per type:
*
* SKILL: Download/copy markdown file → ~/.waggle/skills/{name}.md
* Then call PUT /api/skills/{name} if server is running.
*
* PLUGIN: Clone/download plugin dir → ~/.waggle/plugins/{name}/
* Write plugin.json manifest, copy skill files, register in registry.json.
* Then call POST /api/plugins/install if server is running.
*
* MCP: Add server config to .mcp.json (or bundle inside a plugin).
* Optionally install npm package via npx.
*/
import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, rmSync } from 'fs';
import { join, dirname } from 'path';
import { homedir } from 'os';
import { execSync } from 'child_process';
import { MarketplaceDB } from './db.js';
import { SecurityGate, type ScanResult, type SecurityGateConfig } from './security.js';
import { type FetchFn, defaultFetch } from './fetcher.js';
import type {
MarketplacePackage,
InstallManifest,
InstallRequest,
InstallResult,
PackInstallResult,
InstallationType,
McpServerConfig,
PluginManifest,
PostInstallHook,
} from './types.js';
const WAGGLE_DIR = join(homedir(), '.waggle');
const SKILLS_DIR = join(WAGGLE_DIR, 'skills');
const PLUGINS_DIR = join(WAGGLE_DIR, 'plugins');
const REGISTRY_PATH = join(PLUGINS_DIR, 'registry.json');
// UX-Refactor Phase 4 (C4): the sidecar boot loader reads <dataDir>/.mcp.json
// (dataDir = WAGGLE_DATA_DIR or ~/.waggle — see server local/mcp-config.ts).
// This previously wrote to process.cwd(), a file nothing ever read.
// Resolved at CALL time (not module import) so a host that sets
// WAGGLE_DATA_DIR after this module loads still writes to the right place.
function mcpConfigPath(): string {
return join(process.env.WAGGLE_DATA_DIR || WAGGLE_DIR, '.mcp.json');
}
/** Waggle server API base URL (when running locally) */
const API_BASE = process.env.WAGGLE_API_URL || 'http://localhost:3000';
/** A single server entry inside a `.mcp.json` file. */
interface McpConfigEntry {
command: string;
args: string[];
env?: Record<string, string>;
}
/** Shape of the `.mcp.json` config file we read/write. */
interface McpConfigFile {
mcpServers: Record<string, McpConfigEntry>;
}
export class MarketplaceInstaller {
private db: MarketplaceDB;
private security: SecurityGate;
/** Outbound fetch for external skill content — SSRF-guarded when the server
* injects it; plain global fetch for standalone/CLI callers. */
private fetchImpl: FetchFn;
constructor(db: MarketplaceDB, securityConfig?: Partial<SecurityGateConfig>, fetchImpl?: FetchFn) {
this.db = db;
this.security = new SecurityGate(securityConfig);
this.fetchImpl = fetchImpl ?? defaultFetch;
this.ensureDirectories();
}
// ─── Public API ───────────────────────────────────────────────────
/**
* Install a single package from the marketplace.
*/
async install(request: InstallRequest): Promise<InstallResult> {
const pkg = this.db.getPackage(request.packageId);
if (!pkg) {
return {
success: false,
packageId: request.packageId,
packageName: 'unknown',
installType: 'skill',
installPath: '',
message: `Package ID ${request.packageId} not found in marketplace database.`,
errors: ['Package not found'],
};
}
// Check if already installed
if (!request.force && this.db.isInstalled(pkg.id)) {
return {
success: true,
packageId: pkg.id,
packageName: pkg.name,
installType: pkg.waggle_install_type as InstallationType,
installPath: pkg.waggle_install_path,
message: `${pkg.display_name} is already installed. Use force=true to reinstall.`,
};
}
// ─── SECURITY GATE: Pre-install scan ───────────────────────
// Fetch content early so we can scan it before writing to disk
let contentToScan: string | undefined;
try {
contentToScan = await this.resolveContent(pkg);
} catch {
// Content resolution failure is handled in type-specific installers
}
const scanResult = await this.security.scan(pkg, contentToScan);
this.recordScanResult(pkg.id, scanResult);
if (scanResult.blocked && !request.forceInsecure) {
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType: pkg.waggle_install_type as InstallationType,
installPath: pkg.waggle_install_path,
message: `BLOCKED: Security scan found ${scanResult.overall_severity} severity issues. ${scanResult.findings.length} finding(s). Use forceInsecure=true to override.`,
errors: scanResult.findings.map(f => `[${f.severity}] ${f.title}: ${f.description}`),
scanResult,
};
}
// ─── END SECURITY GATE ─────────────────────────────────────
// Dispatch to type-specific installer
const installType = pkg.waggle_install_type as InstallationType;
let result: InstallResult;
switch (installType) {
case 'skill':
result = await this.installSkill(pkg, request);
break;
case 'plugin':
result = await this.installPlugin(pkg, request);
break;
case 'mcp':
result = await this.installMcp(pkg, request);
break;
default:
result = {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType,
installPath: '',
message: `Unknown install type: ${installType}`,
errors: [`Unsupported waggle_install_type: ${installType}`],
};
}
// Record in installations table if successful. Settings VALUES are
// typically API keys (§7.1 vault-only secrets) — persist only the keys so
// the row still documents WHICH settings were supplied without duplicating
// the secrets into a third plaintext store (.mcp.json already carries the
// resolved env; see server local/mcp-config.ts for the accepted exposure).
if (result.success) {
const settingKeys = Object.fromEntries(
Object.keys(request.settings ?? {}).map((k) => [k, '[redacted]']),
);
this.db.recordInstallation(
pkg.id,
pkg.version,
result.installPath,
settingKeys,
);
// Attach scan result to install result
result.scanResult = scanResult;
}
return result;
}
/**
* Scan a package without installing it.
*/
async scanOnly(packageId: number): Promise<ScanResult | null> {
const pkg = this.db.getPackage(packageId);
if (!pkg) return null;
let content: string | undefined;
try {
content = await this.resolveContent(pkg);
} catch { /* will scan without content */ }
const result = await this.security.scan(pkg, content);
this.recordScanResult(pkg.id, result);
return result;
}
/**
* Get a formatted security report for a package.
*/
async getSecurityReport(packageId: number): Promise<string> {
const result = await this.scanOnly(packageId);
if (!result) return 'Package not found.';
return this.security.formatReport(result);
}
/**
* Install an entire capability pack.
*/
async installPack(packSlug: string, options?: { force?: boolean }): Promise<PackInstallResult> {
const packData = this.db.getPacksBySlug(packSlug);
if (!packData) {
return {
packSlug,
packName: packSlug,
totalPackages: 0,
installed: [],
skipped: [],
failed: [],
};
}
const result: PackInstallResult = {
packSlug,
packName: packData.pack.display_name,
totalPackages: packData.packages.length,
installed: [],
skipped: [],
failed: [],
};
for (const pkg of packData.packages) {
if (!options?.force && this.db.isInstalled(pkg.id)) {
result.skipped.push(pkg.display_name);
continue;
}
const installResult = await this.install({
packageId: pkg.id,
force: options?.force,
});
if (installResult.success) {
result.installed.push(installResult);
} else {
result.failed.push(installResult);
}
}
return result;
}
/**
* Uninstall a package.
*/
async uninstall(packageId: number): Promise<InstallResult> {
const pkg = this.db.getPackage(packageId);
if (!pkg) {
return {
success: false,
packageId,
packageName: 'unknown',
installType: 'skill',
installPath: '',
message: 'Package not found.',
};
}
const installType = pkg.waggle_install_type as InstallationType;
try {
switch (installType) {
case 'skill':
await this.uninstallSkill(pkg);
break;
case 'plugin':
await this.uninstallPlugin(pkg);
break;
case 'mcp':
await this.uninstallMcp(pkg);
break;
}
this.db.markUninstalled(packageId);
return {
success: true,
packageId: pkg.id,
packageName: pkg.name,
installType,
installPath: pkg.waggle_install_path,
message: `${pkg.display_name} has been uninstalled.`,
};
} catch (err) {
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType,
installPath: pkg.waggle_install_path,
message: `Failed to uninstall: ${(err as Error).message}`,
errors: [(err as Error).message],
};
}
}
// ─── Skill Installation ───────────────────────────────────────────
private async installSkill(pkg: MarketplacePackage, request: InstallRequest): Promise<InstallResult> {
const skillName = pkg.name;
const installPath = request.installPath || join(SKILLS_DIR, `${skillName}.md`);
const manifest = pkg.install_manifest as InstallManifest | null;
try {
let content: string;
if (manifest?.skill_content) {
// Inline content from database
content = manifest.skill_content;
} else if (manifest?.skill_url) {
// Fetch from URL (GitHub raw, ClawHub API, etc.)
content = await this.fetchContent(manifest.skill_url);
} else if (pkg.repository_url) {
// Try to fetch SKILL.md from repository
const rawUrl = this.githubRawUrl(pkg.repository_url, 'SKILL.md');
content = await this.fetchContent(rawUrl);
} else {
// Generate a stub skill file from package metadata
content = this.generateSkillStub(pkg);
}
// Ensure skills directory exists
mkdirSync(dirname(installPath), { recursive: true });
// Write the skill file
writeFileSync(installPath, content, 'utf-8');
// Notify Waggle server if running
await this.notifyServer('PUT', `/api/skills/${skillName}`, {
name: skillName,
content,
});
return {
success: true,
packageId: pkg.id,
packageName: pkg.name,
installType: 'skill',
installPath,
message: `Skill "${pkg.display_name}" installed to ${installPath}`,
};
} catch (err) {
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType: 'skill',
installPath,
message: `Failed to install skill: ${(err as Error).message}`,
errors: [(err as Error).message],
};
}
}
// ─── Plugin Installation ──────────────────────────────────────────
private async installPlugin(pkg: MarketplacePackage, request: InstallRequest): Promise<InstallResult> {
const pluginName = pkg.name;
const pluginDir = request.installPath || join(PLUGINS_DIR, pluginName);
const manifest = pkg.install_manifest as InstallManifest | null;
try {
mkdirSync(pluginDir, { recursive: true });
// Step 1: Clone repo, install npm package, or create from metadata
if (manifest?.git_url) {
execSync(`git clone --depth 1 ${manifest.git_url} ${pluginDir}`, {
stdio: 'pipe',
timeout: 60_000,
});
} else if (manifest?.npm_package) {
// Install npm package into plugin directory
try {
writeFileSync(join(pluginDir, 'package.json'), JSON.stringify({ name: pluginName, private: true }), 'utf-8');
execSync(`npm install ${manifest.npm_package} --save`, {
cwd: pluginDir,
stdio: 'pipe',
timeout: 120_000,
});
} catch {
// npm install failed — continue with metadata-only plugin
}
}
// Step 2: Write plugin.json
const pluginManifest: PluginManifest = manifest?.plugin_manifest || {
name: pluginName,
version: pkg.version,
description: pkg.description,
skills: [],
mcpServers: [],
};
// Apply user settings to the manifest
if (request.settings && pluginManifest.settingsSchema) {
for (const [key, value] of Object.entries(request.settings)) {
// Inject settings into MCP server env vars
pluginManifest.mcpServers?.forEach(server => {
if (server.env) {
for (const envKey of Object.keys(server.env)) {
if (server.env[envKey] === `\${${key}}`) {
server.env[envKey] = value;
}
}
}
});
}
}
writeFileSync(
join(pluginDir, 'plugin.json'),
JSON.stringify(pluginManifest, null, 2),
'utf-8',
);
// Step 3: Install bundled skills
if (pluginManifest.skills && pluginManifest.skills.length > 0) {
const skillsDir = join(pluginDir, 'skills');
mkdirSync(skillsDir, { recursive: true });
for (const skillName of pluginManifest.skills) {
const skillPath = join(skillsDir, `${skillName}.md`);
if (!existsSync(skillPath)) {
// Try to find the skill in marketplace and install it into the plugin
const skillPkg = this.db.getPackageByName(skillName);
if (skillPkg?.install_manifest) {
const skillManifest = skillPkg.install_manifest as InstallManifest;
if (skillManifest.skill_url) {
const content = await this.fetchContent(skillManifest.skill_url);
writeFileSync(skillPath, content, 'utf-8');
}
}
}
}
}
// Step 4: Update registry.json
this.updatePluginRegistry(pluginName, pluginManifest);
// Step 5: Run post-install hooks
if (manifest?.post_install) {
for (const hook of manifest.post_install) {
await this.runPostInstallHook(hook, pluginDir);
}
}
// Step 6: Notify server
await this.notifyServer('POST', '/api/plugins/install', {
path: pluginDir,
});
return {
success: true,
packageId: pkg.id,
packageName: pkg.name,
installType: 'plugin',
installPath: pluginDir,
message: `Plugin "${pkg.display_name}" installed to ${pluginDir}`,
};
} catch (err) {
// Clean up on failure
if (existsSync(pluginDir)) {
rmSync(pluginDir, { recursive: true, force: true });
}
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType: 'plugin',
installPath: pluginDir,
message: `Failed to install plugin: ${(err as Error).message}`,
errors: [(err as Error).message],
};
}
}
// ─── MCP Server Installation ──────────────────────────────────────
private async installMcp(pkg: MarketplacePackage, request: InstallRequest): Promise<InstallResult> {
const manifest = pkg.install_manifest as InstallManifest | null;
const mcpConfig = manifest?.mcp_config;
if (!mcpConfig) {
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType: 'mcp',
installPath: mcpConfigPath(),
message: 'No MCP server configuration found in package manifest.',
errors: ['Missing mcp_config in install_manifest'],
};
}
try {
// Step 1: Install npm package if needed
if (manifest?.npm_package) {
const args = manifest.npm_args?.join(' ') || '';
execSync(`npm install -g ${manifest.npm_package} ${args}`, {
stdio: 'pipe',
timeout: 120_000,
});
}
// Step 2: Apply user settings to env vars
const serverConfig = { ...mcpConfig };
if (request.settings && serverConfig.env) {
for (const [key, value] of Object.entries(request.settings)) {
for (const envKey of Object.keys(serverConfig.env)) {
if (serverConfig.env[envKey] === `\${${key}}` || serverConfig.env[envKey] === '') {
serverConfig.env[envKey] = value;
}
}
}
}
// Step 3: Update .mcp.json
this.updateMcpConfig(serverConfig);
return {
success: true,
packageId: pkg.id,
packageName: pkg.name,
installType: 'mcp',
installPath: mcpConfigPath(),
message: `MCP server "${pkg.display_name}" added to ${mcpConfigPath()}`,
};
} catch (err) {
return {
success: false,
packageId: pkg.id,
packageName: pkg.name,
installType: 'mcp',
installPath: mcpConfigPath(),
message: `Failed to install MCP server: ${(err as Error).message}`,
errors: [(err as Error).message],
};
}
}
// ─── Uninstallation ───────────────────────────────────────────────
private async uninstallSkill(pkg: MarketplacePackage): Promise<void> {
const skillPath = join(SKILLS_DIR, `${pkg.name}.md`);
if (existsSync(skillPath)) {
rmSync(skillPath);
}
await this.notifyServer('DELETE', `/api/skills/${pkg.name}`);
}
private async uninstallPlugin(pkg: MarketplacePackage): Promise<void> {
const pluginDir = join(PLUGINS_DIR, pkg.name);
if (existsSync(pluginDir)) {
rmSync(pluginDir, { recursive: true, force: true });
}
this.removeFromPluginRegistry(pkg.name);
await this.notifyServer('DELETE', `/api/plugins/${pkg.name}`);
}
private async uninstallMcp(pkg: MarketplacePackage): Promise<void> {
const manifest = pkg.install_manifest as InstallManifest | null;
const serverName = manifest?.mcp_config?.name || pkg.name;
this.removeMcpConfig(serverName);
}
// ─── Helpers ──────────────────────────────────────────────────────
/**
* Resolve the downloadable content for a package (for pre-install scanning).
*/
private async resolveContent(pkg: MarketplacePackage): Promise<string | undefined> {
const manifest = pkg.install_manifest as InstallManifest | null;
if (pkg.waggle_install_type === 'skill') {
if (manifest?.skill_content) return manifest.skill_content;
if (manifest?.skill_url) return this.fetchContent(manifest.skill_url);
if (pkg.repository_url) {
const rawUrl = this.githubRawUrl(pkg.repository_url, 'SKILL.md');
return this.fetchContent(rawUrl);
}
return this.generateSkillStub(pkg);
}
if (pkg.waggle_install_type === 'mcp') {
// For MCPs, "content" is the config + description for scanning
return JSON.stringify({
name: manifest?.mcp_config?.name || pkg.name,
description: pkg.description,
args: manifest?.mcp_config?.args || [],
env: manifest?.mcp_config?.env || {},
});
}
if (pkg.waggle_install_type === 'plugin') {
// For plugins, return the manifest as content
if (manifest?.plugin_manifest) {
return JSON.stringify(manifest.plugin_manifest);
}
}
return undefined;
}
/**
* Record a security scan result in the database.
*/
private recordScanResult(packageId: number, result: ScanResult): void {
try {
// Update package security columns
const db = this.db.getRawDb(); // Access underlying better-sqlite3 instance
if (db && db.prepare) {
db.prepare(`
UPDATE packages SET
security_status = ?,
security_score = ?,
last_scanned_at = ?,
content_hash = ?,
scan_engines = ?,
scan_findings = ?,
scan_blocked = ?
WHERE id = ?
`).run(
result.overall_severity.toLowerCase(),
result.security_score,
result.scanned_at,
result.content_hash,
JSON.stringify(result.engines_used),
JSON.stringify(result.findings),
result.blocked ? 1 : 0,
packageId,
);
// Insert into scan_history
db.prepare(`
INSERT INTO scan_history
(package_id, scanned_at, overall_severity, security_score, content_hash, engines_used, findings, blocked, scan_duration_ms, triggered_by)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
packageId,
result.scanned_at,
result.overall_severity,
result.security_score,
result.content_hash,
JSON.stringify(result.engines_used),
JSON.stringify(result.findings),
result.blocked ? 1 : 0,
result.scan_duration_ms,
'install',
);
}
} catch (err) {
console.warn(`[security] Failed to record scan result: ${(err as Error).message}`);
}
}
private ensureDirectories(): void {
mkdirSync(SKILLS_DIR, { recursive: true });
mkdirSync(PLUGINS_DIR, { recursive: true });
if (!existsSync(REGISTRY_PATH)) {
writeFileSync(REGISTRY_PATH, JSON.stringify({ plugins: {} }, null, 2), 'utf-8');
}
}
private async fetchContent(url: string): Promise<string> {
// External skill content — routed through the injected (SSRF-guarded)
// fetcher so a malicious skill_url cannot pull an internal/link-local host.
const response = await this.fetchImpl(url);
if (!response.ok) {
throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
}
return response.text();
}
private githubRawUrl(repoUrl: string, filePath: string): string {
// Convert https://github.com/user/repo to https://raw.githubusercontent.com/user/repo/main/filePath
const match = repoUrl.match(/github\.com\/([^/]+)\/([^/]+)/);
if (!match) return repoUrl;
return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/main/${filePath}`;
}
private generateSkillStub(pkg: MarketplacePackage): string {
return `# ${pkg.display_name}
${pkg.description}
> Installed from Waggle Marketplace (source: ${pkg.author || 'community'})
> Category: ${pkg.category}
> Version: ${pkg.version}
---
## Instructions
This skill was installed from the marketplace. Configure or extend it as needed for your workflow.
`;
}
private updatePluginRegistry(name: string, manifest: PluginManifest): void {
const registry = JSON.parse(readFileSync(REGISTRY_PATH, 'utf-8'));
registry.plugins[name] = {
name: manifest.name,
version: manifest.version,
description: manifest.description,
skills: manifest.skills || [],
mcpServers: manifest.mcpServers || [],
};
writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2), 'utf-8');
}
private removeFromPluginRegistry(name: string): void {
const registry = JSON.parse(readFileSync(REGISTRY_PATH, 'utf-8'));
delete registry.plugins[name];
writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2), 'utf-8');
}
private updateMcpConfig(serverConfig: McpServerConfig): void {
let mcpJson: McpConfigFile = { mcpServers: {} };
if (existsSync(mcpConfigPath())) {
mcpJson = JSON.parse(readFileSync(mcpConfigPath(), 'utf-8')) as McpConfigFile;
}
mcpJson.mcpServers[serverConfig.name] = {
command: serverConfig.command,
args: serverConfig.args,
...(serverConfig.env && { env: serverConfig.env }),
};
writeFileSync(mcpConfigPath(), JSON.stringify(mcpJson, null, 2), 'utf-8');
}
private removeMcpConfig(serverName: string): void {
if (!existsSync(mcpConfigPath())) return;
const mcpJson = JSON.parse(readFileSync(mcpConfigPath(), 'utf-8')) as McpConfigFile;
delete mcpJson.mcpServers[serverName];
writeFileSync(mcpConfigPath(), JSON.stringify(mcpJson, null, 2), 'utf-8');
}
private async runPostInstallHook(hook: PostInstallHook, cwd: string): Promise<void> {
switch (hook.type) {
case 'run_command':
if (hook.command) {
execSync(hook.command, { cwd, stdio: 'pipe', timeout: 30_000 });
}
break;
case 'create_file':
if (hook.path && hook.content) {
const fullPath = join(cwd, hook.path);
mkdirSync(dirname(fullPath), { recursive: true });
writeFileSync(fullPath, hook.content, 'utf-8');
}
break;
case 'append_config':
// Append to workspace config
break;
}
}
private async notifyServer(method: string, path: string, body?: unknown): Promise<void> {
try {
await fetch(`${API_BASE}${path}`, {
method,
headers: { 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
});
} catch {
// Server not running — that's fine, files are already on disk
}
}
}

View File

@@ -0,0 +1,795 @@
/**
* Waggle Marketplace — MCP Server Registry
*
* Seed data for well-known MCP servers from the official ecosystem.
* These entries are inserted into the marketplace DB on initialization,
* making popular MCP servers immediately discoverable and installable.
*
* All npm package names and configurations reference real, published
* packages from the MCP ecosystem.
*/
import type { MarketplacePackage } from './types.js';
import type { MarketplaceDB } from './db.js';
// ─── Source ID Management ────────────────────────────────────────────
const MCP_REGISTRY_SOURCE = {
name: 'mcp_registry',
display_name: 'MCP Server Registry',
url: 'https://github.com/modelcontextprotocol/servers',
source_type: 'registry' as const,
platform: 'npm',
total_packages: 0,
install_method: 'npm' as const,
api_endpoint: null,
description: 'Official and community MCP servers curated for Waggle',
};
/**
* Ensure the MCP Registry source exists in the DB.
* Returns the source_id to use for package inserts.
*/
function ensureMcpSource(db: MarketplaceDB): number {
// Access the underlying better-sqlite3 instance
const rawDb = db.getRawDb();
const existing = rawDb
.prepare('SELECT id FROM sources WHERE name = ?')
.get(MCP_REGISTRY_SOURCE.name) as { id: number } | undefined;
if (existing) return existing.id;
const result = rawDb
.prepare(
`INSERT INTO sources (name, display_name, url, source_type, platform, total_packages, install_method, api_endpoint, description)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
)
.run(
MCP_REGISTRY_SOURCE.name,
MCP_REGISTRY_SOURCE.display_name,
MCP_REGISTRY_SOURCE.url,
MCP_REGISTRY_SOURCE.source_type,
MCP_REGISTRY_SOURCE.platform,
MCP_REGISTRY_SOURCE.total_packages,
MCP_REGISTRY_SOURCE.install_method,
MCP_REGISTRY_SOURCE.api_endpoint,
MCP_REGISTRY_SOURCE.description,
);
return result.lastInsertRowid as number;
}
// ─── MCP Server Definitions ─────────────────────────────────────────
export type McpServerEntry = Omit<
Partial<MarketplacePackage>,
'id' | 'source_id' | 'created_at' | 'updated_at'
> & {
name: string;
display_name: string;
description: string;
};
/**
* Well-known MCP servers from the official ecosystem.
*
* Organized by category:
* - developer-tools: filesystem, git, github, sqlite, postgres
* - web: brave-search, fetch, puppeteer
* - productivity: google-drive, slack, notion, gmail
* - knowledge: memory, everything, sequential-thinking
* - data: google-sheets, airtable
*/
export const MCP_SERVERS: McpServerEntry[] = [
// ── Developer Tools ─────────────────────────────────────────────
{
name: 'filesystem',
display_name: 'File System',
description:
'Read, write, search, and manage files and directories on the local filesystem with configurable access controls',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem',
downloads: 85000,
stars: 15000,
rating: 4.8,
rating_count: 420,
category: 'developer-tools',
subcategory: 'file-management',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-filesystem',
mcp_config: {
name: 'filesystem',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user/projects'],
},
},
},
{
name: 'git',
display_name: 'Git',
description:
'Read, search, and analyze Git repositories including diffs, logs, branches, and file history',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/git',
downloads: 62000,
stars: 15000,
rating: 4.7,
rating_count: 310,
category: 'developer-tools',
subcategory: 'version-control',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer'],
install_manifest: {
npm_package: 'mcp-server-git',
mcp_config: {
name: 'git',
command: 'uvx',
args: ['mcp-server-git'],
},
},
},
{
name: 'github',
display_name: 'GitHub',
description:
'Interact with GitHub repositories, issues, pull requests, branches, and files via the GitHub API',
author: 'GitHub',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/github',
downloads: 78000,
stars: 15000,
rating: 4.8,
rating_count: 385,
category: 'developer-tools',
subcategory: 'version-control',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-github',
mcp_config: {
name: 'github',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-github'],
env: { GITHUB_PERSONAL_ACCESS_TOKEN: '' },
},
},
},
{
name: 'sqlite',
display_name: 'SQLite',
description:
'Query and manage SQLite databases with read/write access, schema inspection, and business intelligence capabilities',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite',
downloads: 41000,
stars: 15000,
rating: 4.6,
rating_count: 198,
category: 'developer-tools',
subcategory: 'database',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer', 'data_scientist'],
install_manifest: {
npm_package: 'mcp-server-sqlite',
mcp_config: {
name: 'sqlite',
command: 'uvx',
args: ['mcp-server-sqlite', '--db-path', '/path/to/database.db'],
},
},
},
{
name: 'postgres',
display_name: 'PostgreSQL',
description:
'Connect to PostgreSQL databases for schema inspection, read-only queries, and data analysis',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/postgres',
downloads: 38000,
stars: 15000,
rating: 4.5,
rating_count: 176,
category: 'developer-tools',
subcategory: 'database',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer', 'data_scientist'],
install_manifest: {
npm_package: 'mcp-server-postgres',
mcp_config: {
name: 'postgres',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/mydb'],
},
},
},
// ── Web ─────────────────────────────────────────────────────────
{
name: 'brave-search',
display_name: 'Brave Search',
description:
'Search the web and get local results using the Brave Search API with web and local search capabilities',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search',
downloads: 54000,
stars: 15000,
rating: 4.7,
rating_count: 265,
category: 'web',
subcategory: 'search',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['research_analyst', 'content_operator'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-brave-search',
mcp_config: {
name: 'brave-search',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-brave-search'],
env: { BRAVE_API_KEY: '' },
},
},
},
{
name: 'fetch',
display_name: 'Fetch',
description:
'Fetch and extract content from web URLs, converting HTML to markdown for easy consumption by AI agents',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/fetch',
downloads: 47000,
stars: 15000,
rating: 4.6,
rating_count: 230,
category: 'web',
subcategory: 'http',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['research_analyst', 'developer'],
install_manifest: {
npm_package: 'mcp-server-fetch',
mcp_config: {
name: 'fetch',
command: 'uvx',
args: ['mcp-server-fetch'],
},
},
},
{
name: 'puppeteer',
display_name: 'Puppeteer',
description:
'Browser automation and web scraping using Puppeteer — navigate pages, take screenshots, click elements, fill forms',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer',
downloads: 35000,
stars: 15000,
rating: 4.5,
rating_count: 185,
category: 'web',
subcategory: 'automation',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer', 'research_analyst'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-puppeteer',
mcp_config: {
name: 'puppeteer',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-puppeteer'],
},
},
},
// ── Productivity ────────────────────────────────────────────────
{
name: 'google-drive',
display_name: 'Google Drive',
description:
'Search and read files from Google Drive with support for native Google Docs/Sheets/Slides export',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive',
downloads: 29000,
stars: 15000,
rating: 4.4,
rating_count: 145,
category: 'productivity',
subcategory: 'cloud-storage',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['content_operator', 'business_ops'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-gdrive',
mcp_config: {
name: 'google-drive',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-gdrive'],
},
},
},
{
name: 'slack',
display_name: 'Slack',
description:
'Interact with Slack workspaces — read channels, post messages, reply to threads, and manage reactions',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/slack',
downloads: 32000,
stars: 15000,
rating: 4.5,
rating_count: 168,
category: 'productivity',
subcategory: 'communication',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['business_ops', 'customer_success'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-slack',
mcp_config: {
name: 'slack',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-slack'],
env: { SLACK_BOT_TOKEN: '', SLACK_TEAM_ID: '' },
},
},
},
{
name: 'notion',
display_name: 'Notion',
description:
'Search, read, create, and update Notion pages and databases with full API integration',
author: 'suekou',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.0',
license: 'MIT',
repository_url: 'https://github.com/suekou/mcp-notion-server',
homepage_url: 'https://github.com/suekou/mcp-notion-server',
downloads: 25000,
stars: 600,
rating: 4.4,
rating_count: 132,
category: 'productivity',
subcategory: 'note-taking',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['content_operator', 'pm_pack'],
install_manifest: {
npm_package: '@suekou/mcp-notion-server',
mcp_config: {
name: 'notion',
command: 'npx',
args: ['-y', '@suekou/mcp-notion-server'],
env: { NOTION_API_TOKEN: '' },
},
},
},
{
name: 'gmail',
display_name: 'Gmail (Google)',
description:
'Read, search, draft, and send emails through Gmail via the Google API with OAuth2 authentication',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/gmail',
downloads: 22000,
stars: 15000,
rating: 4.3,
rating_count: 118,
category: 'productivity',
subcategory: 'email',
platforms: ['claude_code', 'waggle'],
dependencies: [],
packs: ['business_ops', 'executive'],
install_manifest: {
npm_package: '@anthropic-ai/mcp-server-gmail',
mcp_config: {
name: 'gmail',
command: 'npx',
args: ['-y', '@anthropic-ai/mcp-server-gmail'],
},
},
},
// ── Knowledge ───────────────────────────────────────────────────
{
name: 'memory',
display_name: 'Memory (Knowledge Graph)',
description:
'Persistent memory using a local knowledge graph — store entities, relations, and observations across conversations',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/memory',
downloads: 48000,
stars: 15000,
rating: 4.6,
rating_count: 240,
category: 'knowledge',
subcategory: 'memory',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['research_analyst'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-memory',
mcp_config: {
name: 'memory',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-memory'],
},
},
},
{
name: 'everything',
display_name: 'Everything (Voidtools Search)',
description:
'Lightning-fast file and folder search on Windows using the Everything SDK — instant results across all drives',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/everything',
downloads: 18000,
stars: 15000,
rating: 4.3,
rating_count: 95,
category: 'knowledge',
subcategory: 'search',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: [],
install_manifest: {
npm_package: '@modelcontextprotocol/server-everything',
mcp_config: {
name: 'everything',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-everything'],
},
},
},
{
name: 'sequential-thinking',
display_name: 'Sequential Thinking',
description:
'Dynamic problem-solving through a structured thinking process with branching, revision, and hypothesis tracking',
author: 'Anthropic',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.6.2',
license: 'MIT',
repository_url: 'https://github.com/modelcontextprotocol/servers',
homepage_url:
'https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking',
downloads: 31000,
stars: 15000,
rating: 4.5,
rating_count: 155,
category: 'knowledge',
subcategory: 'reasoning',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['research_analyst', 'consultant'],
install_manifest: {
npm_package: '@modelcontextprotocol/server-sequential-thinking',
mcp_config: {
name: 'sequential-thinking',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
},
},
},
// ── Data ────────────────────────────────────────────────────────
{
name: 'google-sheets',
display_name: 'Google Sheets',
description:
'Read, write, and manage Google Sheets spreadsheets — create sheets, update cells, and read data ranges',
author: 'nicholasoxford',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '1.0.0',
license: 'MIT',
repository_url: 'https://github.com/nicholasoxford/google-sheets-mcp',
homepage_url: 'https://github.com/nicholasoxford/google-sheets-mcp',
downloads: 12000,
stars: 200,
rating: 4.2,
rating_count: 68,
category: 'data',
subcategory: 'spreadsheets',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['data_scientist', 'business_ops', 'finance_accounting'],
install_manifest: {
npm_package: '@nicholasoxford/google-sheets-mcp',
mcp_config: {
name: 'google-sheets',
command: 'npx',
args: ['-y', '@nicholasoxford/google-sheets-mcp'],
env: { GOOGLE_SHEETS_CREDENTIALS: '' },
},
},
},
{
name: 'airtable',
display_name: 'Airtable',
description:
'Read, create, update, and delete records in Airtable bases with full schema and field type support',
author: 'felores',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '1.0.0',
license: 'MIT',
repository_url: 'https://github.com/felores/airtable-mcp',
homepage_url: 'https://github.com/felores/airtable-mcp',
downloads: 8500,
stars: 150,
rating: 4.1,
rating_count: 52,
category: 'data',
subcategory: 'database',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['business_ops', 'pm_pack'],
install_manifest: {
npm_package: 'airtable-mcp-server',
mcp_config: {
name: 'airtable',
command: 'npx',
args: ['-y', 'airtable-mcp-server'],
env: { AIRTABLE_API_KEY: '' },
},
},
},
// ── Additional Popular Servers ──────────────────────────────────
{
name: 'playwright',
display_name: 'Playwright',
description:
'Browser automation using Playwright — navigate, interact with elements, take screenshots, and execute JavaScript in real browsers',
author: 'Microsoft',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '0.0.14',
license: 'Apache-2.0',
repository_url: 'https://github.com/microsoft/playwright-mcp',
homepage_url: 'https://github.com/microsoft/playwright-mcp',
downloads: 42000,
stars: 4500,
rating: 4.7,
rating_count: 210,
category: 'web',
subcategory: 'automation',
platforms: ['claude_code', 'waggle', 'cursor', 'windsurf'],
dependencies: [],
packs: ['developer'],
install_manifest: {
npm_package: '@anthropic-ai/mcp-server-playwright',
mcp_config: {
name: 'playwright',
command: 'npx',
args: ['-y', '@anthropic-ai/mcp-server-playwright'],
},
},
},
{
name: 'linear',
display_name: 'Linear',
description:
'Manage Linear issues, projects, and teams — create, update, search issues and track project progress',
author: 'jerhadf',
package_type: 'mcp_server',
waggle_install_type: 'mcp',
waggle_install_path: '.mcp.json',
version: '1.0.0',
license: 'MIT',
repository_url: 'https://github.com/jerhadf/linear-mcp-server',
homepage_url: 'https://github.com/jerhadf/linear-mcp-server',
downloads: 15000,
stars: 300,
rating: 4.4,
rating_count: 88,
category: 'productivity',
subcategory: 'project-management',
platforms: ['claude_code', 'waggle', 'cursor'],
dependencies: [],
packs: ['pm_pack', 'developer'],
install_manifest: {
npm_package: 'linear-mcp-server',
mcp_config: {
name: 'linear',
command: 'npx',
args: ['-y', 'linear-mcp-server'],
env: { LINEAR_API_KEY: '' },
},
},
},
];
// ─── Seed Function ──────────────────────────────────────────────────
/**
* Seed MCP server entries into the marketplace database.
*
* Inserts each server from MCP_SERVERS if it doesn't already exist
* (matched by name). Skips duplicates safely.
*
* @returns Count of newly added MCP server entries
*/
export function seedMcpServers(db: MarketplaceDB): number {
const sourceId = ensureMcpSource(db);
let added = 0;
for (const server of MCP_SERVERS) {
// Check if already present by name
const existing = db.getPackageByName(server.name);
if (existing) {
// Patch existing records that are missing npm_package in install_manifest
const manifest = typeof existing.install_manifest === 'string'
? JSON.parse(existing.install_manifest)
: existing.install_manifest;
const seedManifest = server.install_manifest;
if (seedManifest?.npm_package && (!manifest || !manifest.npm_package)) {
const patched = { ...manifest, ...seedManifest };
const rawDb = db.getRawDb();
rawDb
.prepare('UPDATE packages SET install_manifest = ? WHERE id = ?')
.run(JSON.stringify(patched), existing.id);
}
continue;
}
db.upsertPackage({
source_id: sourceId,
name: server.name,
display_name: server.display_name,
description: server.description,
author: server.author || 'community',
package_type: server.package_type || 'mcp_server',
waggle_install_type: server.waggle_install_type || 'mcp',
waggle_install_path: server.waggle_install_path || '.mcp.json',
version: server.version || '1.0.0',
license: server.license || 'MIT',
repository_url: server.repository_url || null,
homepage_url: server.homepage_url || null,
downloads: server.downloads || 0,
stars: server.stars || 0,
rating: server.rating || 0,
rating_count: server.rating_count || 0,
category: server.category || 'integration',
subcategory: server.subcategory || null,
platforms: JSON.stringify(server.platforms || ['waggle']),
dependencies: JSON.stringify(server.dependencies || []),
packs: JSON.stringify(server.packs || []),
install_manifest: JSON.stringify(server.install_manifest),
});
added++;
}
// Update source package count
const rawDb = db.getRawDb();
rawDb
.prepare('UPDATE sources SET total_packages = ? WHERE id = ?')
.run(MCP_SERVERS.length, sourceId);
return added;
}

View File

@@ -0,0 +1,297 @@
/**
* Multi-source skill resolver (steal #11 — SKILLS ONLY).
*
* Resolves a user-supplied source string to the raw bytes of a single SKILL.md,
* using an ordered grammar (first match wins):
*
* 1. direct SKILL.md URL — any http(s) `*.md` URL on a non-github host
* 2. GitHub URL — github.com/owner/repo[/blob|tree/<ref>/<path>]
* 3. owner/repo[#subpath] — shorthand → raw.githubusercontent.com (main→master)
* 4. .zip URL — fetch archive, extract the SKILL.md
*
* Everything else is rejected: local paths, `git@`/`ssh://`, `file:`, tar
* archives, and arbitrary non-`.md` URLs. This resolver NEVER writes to disk and
* NEVER installs plugins or MCP servers (those paths run npm/git and are out of
* scope). The caller runs the security pipeline (SecurityGate → injection scan →
* frontmatter) and lands the result as a held approval before anything persists.
*
* Every outbound fetch goes through the injected {@link FetchFn} — the server
* injects an SSRF-guarded fetch so an attacker-influenced URL cannot reach an
* internal / link-local host.
*/
import { createHash } from 'node:crypto';
import { createRequire } from 'node:module';
import { sep as pathSep, normalize as pathNormalize, join as pathJoin } from 'node:path';
import { tmpdir } from 'node:os';
import { type FetchFn, defaultFetch } from './fetcher.js';
export type SkillSourceType = 'skill-md-url' | 'github-url' | 'owner-repo' | 'zip-url';
export interface ResolvedSkillSource {
/** Raw SKILL.md bytes decoded as UTF-8. */
content: string;
/** Which grammar branch matched. */
sourceType: SkillSourceType;
/** The concrete URL the content was fetched from. */
resolvedUrl: string;
}
/** A single zip entry — the slice of adm-zip's API this resolver uses. */
export interface ZipEntry {
entryName: string;
isDirectory: boolean;
getData(): Buffer;
}
/** Lists the entries of a zip archive. Injectable so tests need no adm-zip. */
export type ZipExtractor = (zip: Buffer) => ZipEntry[];
export interface ResolveOptions {
/** SHA-256 (hex) enforced against the fetched artifact when provided. */
sha256?: string;
/** Injected fetch (SSRF-guarded in production; global fetch by default). */
fetchImpl?: FetchFn;
/** Injected zip entry-lister (tests); defaults to adm-zip via runtime require. */
zipExtractor?: ZipExtractor;
}
/** Thrown for a rejected/invalid source or a failed resolution. */
export class SkillSourceError extends Error {
constructor(message: string) {
super(message);
this.name = 'SkillSourceError';
}
}
function truncate(s: string, max = 120): string {
return s.length > max ? `${s.slice(0, max)}…` : s;
}
// ─── Grammar classification ─────────────────────────────────────────
/** owner/repo[#subpath] shorthand — exactly one slash, no local-path markers. */
function isOwnerRepoShorthand(s: string): boolean {
if (s.includes('\\') || s.startsWith('/') || s.startsWith('.') || s.startsWith('~')) return false;
const hashIdx = s.indexOf('#');
const repoPart = hashIdx === -1 ? s : s.slice(0, hashIdx);
const subpath = hashIdx === -1 ? '' : s.slice(hashIdx + 1);
if (!/^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*$/.test(repoPart)) return false;
if (subpath) {
if (subpath.includes('..') || subpath.startsWith('/')) return false;
if (!/^[\w./-]+$/.test(subpath)) return false;
}
return true;
}
/** Classify a source string, or null if it is not an accepted skill source. */
export function classifySource(source: string): SkillSourceType | null {
const s = source.trim();
if (!s) return null;
if (s.startsWith('git@')) return null; // scp-style git remote — rejected
let url: URL | null = null;
try {
url = new URL(s);
} catch {
url = null;
}
if (url) {
if (url.protocol !== 'http:' && url.protocol !== 'https:') return null; // ssh:, file:, git:, …
const host = url.hostname.toLowerCase();
const path = url.pathname.toLowerCase();
if (/\.(tar|tgz)$/.test(path) || /\.tar\.gz$/.test(path)) return null; // tar deferred (symlink pitfalls)
const isGithub = host === 'github.com' || host === 'www.github.com';
if (path.endsWith('.md') && !isGithub) return 'skill-md-url';
if (isGithub) return 'github-url';
if (path.endsWith('.zip')) return 'zip-url';
return null; // arbitrary non-.md, non-github, non-zip URL — rejected
}
if (isOwnerRepoShorthand(s)) return 'owner-repo';
return null;
}
// ─── Candidate URL construction (markdown sources) ──────────────────
function githubUrlCandidates(source: string): string[] {
const u = new URL(source);
const parts = u.pathname.split('/').filter(Boolean); // [owner, repo, ...]
const owner = parts[0];
const repoRaw = parts[1];
if (!owner || !repoRaw) throw new SkillSourceError(`Invalid GitHub URL: ${truncate(source)}`);
const repo = repoRaw.replace(/\.git$/, '');
const rest = parts.slice(2);
if (rest[0] === 'blob' && rest.length >= 3) {
const ref = rest[1];
const filePath = rest.slice(2).join('/');
return [`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filePath}`];
}
if (rest[0] === 'tree' && rest.length >= 2) {
const ref = rest[1];
const subpath = rest.slice(2).join('/');
const file = subpath ? `${subpath}/SKILL.md` : 'SKILL.md';
return [`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${file}`];
}
// Bare repo → try main then master.
return [
`https://raw.githubusercontent.com/${owner}/${repo}/main/SKILL.md`,
`https://raw.githubusercontent.com/${owner}/${repo}/master/SKILL.md`,
];
}
function ownerRepoCandidates(source: string): string[] {
const hashIdx = source.indexOf('#');
const repoPart = hashIdx === -1 ? source : source.slice(0, hashIdx);
const subpath = hashIdx === -1 ? '' : source.slice(hashIdx + 1).replace(/^\/+|\/+$/g, '');
const [owner, repo] = repoPart.split('/');
const file = subpath ? `${subpath}/SKILL.md` : 'SKILL.md';
return [
`https://raw.githubusercontent.com/${owner}/${repo}/main/${file}`,
`https://raw.githubusercontent.com/${owner}/${repo}/master/${file}`,
];
}
// ─── SHA-256 enforcement ────────────────────────────────────────────
function enforceSha(bytes: Buffer, expected?: string): void {
if (!expected) return;
const actual = createHash('sha256').update(bytes).digest('hex');
if (actual.toLowerCase() !== expected.trim().toLowerCase()) {
throw new SkillSourceError(`SHA-256 mismatch: expected ${expected.trim()}, got ${actual}.`);
}
}
// ─── Zip extraction (zip-slip guarded) ──────────────────────────────
/** Boundary root for the resolved-path zip-slip check (never written to). */
const ZIP_DEST_ROOT = pathNormalize(pathJoin(tmpdir(), 'waggle-skill-zip-dest'));
/**
* True when a zip entry is safe to trust: not absolute, no `..` segment, and its
* resolved path stays within the sentinel dest boundary. Rejects zip-slip.
*/
export function isSafeZipEntry(entryName: string): boolean {
const n = (entryName || '').replace(/\\/g, '/');
if (!n) return false;
if (n.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(entryName)) return false; // absolute (posix / windows)
if (n.split('/').some((p) => p === '..')) return false;
const resolved = pathNormalize(pathJoin(ZIP_DEST_ROOT, n));
return resolved === ZIP_DEST_ROOT || resolved.startsWith(ZIP_DEST_ROOT + pathSep);
}
interface AdmZipRawEntry {
entryName: string;
isDirectory: boolean;
getData(): Buffer;
}
interface AdmZipInstance {
getEntries(): AdmZipRawEntry[];
}
type AdmZipConstructor = new (buffer: Buffer) => AdmZipInstance;
let cachedRequire: NodeRequire | null = null;
/** Default zip extractor — loads adm-zip at runtime (optional dep). */
function admZipExtractor(zip: Buffer): ZipEntry[] {
const req = (cachedRequire ??= createRequire(import.meta.url));
let AdmZip: AdmZipConstructor;
try {
AdmZip = req('adm-zip') as AdmZipConstructor;
} catch {
throw new SkillSourceError(
'Zip skill sources require the optional "adm-zip" package. Install it, or use a SKILL.md/GitHub source.',
);
}
const instance = new AdmZip(zip);
return instance.getEntries().map((e) => ({
entryName: e.entryName,
isDirectory: e.isDirectory,
getData: () => e.getData(),
}));
}
/** Depth (segment count) of a zip entry path — used to prefer the shallowest SKILL.md. */
function entryDepth(entryName: string): number {
return entryName.replace(/\\/g, '/').split('/').filter(Boolean).length;
}
function extractSkillMd(entries: ZipEntry[]): string {
let picked: ZipEntry | null = null;
for (const e of entries) {
// Validate EVERY entry first — a malicious archive is rejected whole, before
// the junk filter can hide a traversal entry.
if (!isSafeZipEntry(e.entryName)) {
throw new SkillSourceError(`Unsafe zip entry "${truncate(e.entryName, 80)}" (path traversal).`);
}
if (e.isDirectory) continue;
const base = e.entryName.replace(/\\/g, '/').split('/').pop() || '';
if (base.startsWith('.') || e.entryName.startsWith('__MACOSX/')) continue; // junk
if (base.toLowerCase() === 'skill.md') {
if (!picked || entryDepth(e.entryName) < entryDepth(picked.entryName)) picked = e;
}
}
if (!picked) throw new SkillSourceError('No SKILL.md found in the zip archive.');
return picked.getData().toString('utf-8');
}
async function resolveZip(url: string, doFetch: FetchFn, options: ResolveOptions): Promise<ResolvedSkillSource> {
const res = await doFetch(url);
if (!res.ok) throw new SkillSourceError(`Failed to fetch zip ${truncate(url)}: ${res.status} ${res.statusText}`);
const bytes = Buffer.from(await res.arrayBuffer());
enforceSha(bytes, options.sha256); // sha over the ZIP bytes (UI encourages it here)
const extractor = options.zipExtractor ?? admZipExtractor;
const content = extractSkillMd(extractor(bytes));
return { content, sourceType: 'zip-url', resolvedUrl: url };
}
async function resolveMarkdown(
kind: Exclude<SkillSourceType, 'zip-url'>,
source: string,
doFetch: FetchFn,
options: ResolveOptions,
): Promise<ResolvedSkillSource> {
const candidates =
kind === 'skill-md-url' ? [source]
: kind === 'github-url' ? githubUrlCandidates(source)
: ownerRepoCandidates(source);
let lastStatus = 0;
for (const url of candidates) {
// A thrown error (SSRF egress block, network failure) propagates — only an
// HTTP non-ok (e.g. 404 on `main`) falls through to the next candidate.
const res = await doFetch(url);
if (res.ok) {
const bytes = Buffer.from(await res.arrayBuffer());
enforceSha(bytes, options.sha256);
return { content: bytes.toString('utf-8'), sourceType: kind, resolvedUrl: url };
}
lastStatus = res.status;
}
throw new SkillSourceError(
`Could not fetch SKILL.md from ${truncate(source)} (tried ${candidates.length} location(s); last HTTP ${lastStatus}).`,
);
}
/**
* Resolve a source string to raw SKILL.md bytes. Throws {@link SkillSourceError}
* for a rejected source, a SHA mismatch, an unsafe zip, or a fetch failure.
*/
export async function resolveSkillSource(
source: string,
options: ResolveOptions = {},
): Promise<ResolvedSkillSource> {
const doFetch = options.fetchImpl ?? defaultFetch;
const trimmed = source.trim();
const kind = classifySource(trimmed);
if (!kind) {
throw new SkillSourceError(
`Unsupported skill source "${truncate(trimmed)}". Provide a SKILL.md URL, a GitHub URL, `
+ `an owner/repo[#subpath] shorthand, or a .zip URL.`,
);
}
if (kind === 'zip-url') return resolveZip(trimmed, doFetch, options);
return resolveMarkdown(kind, trimmed, doFetch, options);
}

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,223 @@
/**
* Waggle Marketplace — New Source Seeding
*
* Seeds additional marketplace sources into the DB to expand
* the package catalog via new adapters (awesome-list, npm, web registry, etc.).
*/
import type { MarketplaceDB } from './db.js';
interface NewSource {
name: string;
display_name: string;
url: string;
source_type: string;
api_endpoint: string | null;
total_packages: number;
}
const NEW_SOURCES: NewSource[] = [
{
name: 'skills-sh',
display_name: 'Skills.sh',
url: 'https://skills.sh/',
source_type: 'aggregator',
api_endpoint: 'https://skills.sh/api/skills',
total_packages: 0,
},
{
name: 'agent-skills-cc',
display_name: 'Agent Skills CC',
url: 'https://agent-skills.cc/',
source_type: 'aggregator',
api_endpoint: 'https://agent-skills.cc/api/skills',
total_packages: 0,
},
{
name: 'claude-skills-collection',
display_name: 'Claude Skills Collection',
url: 'https://github.com/abubakarsiddik31/claude-skills-collection',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'mcpmarket',
display_name: 'MCP Market',
url: 'https://mcpmarket.com/tools/skills',
source_type: 'aggregator',
api_endpoint: 'https://mcpmarket.com/api/tools',
total_packages: 0,
},
{
name: 'skillsdirectory',
display_name: 'Skills Directory',
url: 'https://www.skillsdirectory.com/',
source_type: 'aggregator',
api_endpoint: 'https://www.skillsdirectory.com/api/v1/skills?sort=votes',
total_packages: 0,
},
{
name: 'mcpservers-org',
display_name: 'MCPServers.org',
url: 'https://mcpservers.org/agent-skills',
source_type: 'aggregator',
api_endpoint: 'https://mcpservers.org/api/skills',
total_packages: 0,
},
{
name: 'awesome-skills-app',
display_name: 'Awesome Skills App',
url: 'https://awesome-skills.app/',
source_type: 'aggregator',
api_endpoint: 'https://awesome-skills.app/api/skills',
total_packages: 0,
},
{
name: 'awesome-mcp-servers',
display_name: 'Awesome MCP Servers',
url: 'https://github.com/punkpeye/awesome-mcp-servers',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'npm-mcp-servers',
display_name: 'NPM MCP Servers',
url: 'https://www.npmjs.com/search?q=keywords:mcp-server',
source_type: 'npm_registry',
api_endpoint: 'https://registry.npmjs.org/-/v1/search?text=keywords:mcp-server&size=250',
total_packages: 0,
},
{
name: 'npm-mcp-protocol',
display_name: 'NPM MCP Protocol Servers',
url: 'https://www.npmjs.com/search?q=%40modelcontextprotocol',
source_type: 'npm_registry',
api_endpoint: 'https://registry.npmjs.org/-/v1/search?text=@modelcontextprotocol&size=250',
total_packages: 0,
},
// ── GitHub skill repos ─────────────────────────────────────────────
{
name: 'antigravity-awesome-skills',
display_name: 'Antigravity Awesome Skills (1000+)',
url: 'https://github.com/sickn33/antigravity-awesome-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'skillmatic-awesome-skills',
display_name: 'Skillmatic Awesome Agent Skills',
url: 'https://github.com/skillmatic-ai/awesome-agent-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'alirezarezvani-claude-skills',
display_name: 'Claude Skills Collection (192+)',
url: 'https://github.com/alirezarezvani/claude-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'microsoft-skills',
display_name: 'Microsoft Skills (Azure SDK)',
url: 'https://github.com/microsoft/skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'muratcankoylan-context-engineering',
display_name: 'Context Engineering Skills',
url: 'https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'hoodini-ai-agents-skills',
display_name: 'AI Agents Skills (hoodini)',
url: 'https://github.com/hoodini/ai-agents-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'hashicorp-agent-skills',
display_name: 'HashiCorp Agent Skills',
url: 'https://github.com/hashicorp/agent-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'supabase-agent-skills',
display_name: 'Supabase Agent Skills',
url: 'https://github.com/supabase/agent-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'callstack-agent-skills',
display_name: 'Callstack React Native Skills',
url: 'https://github.com/callstackincubator/agent-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
{
name: 'ckanner-agent-skills',
display_name: 'Agent Skills (ckanner)',
url: 'https://github.com/ckanner/agent-skills',
source_type: 'community_repo',
api_endpoint: null,
total_packages: 0,
},
];
/**
* Seed new marketplace sources into the DB.
* Only inserts sources that don't already exist (matched by name).
*
* @returns Count of newly added sources
*/
export function seedNewSources(db: MarketplaceDB): number {
const rawDb = db.getRawDb();
let added = 0;
for (const source of NEW_SOURCES) {
const existing = rawDb
.prepare('SELECT id FROM sources WHERE name = ?')
.get(source.name) as { id: number } | undefined;
if (existing) continue;
rawDb
.prepare(
`INSERT INTO sources (name, display_name, url, source_type, platform, total_packages, install_method, api_endpoint, description)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
)
.run(
source.name,
source.display_name,
source.url,
source.source_type,
'multi',
source.total_packages,
'api_fetch',
source.api_endpoint,
`${source.display_name} — auto-seeded marketplace source`,
);
added++;
}
return added;
}
export { NEW_SOURCES };

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,263 @@
/**
* Waggle Marketplace — Type Definitions
*
* Types for the marketplace database, package installation,
* and integration with Waggle's plugin/skill/MCP systems.
*/
// ─── Database Row Types ───────────────────────────────────────────────
export interface MarketplaceSource {
id: number;
name: string;
display_name: string;
url: string;
source_type: 'marketplace' | 'registry' | 'github_org' | 'community_repo' | 'curated_list' | 'aggregator' | 'npm_registry' | 'official_marketplace' | 'commercial_marketplace' | 'tool' | 'specification';
platform: string;
total_packages: number;
install_method: 'npm' | 'git_clone' | 'download' | 'api_fetch' | 'cli' | 'manual';
api_endpoint: string | null;
description: string;
last_synced_at: string | null;
/** Whether this source was added by the user (vs. built-in seed data). */
is_custom: boolean;
}
export interface MarketplacePackage {
id: number;
source_id: number;
name: string;
display_name: string;
description: string;
author: string;
package_type: 'skill' | 'plugin' | 'mcp_server' | 'template' | 'pack';
waggle_install_type: 'skill' | 'plugin' | 'mcp';
waggle_install_path: string;
version: string;
license: string | null;
repository_url: string | null;
homepage_url: string | null;
downloads: number;
stars: number;
rating: number;
rating_count: number;
category: string;
subcategory: string | null;
install_manifest: InstallManifest | null;
platforms: string[];
min_waggle_version: string | null;
dependencies: string[];
packs: string[];
created_at: string;
updated_at: string;
}
/**
* Input shape accepted by {@link MarketplaceDB.upsertPackage}.
*
* `name` and `source_id` are required. The JSON-serializable columns
* (`platforms`, `dependencies`, `packs`, `install_manifest`) accept EITHER
* their structured form (object/array) OR a pre-serialized JSON string —
* `upsertPackage` serializes objects on the way in, so sync adapters that
* have already called `JSON.stringify()` can pass the string directly.
*/
export type PackageUpsertInput =
& Omit<Partial<MarketplacePackage>, 'platforms' | 'dependencies' | 'packs' | 'install_manifest'>
& {
name: string;
source_id: number;
platforms?: string[] | string;
dependencies?: string[] | string;
packs?: string[] | string;
install_manifest?: InstallManifest | string | null;
};
/**
* Optional security-scan columns persisted on the `packages` table by the
* installer's `recordScanResult()`. They are not part of the core
* {@link MarketplacePackage} shape (a freshly-synced package has none of them),
* so callers that read them must treat every field as possibly-absent.
*/
export interface PackageSecurityColumns {
security_status?: 'unscanned' | 'clean' | 'low' | 'medium' | 'high' | 'critical' | string;
security_score?: number;
last_scanned_at?: string | null;
content_hash?: string | null;
scan_engines?: string | null;
scan_findings?: string | null;
/** 1 = installation was blocked by the security gate, 0 = allowed. */
scan_blocked?: 0 | 1;
}
/** A catalog package row augmented with its (optional) persisted scan columns. */
export type ScannedPackage = MarketplacePackage & PackageSecurityColumns;
/**
* Flat row returned by {@link MarketplaceDB.listInstallations}.
*
* The query joins `installations` (all columns) with a handful of package
* columns aliased as `pkg_*`; it is NOT a nested `{ package: ... }` object.
*/
export interface InstalledPackageRow extends Installation {
pkg_name: string;
pkg_display_name: string;
waggle_install_type: MarketplacePackage['waggle_install_type'];
category: string;
}
export interface MarketplacePack {
id: number;
slug: string;
display_name: string;
description: string;
target_roles: string;
icon: string;
priority: 'core' | 'recommended' | 'optional';
connectors_needed: string[];
created_at: string;
}
export interface Installation {
id: number;
package_id: number;
installed_version: string;
installed_at: string;
install_path: string;
status: 'installed' | 'updating' | 'failed' | 'uninstalled';
config: Record<string, unknown>;
}
// ─── Install Manifest (stored as JSON in packages table) ──────────────
export interface InstallManifest {
/** For skills: the markdown content URL or inline content */
skill_url?: string;
skill_content?: string;
/** For plugins: the plugin.json manifest to write */
plugin_manifest?: PluginManifest;
/** Git repo to clone for plugin files */
git_url?: string;
/** For MCPs: the server configuration */
mcp_config?: McpServerConfig;
/** npm package to install (for MCP servers that need it) */
npm_package?: string;
npm_args?: string[];
/** Post-install hooks */
post_install?: PostInstallHook[];
}
export interface PluginManifest {
name: string;
version: string;
description: string;
skills?: string[];
mcpServers?: McpServerConfig[];
settingsSchema?: Record<string, SettingField>;
}
export interface McpServerConfig {
name: string;
command: string;
args: string[];
env?: Record<string, string>;
}
export interface SettingField {
type: 'string' | 'number' | 'boolean';
description: string;
required?: boolean;
default?: unknown;
}
export interface PostInstallHook {
type: 'run_command' | 'create_file' | 'append_config';
command?: string;
path?: string;
content?: string;
}
// ─── Workflow Types ──────────────────────────────────────────────────
export type InstallationType = 'skill' | 'plugin' | 'mcp';
export interface InstallRequest {
packageId: number;
/** Override install path (default: auto-detected from package) */
installPath?: string;
/** User-provided settings (API keys, etc.) */
settings?: Record<string, string>;
/** Skip confirmation prompt */
force?: boolean;
/** Bypass security gate (DANGEROUS — only for trusted packages) */
forceInsecure?: boolean;
}
export interface InstallResult {
success: boolean;
packageId: number;
packageName: string;
installType: InstallationType;
installPath: string;
message: string;
errors?: string[];
/** Security scan result (attached when scan was performed) */
scanResult?: import('./security.js').ScanResult;
}
export interface PackInstallResult {
packSlug: string;
packName: string;
totalPackages: number;
installed: InstallResult[];
skipped: string[];
failed: InstallResult[];
}
export type SearchSort = 'relevance' | 'popular' | 'recent' | 'name';
export interface SearchOptions {
query?: string;
type?: InstallationType;
category?: string;
pack?: string;
source?: string;
sort?: SearchSort;
limit?: number;
offset?: number;
}
export interface SearchResult {
packages: MarketplacePackage[];
total: number;
facets: {
types: Record<string, number>;
categories: Record<string, number>;
sources: Record<string, number>;
};
/** Total number of installed packages across the whole catalog. */
installedCount: number;
}
export interface SyncOptions {
sources?: string[];
fullRefresh?: boolean;
dryRun?: boolean;
/**
* Scan skill content during sync using SecurityGate.
* Default: false (scanning all packages during sync would be slow).
* Instead, packages are scanned on first install attempt, and the result is cached.
*/
scanDuringSync?: boolean;
}
export interface SyncResult {
source: string;
added: number;
updated: number;
removed: number;
errors: string[];
}