@shnitzel/plugscout 0.3.1

package/dist/interfaces/cli/options.js

@@ -0,0 +1,93 @@
+import { CatalogKindSchema } from '../../lib/validation/contracts.js';
+const KIND_ALIASES = {
+    skill: 'skill',
+    skills: 'skill',
+    mcp: 'mcp',
+    mcps: 'mcp',
+    server: 'mcp',
+    servers: 'mcp',
+    'claude-plugin': 'claude-plugin',
+    'claude-plugins': 'claude-plugin',
+    'claude plugin': 'claude-plugin',
+    'claude plugins': 'claude-plugin',
+    plugin: 'claude-plugin',
+    plugins: 'claude-plugin',
+    'claude-connector': 'claude-connector',
+    'claude-connectors': 'claude-connector',
+    'claude connector': 'claude-connector',
+    'claude connectors': 'claude-connector',
+    connector: 'claude-connector',
+    connectors: 'claude-connector',
+    'copilot-extension': 'copilot-extension',
+    'copilot-extensions': 'copilot-extension',
+    'copilot extension': 'copilot-extension',
+    'copilot extensions': 'copilot-extension',
+    extension: 'copilot-extension',
+    extensions: 'copilot-extension',
+    copilot: 'copilot-extension'
+};
+export function readFlag(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+export function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+export function readKinds(args) {
+    const value = readFlag(args, '--kind');
+    if (!value) {
+        return undefined;
+    }
+    return value
+        .split(',')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0)
+        .map((kind) => normalizeKind(kind));
+}
+export function normalizeKind(raw) {
+    const normalized = raw.trim().toLowerCase();
+    const alias = KIND_ALIASES[normalized];
+    if (alias) {
+        return alias;
+    }
+    try {
+        return CatalogKindSchema.parse(normalized);
+    }
+    catch {
+        throw new Error(`Invalid --kind value: ${raw}. Expected one of: skill, mcp, claude-plugin, claude-connector, copilot-extension. Aliases also supported: skills, mcps, plugins, connectors, extensions.`);
+    }
+}
+export function readCsvList(args, flag) {
+    const value = readFlag(args, flag);
+    if (!value) {
+        return undefined;
+    }
+    return value
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+export function readLimit(args, defaultValue) {
+    const value = readFlag(args, '--limit');
+    if (!value) {
+        return defaultValue;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid --limit value: ${value}`);
+    }
+    return parsed;
+}
+export function readSort(args, defaultValue = 'score') {
+    const value = readFlag(args, '--sort');
+    if (!value) {
+        return defaultValue;
+    }
+    if (value === 'score' || value === 'trust' || value === 'risk' || value === 'fit' || value === 'name') {
+        return value;
+    }
+    throw new Error(`Invalid --sort value: ${value}. Expected one of: score, trust, risk, fit, name`);
+}

package/dist/interfaces/cli/output.js

@@ -0,0 +1,9 @@
+export function printHint(message) {
+    console.log(`Hint: ${message}`);
+}
+export function printSection(title) {
+    console.log(`\n${title}`);
+}
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}

package/dist/interfaces/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/cli/ui/home.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import { loadCatalogItems, loadQuarantine, loadWhitelist } from '../../../catalog/repository.js';
+import { getStaleRegistries, loadSyncState } from '../../../catalog/sync-state.js';
+import { getPackagePath } from '../../../lib/paths.js';
+import { colors } from '../formatters/colors.js';
+export async function renderHomeScreen() {
+    const [logo, pkg, catalogStats, runtimeStats] = await Promise.all([
+        readLogo(),
+        readPackageMeta(),
+        readCatalogStats(),
+        readRuntimeStats()
+    ]);
+    const lines = [];
+    const version = pkg.version ?? '0.0.0';
+    const author = pkg.author ?? '';
+    const renderedLogo = logo
+        .replace('{{version}}', `v${version}`)
+        .replace('{{author}}', author || 'unknown');
+    lines.push(colorIfTty(renderedLogo.trimEnd(), colors.cyan));
+    lines.push('');
+    lines.push('Discover and safely install Claude plugins, Claude connectors, Copilot extensions, Skills, and MCP servers.');
+    lines.push('');
+    lines.push(colorIfTty('Catalog', colors.bold));
+    lines.push(`- items=${catalogStats.items} skill=${catalogStats.skill} mcp=${catalogStats.mcp} claude-plugin=${catalogStats.claudePlugin} claude-connector=${catalogStats.claudeConnector} copilot-extension=${catalogStats.copilotExtension}`);
+    lines.push(`- stale-registries=${runtimeStats.staleRegistries} whitelist=${runtimeStats.whitelist} quarantined=${runtimeStats.quarantined}`);
+    lines.push('');
+    lines.push(colorIfTty('Quick actions', colors.bold));
+    lines.push('- plugscout doctor');
+    lines.push('- plugscout status --verbose');
+    lines.push('- plugscout recommend --project . --only-safe --limit 10');
+    lines.push('- plugscout sync --dry-run');
+    lines.push('- plugscout help');
+    lines.push('');
+    lines.push(colorIfTty('Examples', colors.bold));
+    lines.push('- plugscout list --kind connectors --limit 10');
+    lines.push('- plugscout search github');
+    lines.push('- plugscout show --id claude-connector:asana');
+    lines.push('');
+    lines.push(colorIfTty('Kind aliases', colors.bold));
+    lines.push('- skills, mcps, plugins, connectors, extensions');
+    lines.push('');
+    lines.push(colorIfTty('Ranking meaning', colors.bold));
+    lines.push('- `top` and `recommend` are repo-aware suggestions, not global popularity charts.');
+    lines.push('- score = fit + trust + freshness - security - blocked');
+    lines.push('- higher score means a better match for this repo under current policy');
+    lines.push('- review each suggestion before installing; do not install blindly from rank alone');
+    return lines.join('\n');
+}
+async function readLogo() {
+    try {
+        return await fs.readFile(getPackagePath('assets/cli/logo.txt'), 'utf8');
+    }
+    catch {
+        return 'PlugScout';
+    }
+}
+async function readPackageMeta() {
+    try {
+        const raw = await fs.readFile(getPackagePath('package.json'), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { name: 'plugscout', version: '0.0.0' };
+    }
+}
+async function readCatalogStats() {
+    const items = await loadCatalogItems();
+    let skill = 0;
+    let mcp = 0;
+    let claudePlugin = 0;
+    let claudeConnector = 0;
+    let copilotExtension = 0;
+    items.forEach((item) => {
+        if (item.kind === 'skill') {
+            skill += 1;
+            return;
+        }
+        if (item.kind === 'mcp') {
+            mcp += 1;
+            return;
+        }
+        if (item.kind === 'claude-plugin') {
+            claudePlugin += 1;
+            return;
+        }
+        if (item.kind === 'claude-connector') {
+            claudeConnector += 1;
+            return;
+        }
+        copilotExtension += 1;
+    });
+    return {
+        items: items.length,
+        skill,
+        mcp,
+        claudePlugin,
+        claudeConnector,
+        copilotExtension
+    };
+}
+async function readRuntimeStats() {
+    const [syncState, whitelist, quarantine] = await Promise.all([loadSyncState(), loadWhitelist(), loadQuarantine()]);
+    return {
+        staleRegistries: getStaleRegistries(syncState).length,
+        whitelist: whitelist.size,
+        quarantined: quarantine.length
+    };
+}
+function colorIfTty(value, apply) {
+    if (!process.stdout.isTTY || process.env.NO_COLOR === '1') {
+        return value;
+    }
+    return apply(value);
+}

package/dist/interfaces/cli/ui/web-report.js

@@ -0,0 +1,384 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadCatalogItems, loadQuarantine, loadWhitelist } from '../../../catalog/repository.js';
+import { loadItemInsights, loadSecurityPolicy } from '../../../config/runtime.js';
+import { buildAssessment } from '../../../security/assessment.js';
+export async function writeWebReport(options) {
+    const [items, whitelist, quarantine, policy, insights] = await Promise.all([
+        loadCatalogItems(),
+        loadWhitelist(),
+        loadQuarantine(),
+        loadSecurityPolicy(),
+        loadItemInsights()
+    ]);
+    const filtered = filterByKinds(items, options.kinds).slice(0, options.limit);
+    const quarantineIds = new Set(quarantine.map((entry) => entry.id));
+    const rows = filtered.map((item) => {
+        const assessment = buildAssessment(item, policy);
+        const blockedByPolicy = assessment.riskTier === 'high' || assessment.riskTier === 'critical';
+        const blocked = blockedByPolicy || quarantineIds.has(item.id);
+        return { item, assessment, blocked, approved: whitelist.has(item.id), insight: insights.get(item.id) };
+    });
+    const html = renderHtml(rows, {
+        totalItems: filtered.length,
+        whitelist: whitelist.size,
+        quarantined: quarantine.length
+    }, policy);
+    const resolvedOutput = path.resolve(options.outputPath);
+    await fs.mkdir(path.dirname(resolvedOutput), { recursive: true });
+    await fs.writeFile(resolvedOutput, html, 'utf8');
+    return { outputPath: resolvedOutput, items: filtered.length };
+}
+function filterByKinds(items, kinds) {
+    if (!kinds || kinds.length === 0) {
+        return items;
+    }
+    const set = new Set(kinds);
+    return items.filter((item) => set.has(item.kind));
+}
+function renderHtml(rows, stats, policy) {
+    const kindCounts = countByKind(rows.map((entry) => entry.item));
+    const topClaude = rows.filter((entry) => entry.item.kind === 'claude-plugin').slice(0, 15);
+    const topConnectors = rows.filter((entry) => entry.item.kind === 'claude-connector').slice(0, 15);
+    const topCopilot = rows.filter((entry) => entry.item.kind === 'copilot-extension').slice(0, 15);
+    const allRows = rows.slice(0, 120);
+    const detailRows = rows.slice(0, 80);
+    const riskScale = escapeHtml(formatRiskScale(policy));
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>PlugScout Web Report</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #050916;
+      --panel: #0e1628;
+      --line: #22314d;
+      --text: #e5edf8;
+      --muted: #a8b6cc;
+      --ok: #22c55e;
+      --warn: #f59e0b;
+      --bad: #ef4444;
+      --accent: #60a5fa;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font: 15px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+      color: var(--text);
+      background: radial-gradient(circle at top, #111b33 0%, var(--bg) 45%);
+      padding: 28px;
+    }
+    .wrap { max-width: 1460px; margin: 0 auto; }
+    h1 { margin: 0 0 8px; font-size: 34px; }
+    .sub { color: var(--muted); margin: 0 0 22px; }
+    .cards {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(180px, 1fr));
+      gap: 12px;
+      margin-bottom: 18px;
+    }
+    .card {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      padding: 14px;
+    }
+    .k { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .v { font-size: 26px; font-weight: 700; margin-top: 4px; }
+    .section {
+      margin-top: 18px;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      overflow: hidden;
+    }
+    .section-body { padding: 14px 16px; }
+    .section h2 {
+      margin: 0;
+      padding: 14px 16px;
+      font-size: 18px;
+      border-bottom: 1px solid var(--line);
+      color: var(--accent);
+    }
+    table { width: 100%; border-collapse: collapse; }
+    th, td {
+      text-align: left;
+      padding: 10px 12px;
+      border-bottom: 1px solid #1d2a41;
+      vertical-align: top;
+      word-break: break-word;
+    }
+    th { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.04em; }
+    .pill {
+      display: inline-block;
+      border-radius: 999px;
+      border: 1px solid #314664;
+      padding: 2px 9px;
+      font-size: 12px;
+      color: var(--text);
+      white-space: nowrap;
+    }
+    .ok { color: var(--ok); border-color: #166534; }
+    .warn { color: var(--warn); border-color: #854d0e; }
+    .bad { color: var(--bad); border-color: #7f1d1d; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; font-size: 13px; }
+    .detail-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(360px, 1fr));
+      gap: 12px;
+      padding: 14px;
+    }
+    .detail-card {
+      border: 1px solid #243654;
+      border-radius: 10px;
+      background: #081121;
+      padding: 12px;
+    }
+    .detail-head {
+      display: flex;
+      align-items: flex-start;
+      justify-content: space-between;
+      gap: 10px;
+      margin-bottom: 8px;
+    }
+    .title {
+      margin: 0;
+      font-size: 16px;
+      line-height: 1.3;
+    }
+    .meta {
+      color: var(--muted);
+      font-size: 12px;
+      margin-top: 4px;
+    }
+    .line { margin-top: 8px; color: var(--text); }
+    .line .label { color: var(--muted); }
+    .chips { margin-top: 8px; display: flex; flex-wrap: wrap; gap: 6px; }
+    .chip {
+      border: 1px solid #2f476b;
+      border-radius: 999px;
+      padding: 2px 8px;
+      color: #c9dbf5;
+      font-size: 12px;
+    }
+    .link { color: #93c5fd; text-decoration: none; }
+    .link:hover { text-decoration: underline; }
+    pre {
+      margin: 8px 0 0;
+      padding: 9px 10px;
+      border: 1px solid #243654;
+      border-radius: 8px;
+      background: #060f1d;
+      overflow-x: auto;
+      color: #dbeafe;
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>PlugScout Web Report</h1>
+    <p class="sub">Readable catalog view for Claude plugins, Claude connectors, Copilot extensions, Skills, and MCP servers.</p>
+    <div class="cards">
+      <div class="card"><div class="k">Items</div><div class="v">${stats.totalItems}</div></div>
+      <div class="card"><div class="k">Claude Plugins</div><div class="v">${kindCounts['claude-plugin']}</div></div>
+      <div class="card"><div class="k">Claude Connectors</div><div class="v">${kindCounts['claude-connector']}</div></div>
+      <div class="card"><div class="k">Copilot Extensions</div><div class="v">${kindCounts['copilot-extension']}</div></div>
+      <div class="card"><div class="k">Skills</div><div class="v">${kindCounts.skill}</div></div>
+      <div class="card"><div class="k">MCP Servers</div><div class="v">${kindCounts.mcp}</div></div>
+      <div class="card"><div class="k">Whitelist / Quarantine</div><div class="v">${stats.whitelist} / ${stats.quarantined}</div></div>
+    </div>
+    <section class="section">
+      <h2>How to read scores</h2>
+      <div class="section-body">
+        <div><span class="pill ok">trust</span> 0-100, higher is better.</div>
+        <div style="margin-top:6px;"><span class="pill warn">risk</span> 0-100, lower is safer. ${riskScale}</div>
+        <div style="margin-top:6px;"><span class="pill bad">blocked</span> means policy high/critical risk or quarantined.</div>
+      </div>
+    </section>
+    ${renderTableSection('Top Claude Plugins', topClaude)}
+    ${renderTableSection('Top Claude Connectors', topConnectors)}
+    ${renderTableSection('Top Copilot Extensions', topCopilot)}
+    ${renderTableSection('Catalog Snapshot', allRows)}
+    ${renderDetailSection('Decision details per item', detailRows, policy)}
+  </div>
+</body>
+</html>`;
+}
+function renderTableSection(title, rows) {
+    return `<section class="section">
+  <h2>${escapeHtml(title)}</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>ID</th>
+        <th>Name</th>
+        <th>Kind</th>
+        <th>Provider</th>
+        <th>Trust</th>
+        <th>Source</th>
+        <th>Confidence</th>
+        <th>Risk</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${rows
+        .map((entry) => {
+        const metadata = asMetadata(entry.item.metadata);
+        const confidence = stringOr(metadata.sourceConfidence, 'official');
+        const trustScore = computeTrustScore(entry.item);
+        const riskClass = entry.assessment.riskTier === 'low'
+            ? 'ok'
+            : entry.assessment.riskTier === 'medium'
+                ? 'warn'
+                : 'bad';
+        return `<tr>
+            <td class="mono">${escapeHtml(entry.item.id)}</td>
+            <td>${escapeHtml(entry.item.name)}</td>
+            <td>${escapeHtml(entry.item.kind)}</td>
+            <td>${escapeHtml(entry.item.provider)}</td>
+            <td><span class="pill">${trustScore.toFixed(0)}</span></td>
+            <td>${escapeHtml(entry.item.source)}</td>
+            <td><span class="pill">${escapeHtml(confidence)}</span></td>
+            <td><span class="pill ${riskClass}">${escapeHtml(entry.assessment.riskTier)} (${entry.assessment.riskScore.toFixed(0)})</span></td>
+            <td>${entry.blocked ? '<span class="pill bad">blocked</span>' : entry.approved ? '<span class="pill ok">approved</span>' : '<span class="pill ok">allowed</span>'}</td>
+          </tr>`;
+    })
+        .join('\n')}
+    </tbody>
+  </table>
+</section>`;
+}
+function renderDetailSection(title, rows, policy) {
+    return `<section class="section">
+  <h2>${escapeHtml(title)}</h2>
+  <div class="detail-grid">
+    ${rows.map((entry) => renderDetailCard(entry, policy)).join('\n')}
+  </div>
+</section>`;
+}
+function renderDetailCard(entry, policy) {
+    const metadata = asMetadata(entry.item.metadata);
+    const trustScore = computeTrustScore(entry.item);
+    const confidence = stringOr(metadata.sourceConfidence, 'official');
+    const catalogType = stringOr(metadata.catalogType, 'standard');
+    const sourceRepo = typeof metadata.sourceRepo === 'string' ? metadata.sourceRepo : '';
+    const sourcePage = typeof metadata.sourcePage === 'string' ? metadata.sourcePage : '';
+    const status = entry.blocked ? 'blocked' : entry.approved ? 'approved' : 'allowed';
+    const installHint = buildInstallHint(entry.item);
+    const bestFor = entry.insight?.bestFor ?? [];
+    const tradeoffs = entry.insight?.tradeoffs ?? [];
+    return `<article class="detail-card">
+    <div class="detail-head">
+      <div>
+        <h3 class="title">${escapeHtml(entry.item.name)}</h3>
+        <div class="meta mono">${escapeHtml(entry.item.id)}</div>
+      </div>
+      <div>
+        <span class="pill">${escapeHtml(entry.item.kind)}</span>
+      </div>
+    </div>
+    <div class="line">${escapeHtml(entry.item.description)}</div>
+    <div class="line"><span class="label">Decision:</span> trust ${trustScore.toFixed(0)}/100 (${escapeHtml(describeTrustBand(trustScore))}), risk ${entry.assessment.riskScore.toFixed(0)}/100 (${escapeHtml(entry.assessment.riskTier)}; ${escapeHtml(describeRiskBand(entry.assessment.riskScore, policy))}), status ${escapeHtml(status)}.</div>
+    <div class="line"><span class="label">Risk reasons:</span> ${escapeHtml(entry.assessment.reasons.join('; '))}</div>
+    <div class="line"><span class="label">Provenance:</span> provider=${escapeHtml(entry.item.provider)} source=${escapeHtml(entry.item.source)} confidence=${escapeHtml(confidence)} catalog=${escapeHtml(catalogType)}</div>
+    ${sourceRepo
+        ? `<div class="line"><span class="label">Source repo:</span> <a class="link" href="${escapeHtml(sourceRepo)}">${escapeHtml(sourceRepo)}</a></div>`
+        : ''}
+    ${sourcePage
+        ? `<div class="line"><span class="label">Source page:</span> <a class="link" href="${escapeHtml(sourcePage)}">${escapeHtml(sourcePage)}</a></div>`
+        : ''}
+    ${bestFor.length > 0
+        ? `<div class="line"><span class="label">Best for:</span> ${escapeHtml(bestFor.join('; '))}</div>`
+        : ''}
+    ${tradeoffs.length > 0
+        ? `<div class="line"><span class="label">Tradeoffs:</span> ${escapeHtml(tradeoffs.join('; '))}</div>`
+        : ''}
+    <div class="chips">${renderChips(entry.item.capabilities)}</div>
+    <pre class="mono">${escapeHtml(installHint)}</pre>
+  </article>`;
+}
+function renderChips(values) {
+    if (values.length === 0) {
+        return '<span class="chip">no capability tags</span>';
+    }
+    return values
+        .slice(0, 8)
+        .map((value) => `<span class="chip">${escapeHtml(value)}</span>`)
+        .join('');
+}
+function buildInstallHint(item) {
+    if (item.install.kind === 'manual') {
+        if (item.install.url) {
+            return `Manual install: ${item.install.url}`;
+        }
+        return `Manual install: ${item.install.instructions}`;
+    }
+    const args = item.install.args.length > 0 ? ` ${item.install.args.join(' ')}` : '';
+    return `${item.install.kind} ${item.install.target}${args}`;
+}
+function computeTrustScore(item) {
+    return (item.maintenanceSignal + item.provenanceSignal + item.adoptionSignal) / 3;
+}
+function describeTrustBand(score) {
+    if (score >= 80) {
+        return 'high confidence';
+    }
+    if (score >= 60) {
+        return 'moderate confidence';
+    }
+    return 'needs review';
+}
+function describeRiskBand(score, policy) {
+    if (score <= policy.thresholds.lowMax) {
+        return 'low-risk zone';
+    }
+    if (score <= policy.thresholds.mediumMax) {
+        return 'medium-risk zone';
+    }
+    if (score <= policy.thresholds.highMax) {
+        return 'high-risk zone';
+    }
+    return 'critical-risk zone';
+}
+function formatRiskScale(policy) {
+    const low = policy.thresholds.lowMax;
+    const medium = policy.thresholds.mediumMax;
+    const high = policy.thresholds.highMax;
+    return `low 0-${low}, medium ${low + 1}-${medium}, high ${medium + 1}-${high}, critical ${high + 1}-${policy.thresholds.criticalMax}; install gate blocks: ${policy.installGate.blockTiers.join(', ')}.`;
+}
+function asMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function stringOr(value, fallback) {
+    if (typeof value === 'string' && value.trim().length > 0) {
+        return value;
+    }
+    return fallback;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+function countByKind(items) {
+    return items.reduce((acc, item) => {
+        acc[item.kind] += 1;
+        return acc;
+    }, {
+        skill: 0,
+        mcp: 0,
+        'claude-plugin': 0,
+        'claude-connector': 0,
+        'copilot-extension': 0
+    });
+}