@crawlith/core 0.1.1 → 0.1.2

package/dist/graph/hits.js

@@ -0,0 +1,111 @@
+/**
+ * Service to compute Hub and Authority scores using the HITS algorithm.
+ * Operates purely on the internal link graph.
+ */
+export class HITSService {
+    /**
+     * Computes Hub and Authority scores using the HITS algorithm.
+     * @param {Graph} graph - The link graph to analyze.
+     * @param {HITSOptions} options - Algorithm options (e.g. number of iterations).
+     * @returns {Map<string, HITSRow>} A map of page URLs to their HITS results.
+     */
+    evaluate(graph, options = {}) {
+        const iterations = options.iterations || 20;
+        const nodes = graph.getNodes();
+        // 1. Filter eligible nodes
+        const eligibleNodes = nodes.filter(n => (n.status === 200 || n.status === 0) &&
+            (!n.redirectChain || n.redirectChain.length === 0) &&
+            !n.noindex);
+        const N = eligibleNodes.length;
+        const results = new Map();
+        if (N === 0)
+            return results;
+        // Map URL to Index for O(1) access
+        const urlToIndex = new Map();
+        for (let i = 0; i < N; i++) {
+            urlToIndex.set(eligibleNodes[i].url, i);
+        }
+        // Build Adjacency Lists
+        const incoming = new Array(N).fill(null).map(() => []);
+        const outgoing = new Array(N).fill(null).map(() => []);
+        const allEdges = graph.getEdges();
+        for (const edge of allEdges) {
+            if (edge.source === edge.target)
+                continue;
+            const sourceIndex = urlToIndex.get(edge.source);
+            const targetIndex = urlToIndex.get(edge.target);
+            if (sourceIndex !== undefined && targetIndex !== undefined) {
+                const weight = edge.weight || 1.0;
+                incoming[targetIndex].push({ sourceIndex, weight });
+                outgoing[sourceIndex].push({ targetIndex, weight });
+            }
+        }
+        // Initialize Scores
+        const authScores = new Float64Array(N).fill(1.0);
+        const hubScores = new Float64Array(N).fill(1.0);
+        // 2. Iteration
+        for (let iter = 0; iter < iterations; iter++) {
+            let normAuth = 0;
+            for (let i = 0; i < N; i++) {
+                const inLinks = incoming[i];
+                let newAuth = 0;
+                for (let j = 0; j < inLinks.length; j++) {
+                    const link = inLinks[j];
+                    newAuth += hubScores[link.sourceIndex] * link.weight;
+                }
+                authScores[i] = newAuth;
+                normAuth += newAuth * newAuth;
+            }
+            normAuth = Math.sqrt(normAuth);
+            if (normAuth > 0) {
+                for (let i = 0; i < N; i++)
+                    authScores[i] /= normAuth;
+            }
+            let normHub = 0;
+            for (let i = 0; i < N; i++) {
+                const outLinks = outgoing[i];
+                let newHub = 0;
+                for (let j = 0; j < outLinks.length; j++) {
+                    const link = outLinks[j];
+                    newHub += authScores[link.targetIndex] * link.weight;
+                }
+                hubScores[i] = newHub;
+                normHub += newHub * newHub;
+            }
+            normHub = Math.sqrt(normHub);
+            if (normHub > 0) {
+                for (let i = 0; i < N; i++)
+                    hubScores[i] /= normHub;
+            }
+        }
+        // 3. Classification and Result Mapping
+        const sortedAuth = [...authScores].sort((a, b) => a - b);
+        const sortedHub = [...hubScores].sort((a, b) => a - b);
+        const medianAuth = sortedAuth[Math.floor(sortedAuth.length / 2)];
+        const medianHub = sortedHub[Math.floor(sortedHub.length / 2)];
+        const maxAuth = sortedAuth[sortedAuth.length - 1];
+        const maxHub = sortedHub[sortedHub.length - 1];
+        for (let i = 0; i < N; i++) {
+            const auth = authScores[i];
+            const hub = hubScores[i];
+            const url = eligibleNodes[i].url;
+            const isHighAuth = (auth > medianAuth || (auth === maxAuth && auth > 0)) && auth > 0.00001;
+            const isHighHub = (hub > medianHub || (hub === maxHub && hub > 0)) && hub > 0.00001;
+            let link_role = 'peripheral';
+            if (isHighAuth && isHighHub)
+                link_role = 'power';
+            else if (isHighAuth)
+                link_role = 'authority';
+            else if (isHighHub)
+                link_role = 'hub';
+            else if (auth > 0.00001 && hub > 0.00001)
+                link_role = 'balanced';
+            results.set(url, {
+                authority_score: auth,
+                hub_score: hub,
+                link_role
+            });
+        }
+        return results;
+    }
+}

