@shnitzel/plugscout 0.3.1

package/dist/interfaces/cli/update-check.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs/promises';
+import semver from 'semver';
+import { readJsonFile, writeJsonFile } from '../../lib/json.js';
+import { getPackagePath, getStatePath } from '../../lib/paths.js';
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 2500;
+const RELEASE_REPO = 'amitrintzler/skills-and-mcps';
+export const RELEASE_API_URL = `https://api.github.com/repos/${RELEASE_REPO}/releases/latest`;
+export const RELEASE_DOWNLOAD_URL = `https://github.com/${RELEASE_REPO}/releases/latest`;
+export function getUpdateCheckStatePath() {
+    return getStatePath('data/system/update-check.json');
+}
+export function normalizeReleaseVersion(tag) {
+    const clean = tag.trim().replace(/^v/i, '');
+    const strict = semver.valid(clean);
+    if (strict) {
+        return strict;
+    }
+    const coerced = semver.coerce(clean);
+    return coerced ? coerced.version : null;
+}
+export function isVersionNewer(candidate, current) {
+    const normalizedCurrent = normalizeReleaseVersion(current);
+    const normalizedCandidate = normalizeReleaseVersion(candidate);
+    if (!normalizedCurrent || !normalizedCandidate) {
+        return false;
+    }
+    return semver.gt(normalizedCandidate, normalizedCurrent);
+}
+export function isCacheFresh(lastCheckedAt, now = new Date()) {
+    if (!lastCheckedAt) {
+        return false;
+    }
+    const parsed = Date.parse(lastCheckedAt);
+    if (!Number.isFinite(parsed)) {
+        return false;
+    }
+    return now.getTime() - parsed < UPDATE_CHECK_TTL_MS;
+}
+export function isUpdateCheckDisabled(options) {
+    if (options.disableAutoCheck) {
+        return true;
+    }
+    if (process.env.PLUGSCOUT_DISABLE_UPDATE_CHECK === '1' || process.env.TOOLKIT_DISABLE_UPDATE_CHECK === '1') {
+        return true;
+    }
+    if (process.env.CI) {
+        return true;
+    }
+    return !process.stdout.isTTY;
+}
+export async function maybeNotifyAboutUpdate(options = {}) {
+    if (isUpdateCheckDisabled(options)) {
+        return;
+    }
+    const currentVersion = await loadCurrentVersion();
+    let state = await loadUpdateCheckState();
+    if (!isCacheFresh(state.lastCheckedAt) || !state.latestVersion) {
+        const fetched = await lookupLatestReleaseVersion();
+        state = {
+            ...state,
+            lastCheckedAt: new Date().toISOString(),
+            source: 'github-releases'
+        };
+        if (fetched.status === 'ok') {
+            state.latestVersion = fetched.latestVersion;
+        }
+        if (fetched.status === 'no-release') {
+            delete state.latestVersion;
+        }
+        await saveUpdateCheckState(state);
+        if (fetched.status !== 'ok') {
+            return;
+        }
+    }
+    if (!state.latestVersion || !isVersionNewer(state.latestVersion, currentVersion)) {
+        return;
+    }
+    if (state.lastNotifiedVersion === state.latestVersion) {
+        return;
+    }
+    console.log(`New PlugScout version available: v${currentVersion} -> v${state.latestVersion}`);
+    console.log(`Download: ${RELEASE_DOWNLOAD_URL}`);
+    await saveUpdateCheckState({
+        ...state,
+        source: 'github-releases',
+        lastNotifiedVersion: state.latestVersion
+    });
+}
+export async function checkForUpdateNow() {
+    const currentVersion = await loadCurrentVersion();
+    const result = await lookupLatestReleaseVersion();
+    if (result.status === 'error') {
+        return { status: 'error', currentVersion };
+    }
+    if (result.status === 'no-release') {
+        await saveUpdateCheckState({
+            ...(await loadUpdateCheckState()),
+            source: 'github-releases',
+            lastCheckedAt: new Date().toISOString(),
+            latestVersion: undefined
+        });
+        return { status: 'no-release', currentVersion };
+    }
+    await saveUpdateCheckState({
+        ...(await loadUpdateCheckState()),
+        source: 'github-releases',
+        lastCheckedAt: new Date().toISOString(),
+        latestVersion: result.latestVersion
+    });
+    if (isVersionNewer(result.latestVersion, currentVersion)) {
+        return { status: 'update-available', currentVersion, latestVersion: result.latestVersion };
+    }
+    return { status: 'up-to-date', currentVersion, latestVersion: result.latestVersion };
+}
+async function lookupLatestReleaseVersion() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(RELEASE_API_URL, {
+            method: 'GET',
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/vnd.github+json',
+                'User-Agent': 'plugscout-cli'
+            }
+        });
+        if (response.status === 404) {
+            return { status: 'no-release' };
+        }
+        if (!response.ok) {
+            return { status: 'error' };
+        }
+        const payload = (await response.json());
+        const normalized = normalizeReleaseVersion(payload.tag_name ?? '');
+        if (!normalized) {
+            return { status: 'error' };
+        }
+        return { status: 'ok', latestVersion: normalized };
+    }
+    catch {
+        return { status: 'error' };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function loadCurrentVersion() {
+    try {
+        const raw = await fs.readFile(getPackagePath('package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        const normalized = normalizeReleaseVersion(parsed.version ?? '');
+        return normalized ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function loadUpdateCheckState() {
+    const filePath = getUpdateCheckStatePath();
+    try {
+        const raw = await readJsonFile(filePath);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return {};
+        }
+        const typed = raw;
+        return {
+            lastCheckedAt: typeof typed.lastCheckedAt === 'string' ? typed.lastCheckedAt : undefined,
+            latestVersion: typeof typed.latestVersion === 'string' ? typed.latestVersion : undefined,
+            lastNotifiedVersion: typeof typed.lastNotifiedVersion === 'string' ? typed.lastNotifiedVersion : undefined,
+            source: typed.source === 'github-releases' ? 'github-releases' : undefined
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function saveUpdateCheckState(state) {
+    await writeJsonFile(getUpdateCheckStatePath(), state);
+}

package/dist/lib/json.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+export async function readJsonFile(filePath) {
+    const fullPath = path.resolve(filePath);
+    return fs.readJson(fullPath);
+}
+export async function writeJsonFile(filePath, data) {
+    const fullPath = path.resolve(filePath);
+    await fs.ensureFile(fullPath);
+    await fs.writeJson(fullPath, data, { spaces: 2 });
+}

package/dist/lib/logger.js

@@ -0,0 +1,13 @@
+function log(level, message, payload) {
+    const time = new Date().toISOString();
+    if (payload) {
+        console[level === 'info' ? 'log' : level](`[${time}] [${level.toUpperCase()}] ${message}`, payload);
+        return;
+    }
+    console[level === 'info' ? 'log' : level](`[${time}] [${level.toUpperCase()}] ${message}`);
+}
+export const logger = {
+    info: (message, payload) => log('info', message, payload),
+    warn: (message, payload) => log('warn', message, payload),
+    error: (message, payload) => log('error', message, payload)
+};

package/dist/lib/paths.js

@@ -0,0 +1,18 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(MODULE_DIR, '../..');
+export function getPackageRoot() {
+    return PACKAGE_ROOT;
+}
+export function getPackagePath(...segments) {
+    return path.resolve(PACKAGE_ROOT, ...segments);
+}
+export function getToolkitHome() {
+    const root = process.env.PLUGSCOUT_HOME ?? process.env.TOOLKIT_HOME ?? path.join(os.homedir(), '.plugscout');
+    return path.resolve(root);
+}
+export function getStatePath(...segments) {
+    return path.resolve(getToolkitHome(), ...segments);
+}

package/dist/lib/validation/contracts.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+const isoDate = z
+    .string()
+    .regex(/^(19|20|21)\d{2}-[01]\d-[0-3]\d$/, 'Expected ISO date (YYYY-MM-DD)');
+export const RiskTierSchema = z.enum(['low', 'medium', 'high', 'critical']);
+export const CatalogKindSchema = z.enum(['skill', 'mcp', 'claude-plugin', 'claude-connector', 'copilot-extension']);
+const SecuritySignalsSchema = z
+    .object({
+    knownVulnerabilities: z.number().int().min(0).default(0),
+    suspiciousPatterns: z.number().int().min(0).default(0),
+    injectionFindings: z.number().int().min(0).default(0),
+    exfiltrationSignals: z.number().int().min(0).default(0),
+    integrityAlerts: z.number().int().min(0).default(0)
+})
+    .default({});
+export const InstallMethodSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('skill.sh'),
+        target: z.string().min(1),
+        args: z.array(z.string()).default([])
+    }),
+    z.object({
+        kind: z.literal('gh-cli'),
+        target: z.string().min(1),
+        args: z.array(z.string()).default([])
+    }),
+    z.object({
+        kind: z.literal('manual'),
+        instructions: z.string().min(1),
+        url: z.string().url().optional()
+    })
+]);
+export const CatalogItemSchema = z.object({
+    id: z.string().min(1),
+    kind: CatalogKindSchema,
+    name: z.string().min(1),
+    description: z.string().min(1),
+    provider: z.string().min(1),
+    capabilities: z.array(z.string().min(1)).default([]),
+    compatibility: z.array(z.string().min(1)).default([]),
+    source: z.string().min(1),
+    lastSeenAt: isoDate,
+    transport: z.enum(['stdio', 'http', 'sse', 'websocket']).optional(),
+    authModel: z.enum(['none', 'api_key', 'oauth', 'custom']).optional(),
+    install: InstallMethodSchema,
+    adoptionSignal: z.number().min(0).max(100).default(50),
+    maintenanceSignal: z.number().min(0).max(100).default(50),
+    provenanceSignal: z.number().min(0).max(100).default(80),
+    freshnessSignal: z.number().min(0).max(100).default(50),
+    securitySignals: SecuritySignalsSchema,
+    metadata: z.record(z.unknown()).default({})
+});
+export const CatalogSkillSchema = CatalogItemSchema.extend({
+    kind: z.literal('skill')
+});
+export const CatalogMcpServerSchema = CatalogItemSchema.extend({
+    kind: z.literal('mcp'),
+    transport: z.enum(['stdio', 'http', 'sse', 'websocket']).default('stdio'),
+    authModel: z.enum(['none', 'api_key', 'oauth', 'custom']).default('none')
+});
+export const RiskAssessmentSchema = z.object({
+    id: z.string().min(1),
+    riskScore: z.number().min(0).max(100),
+    riskTier: RiskTierSchema,
+    reasons: z.array(z.string().min(1)).nonempty(),
+    scannerResults: z.object({
+        packageIntegrity: z.object({ findings: z.number().int().min(0) }),
+        vulnerabilityIntel: z.object({ findings: z.number().int().min(0) }),
+        permissionPatterns: z.object({ findings: z.number().int().min(0) }),
+        injectionTests: z.object({ findings: z.number().int().min(0) }),
+        exfiltrationHeuristics: z.object({ findings: z.number().int().min(0) })
+    }),
+    assessedAt: z.string().datetime()
+});
+export const RecommendationSchema = z.object({
+    id: z.string().min(1),
+    kind: CatalogKindSchema,
+    provider: z.string().min(1),
+    rankScore: z.number().min(0).max(100),
+    fitReasons: z.array(z.string().min(1)).nonempty(),
+    scoreBreakdown: z.object({
+        fitScore: z.number().min(0).max(100),
+        trustScore: z.number().min(0).max(100),
+        securityPenalty: z.number().min(0).max(100),
+        freshnessBonus: z.number().min(0).max(100),
+        blockedPenalty: z.number().min(0).max(100)
+    }),
+    riskTier: RiskTierSchema,
+    riskScore: z.number().min(0).max(100),
+    blocked: z.boolean(),
+    blockReason: z.string().optional(),
+    installMethod: z.enum(['skill.sh', 'gh-cli', 'manual'])
+});
+export const InstallAuditSchema = z.object({
+    id: z.string().min(1),
+    requestedAt: z.string().datetime(),
+    policyDecision: z.enum(['allowed', 'blocked', 'override-allowed']),
+    overrideUsed: z.boolean(),
+    installer: z.enum(['skill.sh', 'gh-cli', 'manual', 'skills', 'npm', 'docker']),
+    exitCode: z.number().int()
+});
+export const RemoteRegistrySchema = z.object({
+    url: z.string().url(),
+    format: z.enum(['json-array', 'catalog-json', 'html']).default('json-array'),
+    entryPath: z.string().min(1).optional(),
+    supportsUpdatedSince: z.boolean().default(false),
+    updatedSinceParam: z.string().min(1).default('updated_since'),
+    pagination: z
+        .object({
+        mode: z.literal('cursor').default('cursor'),
+        cursorParam: z.string().min(1).default('cursor'),
+        nextCursorPath: z.string().min(1).default('next_cursor'),
+        limitParam: z.string().min(1).optional(),
+        limit: z.number().int().min(1).max(1000).optional()
+    })
+        .optional(),
+    timeoutMs: z.number().int().min(100).max(120000).default(10000),
+    authEnv: z.string().min(1).optional(),
+    fallbackToLocal: z.boolean().default(true),
+    provider: z.string().min(1).optional(),
+    official: z.boolean().default(true),
+    licenseHint: z.string().min(1).optional()
+});
+export const RegistrySchema = z.object({
+    id: z.string().min(1),
+    kind: CatalogKindSchema,
+    sourceType: z.enum(['public-index', 'vendor-feed', 'community-list']),
+    adapter: z
+        .enum([
+        'direct',
+        'mcp-registry-v0.1',
+        'openai-skills-v1',
+        'openai-skills-github-v1',
+        'claude-plugins-v0.1',
+        'claude-plugins-scrape-v1',
+        'claude-code-marketplace-v1',
+        'copilot-extensions-v0.1',
+        'copilot-plugin-marketplace-v1',
+        'claude-connectors-scrape-v1'
+    ])
+        .default('direct'),
+    enabled: z.boolean().default(true),
+    officialOnly: z.boolean().default(true),
+    entries: z.array(z.unknown()).default([]),
+    remote: RemoteRegistrySchema.optional()
+});
+export const RegistriesFileSchema = z.object({
+    registries: z.array(RegistrySchema)
+});
+export const SecurityPolicySchema = z.object({
+    thresholds: z.object({
+        lowMax: z.number().int().min(0).max(100).default(24),
+        mediumMax: z.number().int().min(0).max(100).default(49),
+        highMax: z.number().int().min(0).max(100).default(74),
+        criticalMax: z.number().int().min(0).max(100).default(100)
+    }),
+    installGate: z.object({
+        blockTiers: z.array(RiskTierSchema).default(['high', 'critical']),
+        warnTiers: z.array(RiskTierSchema).default(['medium'])
+    }),
+    scoring: z.object({
+        vulnerabilityWeight: z.number().int().min(1).default(15),
+        suspiciousWeight: z.number().int().min(1).default(10),
+        injectionWeight: z.number().int().min(1).default(12),
+        exfiltrationWeight: z.number().int().min(1).default(12),
+        integrityWeight: z.number().int().min(1).default(10)
+    })
+});
+export const RankingPolicySchema = z.object({
+    weights: z.object({
+        compatibility: z.number().min(0).max(100).default(25),
+        capabilityCoverage: z.number().min(0).max(100).default(20),
+        maintenance: z.number().min(0).max(100).default(18),
+        provenance: z.number().min(0).max(100).default(18),
+        adoption: z.number().min(0).max(100).default(12),
+        freshnessBonusMax: z.number().min(0).max(100).default(8),
+        securityPenaltyMax: z.number().min(0).max(100).default(40),
+        blockedPenalty: z.number().min(0).max(100).default(40)
+    }),
+    tieBreakers: z.array(z.enum(['trust', 'risk', 'name'])).default(['trust', 'risk', 'name']),
+    blockedFloorTier: RiskTierSchema.default('high')
+});
+export const RecommendationWeightsSchema = z.object({
+    compatibility: z.number().min(0).max(100).default(40),
+    capabilityCoverage: z.number().min(0).max(100).default(25),
+    maintenance: z.number().min(0).max(100).default(15),
+    adoption: z.number().min(0).max(100).default(10),
+    securityPenaltyMax: z.number().min(0).max(100).default(30)
+});
+export const ProviderConfigSchema = z.object({
+    id: z.string().min(1),
+    enabled: z.boolean().default(true),
+    officialOnly: z.boolean().default(true),
+    trustLevel: z.enum(['high', 'medium', 'low']).default('high'),
+    authEnv: z.string().min(1).optional(),
+    poll: z.object({
+        mode: z.enum(['daily', 'manual', 'every-6h']).default('daily'),
+        rateLimitPerMinute: z.number().int().min(1).max(1000).default(60)
+    })
+});
+export const ProvidersFileSchema = z.object({
+    providers: z.array(ProviderConfigSchema)
+});
+export const ItemInsightSchema = z.object({
+    id: z.string().min(1),
+    benefitSummary: z.string().min(1),
+    bestFor: z.array(z.string().min(1)).default([]),
+    whenToUse: z.array(z.string().min(1)).default([]),
+    tradeoffs: z.array(z.string().min(1)).default([]),
+    usageNotes: z.array(z.string().min(1)).default([])
+});
+export const ItemInsightsFileSchema = z.object({
+    insights: z.array(ItemInsightSchema)
+});
+export const RequirementsProfileSchema = z.object({
+    useCase: z.string().default('general'),
+    stack: z.array(z.string()).default([]),
+    deployment: z.string().default('local'),
+    securityPosture: z.enum(['balanced', 'strict']).default('balanced'),
+    requiredCapabilities: z.array(z.string()).default([])
+});
+export const WhitelistFileSchema = z.object({
+    approved: z.array(z.string().min(1)).default([])
+});
+export const QuarantineEntrySchema = z.object({
+    id: z.string().min(1),
+    reason: z.string().min(1),
+    quarantinedAt: z.string().datetime()
+});
+export const QuarantineFileSchema = z.object({
+    quarantined: z.array(QuarantineEntrySchema).default([])
+});
+export const SecurityReportSchema = z.object({
+    generatedAt: z.string().datetime(),
+    staleRegistries: z.array(z.string().min(1)).default([]),
+    passed: z.array(z.string()).default([]),
+    failed: z
+        .array(z.object({
+        id: z.string().min(1),
+        riskTier: RiskTierSchema,
+        riskScore: z.number().min(0).max(100),
+        reasons: z.array(z.string()).nonempty()
+    }))
+        .default([])
+});

package/dist/mcps/normalize.js

@@ -0,0 +1,38 @@
+import { CatalogMcpServerSchema } from '../lib/validation/contracts.js';
+export function normalizeMcps(records, sourceId, today) {
+    return records
+        .map((entry) => CatalogMcpServerSchema.parse({
+        ...ensureObject(entry),
+        source: ensureObject(entry).source ?? sourceId,
+        lastSeenAt: ensureObject(entry).lastSeenAt ?? today
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function ensureObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid MCP registry entry: expected object');
+    }
+    return value;
+}
+export function mergeMcpsById(mcps) {
+    const state = new Map();
+    for (const mcp of mcps) {
+        const existing = state.get(mcp.id);
+        if (!existing) {
+            state.set(mcp.id, mcp);
+            continue;
+        }
+        state.set(mcp.id, {
+            ...existing,
+            capabilities: dedupe([...existing.capabilities, ...mcp.capabilities]),
+            compatibility: dedupe([...existing.compatibility, ...mcp.compatibility]),
+            maintenanceSignal: Math.max(existing.maintenanceSignal, mcp.maintenanceSignal),
+            adoptionSignal: Math.max(existing.adoptionSignal, mcp.adoptionSignal),
+            lastSeenAt: mcp.lastSeenAt >= existing.lastSeenAt ? mcp.lastSeenAt : existing.lastSeenAt
+        });
+    }
+    return Array.from(state.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+function dedupe(values) {
+    return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}

package/dist/models/records.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+const isoDate = z
+    .string()
+    .regex(/^(19|20|21)\d{2}-[01]\d-[0-3]\d$/, 'Must be an ISO date (YYYY-MM-DD)');
+export const SkillSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    taxonomyPath: z.array(z.string().min(1)).nonempty(),
+    aliases: z.array(z.string().min(1)).default([]),
+    proficiencyLevels: z.array(z.string().min(1)).nonempty(),
+    lastValidated: isoDate
+});
+const rangeSchema = z
+    .object({
+    min: z.number().nonnegative(),
+    mid: z.number().nonnegative(),
+    max: z.number().nonnegative()
+})
+    .refine((value) => value.min <= value.mid && value.mid <= value.max, {
+    message: 'Expected min <= mid <= max'
+});
+export const McpSchema = z.object({
+    jobFamily: z.string().min(1),
+    level: z.string().min(1),
+    currency: z.string().min(1),
+    baseRange: rangeSchema,
+    geoModifier: z.record(z.number().positive()),
+    skillLinks: z.array(z.string().min(1)).nonempty(),
+    lastBenchmark: isoDate
+});

package/dist/recommendation/engine.js

@@ -0,0 +1,135 @@
+import { loadRankingPolicy, loadSecurityPolicy } from '../config/runtime.js';
+import { loadCatalogItems, loadQuarantine } from '../catalog/repository.js';
+import { RecommendationSchema } from '../lib/validation/contracts.js';
+import { buildAssessment, isBlockedTier } from '../security/assessment.js';
+export async function recommend(options) {
+    const [items, quarantinedEntries, rankingPolicy, securityPolicy] = await Promise.all([
+        loadCatalogItems(),
+        loadQuarantine(),
+        loadRankingPolicy(),
+        loadSecurityPolicy()
+    ]);
+    const kindFilter = options.kinds?.length ? new Set(options.kinds) : null;
+    const filteredItems = kindFilter ? items.filter((item) => kindFilter.has(item.kind)) : items;
+    const quarantinedIds = new Set(quarantinedEntries.map((entry) => entry.id));
+    return filteredItems
+        .map((candidate) => rankCandidate(candidate, options.projectSignals, options.requirements, rankingPolicy, securityPolicy, quarantinedIds))
+        .sort(sortRecommendations);
+}
+function rankCandidate(candidate, projectSignals, requirements, rankingPolicy, securityPolicy, quarantinedIds) {
+    const assessment = buildAssessment(candidate, securityPolicy);
+    const effectiveRequiredCapabilities = dedupe([
+        ...requirements.requiredCapabilities,
+        ...projectSignals.inferredCapabilities
+    ]);
+    const compatibilityScore = overlapScore(candidate.compatibility, [
+        ...projectSignals.compatibilityTags,
+        ...requirements.stack
+    ]);
+    const capabilityScore = overlapScore(candidate.capabilities, effectiveRequiredCapabilities);
+    const inferredCapabilityMatches = countMatches(candidate.capabilities, projectSignals.inferredCapabilities);
+    const fitScore = compatibilityScore * (rankingPolicy.weights.compatibility / 100) +
+        capabilityScore * (rankingPolicy.weights.capabilityCoverage / 100);
+    const trustScore = candidate.maintenanceSignal * (rankingPolicy.weights.maintenance / 100) +
+        candidate.provenanceSignal * (rankingPolicy.weights.provenance / 100) +
+        candidate.adoptionSignal * (rankingPolicy.weights.adoption / 100);
+    const freshnessBonus = (candidate.freshnessSignal / 100) * rankingPolicy.weights.freshnessBonusMax;
+    const baseSecurityPenalty = (assessment.riskScore / 100) * rankingPolicy.weights.securityPenaltyMax;
+    const sourcePenalty = computeSourcePenalty(candidate);
+    const securityPenalty = Math.min(100, baseSecurityPenalty + sourcePenalty);
+    const blockedByPolicy = isBlockedTier(assessment.riskTier, securityPolicy);
+    const blockedByQuarantine = quarantinedIds.has(candidate.id);
+    const blocked = blockedByPolicy || blockedByQuarantine;
+    const blockedPenalty = blocked ? rankingPolicy.weights.blockedPenalty : 0;
+    const rawRank = fitScore + trustScore + freshnessBonus - securityPenalty - blockedPenalty;
+    const rankScore = Math.max(0, Math.min(100, rawRank));
+    const fitReasons = [
+        `Project archetype: ${projectSignals.inferredArchetype} (${projectSignals.inferenceConfidence}% confidence)`,
+        `Compatibility overlap: ${compatibilityScore.toFixed(1)}`,
+        `Capability coverage: ${capabilityScore.toFixed(1)}`,
+        `Inferred capability matches: ${inferredCapabilityMatches}`,
+        `Repo evidence signals: ${projectSignals.scanEvidence.length}`,
+        `Maintenance signal: ${candidate.maintenanceSignal}`,
+        `Provenance signal: ${candidate.provenanceSignal}`,
+        `Adoption signal: ${candidate.adoptionSignal}`,
+        sourcePenalty > 0 ? `Source confidence penalty: ${round(sourcePenalty)}` : 'Source confidence penalty: 0'
+    ];
+    const blockReason = blockedByQuarantine
+        ? 'Quarantined by whitelist verification'
+        : blockedByPolicy
+            ? `Blocked by security policy tier: ${assessment.riskTier}`
+            : undefined;
+    return RecommendationSchema.parse({
+        id: candidate.id,
+        kind: candidate.kind,
+        provider: candidate.provider,
+        rankScore,
+        fitReasons,
+        scoreBreakdown: {
+            fitScore: round(fitScore),
+            trustScore: round(trustScore),
+            securityPenalty: round(securityPenalty),
+            freshnessBonus: round(freshnessBonus),
+            blockedPenalty: round(blockedPenalty)
+        },
+        riskTier: assessment.riskTier,
+        riskScore: assessment.riskScore,
+        blocked,
+        blockReason,
+        installMethod: candidate.install.kind
+    });
+}
+function sortRecommendations(a, b) {
+    const primary = b.rankScore - a.rankScore;
+    if (primary !== 0) {
+        return primary;
+    }
+    const trustA = a.scoreBreakdown.trustScore;
+    const trustB = b.scoreBreakdown.trustScore;
+    const trustDiff = trustB - trustA;
+    if (trustDiff !== 0) {
+        return trustDiff;
+    }
+    const riskDiff = a.riskScore - b.riskScore;
+    if (riskDiff !== 0) {
+        return riskDiff;
+    }
+    return a.id.localeCompare(b.id);
+}
+function overlapScore(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        return 0;
+    }
+    const rightSet = new Set(right.map((value) => value.toLowerCase()));
+    const matches = left.filter((value) => rightSet.has(value.toLowerCase())).length;
+    return (matches / Math.max(left.length, right.length)) * 100;
+}
+function countMatches(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        return 0;
+    }
+    const rightSet = new Set(right.map((value) => value.toLowerCase()));
+    return left.filter((value) => rightSet.has(value.toLowerCase())).length;
+}
+function dedupe(values) {
+    return Array.from(new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)));
+}
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+function computeSourcePenalty(candidate) {
+    const metadata = candidate.metadata && typeof candidate.metadata === 'object' && !Array.isArray(candidate.metadata)
+        ? candidate.metadata
+        : {};
+    let penalty = 0;
+    const sourceType = typeof metadata.sourceType === 'string' ? metadata.sourceType : '';
+    if (sourceType === 'community-list') {
+        penalty += 6;
+    }
+    const catalogType = typeof metadata.catalogType === 'string' ? metadata.catalogType : '';
+    const confidence = typeof metadata.sourceConfidence === 'string' ? metadata.sourceConfidence : '';
+    if (catalogType === 'connector' && confidence === 'scraped') {
+        penalty += 8;
+    }
+    return penalty;
+}