package/dist/graph/metrics.d.ts

@@ -14,10 +14,6 @@ export interface Metrics {
     crawlEfficiencyScore: number;
     averageDepth: number;
     structuralEntropy: number;
-    topPageRankPages: {
-        url: string;
-        score: number;
-    }[];
     limitReached: boolean;
     sessionStats?: {
         pagesFetched: number;

package/dist/graph/metrics.js

@@ -5,14 +5,24 @@ export function calculateMetrics(graph, _maxDepth) {
     const totalEdges = edges.length;
     // Identify broken nodes
     const brokenNodes = new Set(nodes.filter(n => n.status >= 400 || n.status === 0).map(n => n.url));
+    // Pre-compute outgoing edges per node for faster lookup
+    const outgoingEdges = new Map();
+    for (const edge of edges) {
+        let targets = outgoingEdges.get(edge.source);
+        if (!targets) {
+            targets = [];
+            outgoingEdges.set(edge.source, targets);
+        }
+        targets.push(edge.target);
+    }
     // Populate brokenLinks per node
     for (const node of nodes) {
-        const nodeEdges = edges.filter(e => e.source === node.url);
-        const broken = nodeEdges
-            .map(e => e.target)
-            .filter(targetUrl => brokenNodes.has(targetUrl));
-        if (broken.length > 0) {
-            node.brokenLinks = broken;
+        const targets = outgoingEdges.get(node.url);
+        if (targets) {
+            const broken = targets.filter(targetUrl => brokenNodes.has(targetUrl));
+            if (broken.length > 0) {
+                node.brokenLinks = broken;
+            }
         }
     }
     // Authority Score (per node)
@@ -55,16 +65,11 @@ export function calculateMetrics(graph, _maxDepth) {
         }
     }
     // topAuthorityPages: Top 10 by authority
-    const topAuthorityPages = [...nodes]
-        .map(n => ({ url: n.url, authority: n.authorityScore ?? getAuthority(n) }))
+    const topAuthorityPages = nodes
+        .filter(n => n.isInternal !== false && n.status > 0)
+        .map(n => ({ url: n.url, authority: getAuthority(n) }))
         .sort((a, b) => b.authority - a.authority)
         .slice(0, 10);
-    // topPageRankPages: Top 10 by raw PageRank
-    const topPageRankPages = [...nodes]
-        .filter(n => n.pageRank !== undefined)
-        .map(n => ({ url: n.url, score: n.pageRank }))
-        .sort((a, b) => b.score - a.score)
-        .slice(0, 10);
     const averageOutDegree = totalPages > 0 ? totalEdges / totalPages : 0;
     const maxDepthFound = nodes.reduce((max, n) => Math.max(max, n.depth), 0);
     return {
@@ -79,7 +84,6 @@ export function calculateMetrics(graph, _maxDepth) {
         crawlEfficiencyScore,
         averageDepth,
         structuralEntropy,
-        topPageRankPages,
         limitReached: graph.limitReached,
         sessionStats: graph.sessionStats
     };

package/dist/graph/pagerank.d.ts

@@ -1,12 +1,25 @@
 import { Graph } from './graph.js';
-interface PageRankOptions {
+export interface PageRankRow {
+    raw_rank: number;
+    score: number;
+}
+export interface PageRankOptions {
     dampingFactor?: number;
     maxIterations?: number;
     convergenceThreshold?: number;
     soft404WeightThreshold?: number;
+    neutralScoreWhenFlat?: number;
 }
 /**
- * Production-Grade Weighted PageRank Engine
+ * Service to analyze a site's link graph and compute PageRank metrics.
+ * Runs only on the full crawl graph.
  */
-export declare function computePageRank(graph: Graph, options?: PageRankOptions): void;
-export {};
+export declare class PageRankService {
+    /**
+     * Computes a Production-Grade Weighted PageRank over the given graph.
+     * @param {Graph} graph - The full site graph structure.
+     * @param {PageRankOptions} options - Configuration overrides for damping factor, limits, etc.
+     * @returns {Map<string, PageRankRow>} The individual metrics keyed by exact normalized url.
+     */
+    evaluate(graph: Graph, options?: PageRankOptions): Map<string, PageRankRow>;
+}

package/dist/graph/pagerank.js

@@ -1,104 +1,137 @@
+import { DEFAULTS } from '../constants.js';
 /**
- * Production-Grade Weighted PageRank Engine
+ * Service to analyze a site's link graph and compute PageRank metrics.
+ * Runs only on the full crawl graph.
  */
-export function computePageRank(graph, options = {}) {
-    const d = options.dampingFactor ?? 0.85;
-    const maxIterations = options.maxIterations ?? 40;
-    const epsilon = options.convergenceThreshold ?? 1e-5;
-    const soft404Threshold = options.soft404WeightThreshold ?? 0.8;
-    const allNodes = graph.getNodes();
-    const allEdges = graph.getEdges();
-    // 1. Filter Eligible Nodes
-    const eligibleNodes = allNodes.filter(node => {
-        if (node.noindex)
-            return false;
-        if (node.isCollapsed)
-            return false;
-        if (node.soft404Score && node.soft404Score > soft404Threshold)
-            return false;
-        if (node.canonical && node.canonical !== node.url)
-            return false;
-        if (node.status >= 400)
-            return false; // Don't pass rank to broken pages
-        if (node.status === 0)
-            return false; // Don't pass rank to uncrawled/external pages
-        return true;
-    });
-    const nodeCount = eligibleNodes.length;
-    if (nodeCount === 0)
-        return;
-    const nodeUrls = eligibleNodes.map(n => n.url);
-    const nodeMap = new Map();
-    eligibleNodes.forEach(n => nodeMap.set(n.url, n));
-    // Initialize PageRank
-    let pr = new Map();
-    nodeUrls.forEach(url => pr.set(url, 1 / nodeCount));
-    // Pre-calculate weighted outbound sums and inverted adjacency
-    const outWeights = new Map();
-    const incoming = new Map();
-    const sinks = [];
-    // Initialize outWeights for all eligible nodes
-    nodeUrls.forEach(url => outWeights.set(url, 0));
-    for (const edge of allEdges) {
-        if (nodeMap.has(edge.source) && nodeMap.has(edge.target)) {
-            const weight = edge.weight || 1.0;
-            const sources = incoming.get(edge.target) ?? [];
-            sources.push({ source: edge.source, weight });
-            incoming.set(edge.target, sources);
-            outWeights.set(edge.source, (outWeights.get(edge.source) || 0) + weight);
-        }
-    }
-    // Identify sinks
-    nodeUrls.forEach(url => {
-        if ((outWeights.get(url) || 0) === 0) {
-            sinks.push(url);
+export class PageRankService {
+    /**
+     * Computes a Production-Grade Weighted PageRank over the given graph.
+     * @param {Graph} graph - The full site graph structure.
+     * @param {PageRankOptions} options - Configuration overrides for damping factor, limits, etc.
+     * @returns {Map<string, PageRankRow>} The individual metrics keyed by exact normalized url.
+     */
+    evaluate(graph, options = {}) {
+        const d = options.dampingFactor ?? 0.85;
+        const maxIterations = options.maxIterations ?? 40;
+        const epsilon = options.convergenceThreshold ?? 1e-5;
+        const soft404Threshold = options.soft404WeightThreshold ?? 0.8;
+        const neutralScoreWhenFlat = options.neutralScoreWhenFlat ?? 50;
+        const allNodes = graph.getNodes();
+        const allEdges = graph.getEdges();
+        // 1. Filter Eligible Nodes
+        const eligibleNodes = allNodes.filter(node => {
+            if (node.noindex)
+                return false;
+            if (node.isCollapsed)
+                return false;
+            // Keep compat with other plugins mutating soft404Score onto nodes
+            if (node.soft404Score && node.soft404Score > soft404Threshold)
+                return false;
+            // canonical is stored as absolute URL; extract pathname for path-based comparison
+            if (node.canonical) {
+                try {
+                    const canonicalPath = new URL(node.canonical).pathname;
+                    if (canonicalPath !== node.url)
+                        return false;
+                }
+                catch {
+                    // if canonical isn't a valid URL, compare as-is
+                    if (node.canonical !== node.url)
+                        return false;
+                }
+            }
+            if (node.status >= 400)
+                return false; // Don't pass rank to broken pages
+            if (node.status === 0)
+                return false; // Don't pass rank to uncrawled/external pages
+            return true;
+        });
+        const nodeCount = eligibleNodes.length;
+        const results = new Map();
+        if (nodeCount === 0)
+            return results;
+        // Map URL to Index for O(1) access and TypedArray usage
+        const urlToIndex = new Map();
+        for (let i = 0; i < nodeCount; i++) {
+            urlToIndex.set(eligibleNodes[i].url, i);
         }
-    });
-    // Iterative Calculation
-    for (let i = 0; i < maxIterations; i++) {
-        const nextPr = new Map();
-        // Calculate total rank from sinks to redistribute
-        let sinkRankTotal = 0;
-        for (const url of sinks) {
-            sinkRankTotal += pr.get(url) || 0;
+        // Pre-calculate weighted outbound sums and inverted adjacency
+        const outWeights = new Float64Array(nodeCount);
+        const incoming = new Array(nodeCount).fill(null).map(() => []);
+        for (const edge of allEdges) {
+            const sourceIndex = urlToIndex.get(edge.source);
+            const targetIndex = urlToIndex.get(edge.target);
+            if (sourceIndex !== undefined && targetIndex !== undefined) {
+                const weight = edge.weight || 1.0;
+                incoming[targetIndex].push({ sourceIndex, weight });
+                outWeights[sourceIndex] += weight;
+            }
         }
-        const baseRank = (1 - d) / nodeCount + (d * sinkRankTotal / nodeCount);
-        for (const url of nodeUrls) {
-            let rankFromLinks = 0;
-            const sources = incoming.get(url) || [];
-            for (const edge of sources) {
-                const sourceRank = pr.get(edge.source) || 0;
-                const sourceOutWeight = outWeights.get(edge.source) || 1.0;
-                rankFromLinks += sourceRank * (edge.weight / sourceOutWeight);
+        // Identify sinks
+        const sinks = [];
+        for (let i = 0; i < nodeCount; i++) {
+            if (outWeights[i] === 0) {
+                sinks.push(i);
             }
-            const newRank = baseRank + d * rankFromLinks;
-            nextPr.set(url, newRank);
         }
-        // Convergence check
-        let maxDelta = 0;
-        for (const url of nodeUrls) {
-            const delta = Math.abs(nextPr.get(url) - pr.get(url));
-            if (delta > maxDelta)
-                maxDelta = delta;
+        // Initialize PageRank typed arrays
+        let pr = new Float64Array(nodeCount).fill(1 / nodeCount);
+        let nextPr = new Float64Array(nodeCount);
+        // Iterative Calculation
+        for (let iter = 0; iter < maxIterations; iter++) {
+            // Calculate total rank from sinks to redistribute
+            let sinkRankTotal = 0;
+            for (let i = 0; i < sinks.length; i++) {
+                sinkRankTotal += pr[sinks[i]];
+            }
+            const baseRank = (1 - d) / nodeCount + (d * sinkRankTotal / nodeCount);
+            let maxDelta = 0;
+            for (let i = 0; i < nodeCount; i++) {
+                let rankFromLinks = 0;
+                const sources = incoming[i];
+                for (let j = 0; j < sources.length; j++) {
+                    const edge = sources[j];
+                    const sourceRank = pr[edge.sourceIndex];
+                    const sourceOutWeight = outWeights[edge.sourceIndex] || 1.0;
+                    rankFromLinks += sourceRank * (edge.weight / sourceOutWeight);
+                }
+                const newRank = baseRank + d * rankFromLinks;
+                nextPr[i] = newRank;
+                const delta = Math.abs(newRank - pr[i]);
+                if (delta > maxDelta) {
+                    maxDelta = delta;
+                }
+            }
+            // Swap arrays
+            const temp = pr;
+            pr = nextPr;
+            nextPr = temp;
+            if (maxDelta < epsilon)
+                break;
         }
-        pr = nextPr;
-        if (maxDelta < epsilon)
-            break;
-    }
-    // 2. Normalization (0-100)
-    const ranks = Array.from(pr.values());
-    const minPR = Math.min(...ranks);
-    const maxPR = Math.max(...ranks);
-    const range = maxPR - minPR;
-    for (const node of eligibleNodes) {
-        const rawRank = pr.get(node.url);
-        node.pageRank = rawRank;
-        if (range > 1e-12) {
-            node.pageRankScore = 100 * (rawRank - minPR) / range;
+        // 2. Normalization (0-100)
+        let minPR = pr[0];
+        let maxPR = pr[0];
+        for (let i = 1; i < nodeCount; i++) {
+            const rank = pr[i];
+            if (rank < minPR)
+                minPR = rank;
+            if (rank > maxPR)
+                maxPR = rank;
         }
-        else {
-            // If there's no range, all eligible pages are equally important.
-            node.pageRankScore = 100;
+        const range = maxPR - minPR;
+        for (let i = 0; i < nodeCount; i++) {
+            const rawRank = pr[i];
+            const url = eligibleNodes[i].url;
+            let score = neutralScoreWhenFlat;
+            if (range > DEFAULTS.GRAPH_PRECISION) {
+                score = 100 * (rawRank - minPR) / range;
+            }
+            results.set(url, {
+                raw_rank: rawRank,
+                score: Number(score.toFixed(3))
+            });
         }
+        return results;
     }
 }

package/dist/index.d.ts

@@ -1,26 +1,35 @@
+export * from './scoring/health.js';
 export * from './crawler/crawl.js';
 export * from './crawler/normalize.js';
 export * from './crawler/metricsRunner.js';
+export * from './crawler/trap.js';
 export * from './graph/metrics.js';
-export * from './report/html.js';
-export * from './report/crawl_template.js';
-export * from './report/crawlExport.js';
 export * from './graph/graph.js';
-export * from './diff/compare.js';
-export * from './scoring/orphanSeverity.js';
+export * from './graph/simhash.js';
 export * from './graph/pagerank.js';
-export * from './graph/duplicate.js';
-export * from './graph/cluster.js';
-export * from './scoring/health.js';
-export * from './scoring/hits.js';
+export * from './graph/hits.js';
+export * from './diff/compare.js';
+export * from './diff/service.js';
 export * from './analysis/analyze.js';
 export * from './analysis/content.js';
 export * from './analysis/seo.js';
 export * from './analysis/images.js';
 export * from './analysis/links.js';
+export * from './analysis/scoring.js';
+export * from './analysis/clustering.js';
+export * from './analysis/duplicate.js';
+export * from './analysis/soft404.js';
+export * from './analysis/heading.js';
+export * from './analysis/orphan.js';
 export * from './audit/index.js';
 export * from './audit/types.js';
+export * from './report/html.js';
+export * from './report/crawl_template.js';
+export * from './report/crawlExport.js';
+export * from './report/export.js';
+export * from './report/insight.js';
 export * from './db/index.js';
+export * from './db/reset.js';
 export * from './db/graphLoader.js';
 export * from './db/repositories/SiteRepository.js';
 export * from './db/repositories/SnapshotRepository.js';
@@ -30,4 +39,13 @@ export * from './db/repositories/MetricsRepository.js';
 export * from './lock/lockManager.js';
 export * from './lock/hashKey.js';
 export * from './utils/version.js';
+export * from './utils/secureConfig.js';
 export * from './events.js';
+export * from './plugin-system/plugin-types.js';
+export * from './plugin-system/plugin-loader.js';
+export * from './plugin-system/plugin-registry.js';
+export * from './plugin-system/plugin-cli.js';
+export * from './ports/index.js';
+export * from './application/usecase.js';
+export * from './application/usecases.js';
+export { Command } from 'commander';

package/dist/index.js

@@ -1,26 +1,35 @@
+export * from './scoring/health.js';
 export * from './crawler/crawl.js';
 export * from './crawler/normalize.js';
 export * from './crawler/metricsRunner.js';
+export * from './crawler/trap.js';
 export * from './graph/metrics.js';
-export * from './report/html.js';
-export * from './report/crawl_template.js';
-export * from './report/crawlExport.js';
 export * from './graph/graph.js';
-export * from './diff/compare.js';
-export * from './scoring/orphanSeverity.js';
+export * from './graph/simhash.js';
 export * from './graph/pagerank.js';
-export * from './graph/duplicate.js';
-export * from './graph/cluster.js';
-export * from './scoring/health.js';
-export * from './scoring/hits.js';
+export * from './graph/hits.js';
+export * from './diff/compare.js';
+export * from './diff/service.js';
 export * from './analysis/analyze.js';
 export * from './analysis/content.js';
 export * from './analysis/seo.js';
 export * from './analysis/images.js';
 export * from './analysis/links.js';
+export * from './analysis/scoring.js';
+export * from './analysis/clustering.js';
+export * from './analysis/duplicate.js';
+export * from './analysis/soft404.js';
+export * from './analysis/heading.js';
+export * from './analysis/orphan.js';
 export * from './audit/index.js';
 export * from './audit/types.js';
+export * from './report/html.js';
+export * from './report/crawl_template.js';
+export * from './report/crawlExport.js';
+export * from './report/export.js';
+export * from './report/insight.js';
 export * from './db/index.js';
+export * from './db/reset.js';
 export * from './db/graphLoader.js';
 export * from './db/repositories/SiteRepository.js';
 export * from './db/repositories/SnapshotRepository.js';
@@ -30,4 +39,13 @@ export * from './db/repositories/MetricsRepository.js';
 export * from './lock/lockManager.js';
 export * from './lock/hashKey.js';
 export * from './utils/version.js';
+export * from './utils/secureConfig.js';
 export * from './events.js';
+export * from './plugin-system/plugin-types.js';
+export * from './plugin-system/plugin-loader.js';
+export * from './plugin-system/plugin-registry.js';
+export * from './plugin-system/plugin-cli.js';
+export * from './ports/index.js';
+export * from './application/usecase.js';
+export * from './application/usecases.js';
+export { Command } from 'commander';

package/dist/lock/lockManager.d.ts

@@ -5,6 +5,7 @@ export declare class LockManager {
     private static get lockDir();
     static acquireLock(commandName: string, targetUrl: string, options: any, context?: EngineContext, force?: boolean): Promise<void>;
     static releaseLock(): void;
+    static clearAllLocks(): Promise<number>;
     private static log;
     private static registerHandlers;
 }

package/dist/lock/lockManager.js

@@ -85,6 +85,21 @@ export class LockManager {
             }
         }
     }
+    static async clearAllLocks() {
+        if (!existsSync(this.lockDir))
+            return 0;
+        const files = await fs.readdir(this.lockDir);
+        const lockFiles = files.filter(f => f.endsWith('.lock'));
+        let count = 0;
+        for (const file of lockFiles) {
+            try {
+                await fs.unlink(path.join(this.lockDir, file));
+                count++;
+            }
+            catch { /* ignore */ }
+        }
+        return count;
+    }
     static log(type, message, error) {
         if (this.context) {
             this.context.emit({ type, message, error });

package/dist/plugin-system/plugin-cli.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+/**
+ * Standard utility for plugins to register their configuration commands.
+ * This ensures a consistent 'config <plugin> set' CLI pattern across the ecosystem.
+ *
+ * @param cli - The main Commander instance (must have name 'crawlith').
+ * @param pluginName - The unique name of the plugin (e.g., 'pagespeed').
+ * @param credentialLabel - Human-readable label for the credential (e.g., 'Google API Key').
+ */
+export declare function registerPluginConfigCommand(cli: Command, pluginName: string, credentialLabel: string): void;

package/dist/plugin-system/plugin-cli.js

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+import { setEncryptedConfigKey } from '../utils/secureConfig.js';
+/**
+ * Standard utility for plugins to register their configuration commands.
+ * This ensures a consistent 'config <plugin> set' CLI pattern across the ecosystem.
+ *
+ * @param cli - The main Commander instance (must have name 'crawlith').
+ * @param pluginName - The unique name of the plugin (e.g., 'pagespeed').
+ * @param credentialLabel - Human-readable label for the credential (e.g., 'Google API Key').
+ */
+export function registerPluginConfigCommand(cli, pluginName, credentialLabel) {
+    // Only register subcommands if we are in the root 'crawlith' CLI context
+    if (cli.name() !== 'crawlith')
+        return;
+    // Find or create 'config' command
+    let configCmd = cli.commands.find(c => c.name() === 'config');
+    if (!configCmd) {
+        configCmd = new Command('config').description('Manage Crawlith plugin configuration');
+        cli.addCommand(configCmd);
+    }
+    // Define plugin-specific subcommand
+    const pluginConfigCmd = new Command(pluginName).description(`Manage ${pluginName} configuration`);
+    pluginConfigCmd
+        .command('set <value>')
+        .description(`Set and encrypt ${credentialLabel}`)
+        .action((value) => {
+        setEncryptedConfigKey(pluginName, value);
+        console.log(`✅ ${credentialLabel} for ${pluginName} saved and encrypted.`);
+    });
+    configCmd.addCommand(pluginConfigCmd);
+}