@asifkibria/claude-code-toolkit 1.2.0 → 1.3.0

package/dist/cli.js

@@ -8,11 +8,14 @@ import * as path from "path";
 import * as os from "os";
 import { findAllJsonlFiles, findBackupFiles, scanFile, fixFile, getConversationStats, restoreFromBackup, deleteOldBackups, exportConversationToFile, estimateContextSize, formatContextEstimate, generateUsageAnalytics, formatUsageAnalytics, findDuplicates, formatDuplicateReport, findArchiveCandidates, archiveConversations, formatArchiveReport, runMaintenance, formatMaintenanceReport, generateCronSchedule, generateLaunchdPlist, } from "./lib/scanner.js";
 import { analyzeClaudeStorage, cleanClaudeDirectory, findCleanupTargets, formatStorageReport, formatCleanupReport, } from "./lib/storage.js";
-import { diagnoseMcpServers, formatMcpDiagnosticReport, } from "./lib/mcp-validator.js";
+import { diagnoseMcpServers, formatMcpDiagnosticReport, analyzeMcpPerformance, formatMcpPerformanceReport, } from "./lib/mcp-validator.js";
 import { listSessions, diagnoseSession, repairSession, extractSessionContent, formatSessionReport, formatSessionDiagnosticReport, } from "./lib/session-recovery.js";
-import { scanForSecrets, auditSession, enforceRetention, formatSecretsScanReport, formatAuditReport, formatRetentionReport, } from "./lib/security.js";
+import { scanForSecrets, scanForPII, auditSession, enforceRetention, formatSecretsScanReport, formatPIIScanReport, formatAuditReport, formatRetentionReport, } from "./lib/security.js";
 import { inventoryTraces, cleanTraces, wipeAllTraces, generateTraceGuardHooks, formatTraceInventory, formatTraceCleanReport, formatTraceGuardConfig, } from "./lib/trace.js";
 import { startDashboard, stopDashboard, isDashboardRunning } from "./lib/dashboard.js";
+import { searchConversations, formatSearchReport, compareSessionsByCID, formatSessionDiff } from "./lib/search.js";
+import { linkSessionsToGit, formatGitLinkReport } from "./lib/git.js";
+import { checkAlerts, checkQuotas, formatAlertsReport, formatQuotasReport } from "./lib/alerts.js";
 function formatContentType(type) {
     switch (type) {
         case "image": return "🖼️  image";
@@ -36,7 +39,7 @@ function formatDate(date) {
 }
 function printHelp() {
     console.log(`
-Claude Code Toolkit v1.2.0
+Claude Code Toolkit v1.3.0
 Maintain, optimize, secure, and troubleshoot your Claude Code installation.
 
 USAGE:
@@ -45,25 +48,35 @@ USAGE:
 
 COMMANDS:
   health              Quick health check (start here!)
+  search <query>      Full-text search across all conversations
   stats               Show conversation statistics
   context             Estimate context/token usage
+  cost                Estimate API costs based on token usage
   analytics           Usage analytics dashboard
   duplicates          Find duplicate content and conversations
   archive             Archive old/inactive conversations
   maintenance         Run maintenance checks and actions
   scan                Scan for issues (dry run)
   fix                 Fix all detected issues
+  watch               Monitor sessions for new oversized content
   export              Export conversation to markdown or JSON
   backups             List backup files
   restore <path>      Restore from a backup file
   cleanup             Delete old backup files
   clean               Analyze and clean .claude directory
   mcp-validate        Validate MCP server configurations
+  mcp-perf            Track MCP server performance and usage
   sessions            List all sessions with health status
+  diff <id1> <id2>    Compare two sessions
+  git                 Link sessions to git branches/commits
   recover <id>        Diagnose/repair/extract from a session
   security-scan       Scan conversations for leaked secrets
+  pii-scan            Scan conversations for personal data (PII)
+                      --details: Show unmasked values (handle with care!)
   audit <id>          Audit a session's actions (files, commands, etc.)
   retention           Enforce data retention policy
+  alerts              Check for issues and notifications
+  quotas              Show usage quotas and limits
   dashboard           Open web dashboard in browser
   dashboard --daemon   Run dashboard as background process
   dashboard --stop     Stop background dashboard
@@ -75,12 +88,14 @@ COMMANDS:
 OPTIONS:
   -f, --file <path>     Target a specific file
   -o, --output <path>   Output file path (for export)
+  -q, --query <text>    Search query text
+  --role <type>         For search: filter by role (user|assistant|all)
   --format <type>       Export format: markdown or json (default: markdown)
   --with-tools          Include tool results in export
   -d, --dry-run         Show what would be done without making changes
   --no-backup           Skip creating backups when fixing (not recommended)
   --days <n>            For cleanup/archive/retention: days threshold (default: 7/30)
-  --limit <n>           For stats: limit results (default: 10)
+  --limit <n>           For stats/search: limit results (default: 10/50)
   --sort <field>        For stats: sort by size|messages|images|modified
   --auto                For maintenance: run automatically without prompts
   --schedule            For maintenance: show cron/launchd setup
@@ -96,12 +111,19 @@ OPTIONS:
   --port <n>            For dashboard: port number (default: 1405)
   --daemon              For dashboard: run as background process
   --stop                For dashboard: stop background process
+  --token <value>       Require dashboard auth with bearer token
   --project <path>      Filter by project path
+  --json                Output structured JSON (scan/watch)
+  --interval <sec>      For watch: polling interval in seconds (default: 15)
+  --auto-fix            For watch: automatically fix detected issues
   -h, --help            Show this help message
   -v, --version         Show version
 
 EXAMPLES:
   cct health                        # Quick health check
+  cct search "authentication"       # Search all conversations
+  cct search "api" --role user      # Search only user messages
+  cct cost                          # Estimate API costs
   cct clean --dry-run               # Preview .claude directory cleanup
   cct mcp-validate --test           # Validate and test MCP servers
   cct sessions                      # List all sessions
@@ -123,6 +145,8 @@ function parseArgs(args) {
         subcommand: undefined,
         file: undefined,
         output: undefined,
+        query: undefined,
+        role: undefined,
         format: "markdown",
         withTools: false,
         dryRun: false,
@@ -145,6 +169,11 @@ function parseArgs(args) {
         port: 1405,
         daemon: false,
         stop: false,
+        token: undefined,
+        json: false,
+        interval: 15,
+        autoFix: false,
+        details: false,
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -153,7 +182,7 @@ function parseArgs(args) {
             process.exit(0);
         }
         if (arg === "-v" || arg === "--version") {
-            console.log("1.2.0");
+            console.log("1.3.0");
             process.exit(0);
         }
         if (arg === "-f" || arg === "--file") {
@@ -164,6 +193,14 @@ function parseArgs(args) {
             result.output = args[++i];
             continue;
         }
+        if (arg === "-q" || arg === "--query") {
+            result.query = args[++i];
+            continue;
+        }
+        if (arg === "--role") {
+            result.role = args[++i];
+            continue;
+        }
         if (arg === "--format") {
             const fmt = args[++i];
             if (fmt === "json" || fmt === "markdown") {
@@ -255,6 +292,26 @@ function parseArgs(args) {
             result.project = args[++i];
             continue;
         }
+        if (arg === "--token") {
+            result.token = args[++i];
+            continue;
+        }
+        if (arg === "--json") {
+            result.json = true;
+            continue;
+        }
+        if (arg === "--interval") {
+            result.interval = parseInt(args[++i], 10);
+            continue;
+        }
+        if (arg === "--auto-fix") {
+            result.autoFix = true;
+            continue;
+        }
+        if (arg === "--details") {
+            result.details = true;
+            continue;
+        }
         if (!arg.startsWith("-") && !result.command) {
             result.command = arg;
             continue;
@@ -263,6 +320,19 @@ function parseArgs(args) {
             result.file = arg;
             continue;
         }
+        if (!arg.startsWith("-") && result.command === "search" && !result.query) {
+            result.query = arg;
+            continue;
+        }
+        if (!arg.startsWith("-") && result.command === "diff") {
+            if (!result.file) {
+                result.file = arg;
+            }
+            else if (!result.subcommand) {
+                result.subcommand = arg;
+            }
+            continue;
+        }
         if (!arg.startsWith("-") && result.command === "trace" && !result.subcommand) {
             result.subcommand = arg;
             continue;
@@ -270,13 +340,22 @@ function parseArgs(args) {
     }
     return result;
 }
-async function cmdScan(file) {
+async function cmdScan(file, asJson) {
     if (!fs.existsSync(PROJECTS_DIR)) {
         console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
         process.exit(1);
     }
     const files = file ? [file] : findAllJsonlFiles(PROJECTS_DIR);
-    console.log(`Scanning ${files.length} file(s)...\n`);
+    const summary = {
+        success: true,
+        filesScanned: files.length,
+        filesWithIssues: 0,
+        totalIssues: 0,
+        files: [],
+    };
+    if (!asJson) {
+        console.log(`Scanning ${files.length} file(s)...\n`);
+    }
     let totalIssues = 0;
     let filesWithIssues = 0;
     for (const f of files) {
@@ -286,10 +365,21 @@ async function cmdScan(file) {
                 filesWithIssues++;
                 totalIssues += result.issues.length;
                 const relPath = path.relative(PROJECTS_DIR, f);
-                console.log(`\x1b[33m${relPath}\x1b[0m`);
-                for (const issue of result.issues) {
-                    console.log(`  Line ${issue.line}: ${formatContentType(issue.contentType)} (~${formatBytes(issue.estimatedSize)})`);
+                if (!asJson) {
+                    console.log(`\x1b[33m${relPath}\x1b[0m`);
+                    for (const issue of result.issues) {
+                        console.log(`  Line ${issue.line}: ${formatContentType(issue.contentType)} (~${formatBytes(issue.estimatedSize)})`);
+                    }
                 }
+                summary.files.push({
+                    file: relPath,
+                    issues: result.issues.map((issue) => ({
+                        line: issue.line,
+                        type: issue.contentType,
+                        location: issue.location,
+                        size: formatBytes(issue.estimatedSize),
+                    })),
+                });
             }
         }
         catch {
@@ -297,6 +387,11 @@ async function cmdScan(file) {
         }
     }
     console.log();
+    summary.totalIssues = totalIssues;
+    summary.filesWithIssues = filesWithIssues;
+    if (asJson) {
+        return summary;
+    }
     if (totalIssues === 0) {
         console.log("\x1b[32m✓ No oversized content found.\x1b[0m");
     }
@@ -305,6 +400,100 @@ async function cmdScan(file) {
         console.log("Run 'cct fix' to fix them.");
     }
 }
+async function cmdWatch(asJson, intervalSeconds, autoFix) {
+    if (!fs.existsSync(PROJECTS_DIR)) {
+        console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
+        process.exit(1);
+    }
+    const effectiveSeconds = Number.isFinite(intervalSeconds) && intervalSeconds > 0 ? intervalSeconds : 15;
+    const intervalMs = Math.max(5, effectiveSeconds) * 1000;
+    const seen = new Map();
+    const logEvent = (event) => {
+        if (asJson) {
+            console.log(JSON.stringify(event));
+        }
+        else {
+            const actionText = event.action === "fixed" ? "Fixed" : event.action === "error" ? "Error" : "Detected";
+            console.log(`[${event.timestamp}] ${actionText}: ${event.file} (${event.issues} issue(s))${event.details ? ` - ${event.details}` : ""}`);
+        }
+    };
+    const checkFiles = async () => {
+        const files = findAllJsonlFiles(PROJECTS_DIR);
+        const active = new Set();
+        for (const file of files) {
+            active.add(file);
+            let stat;
+            try {
+                stat = fs.statSync(file);
+            }
+            catch {
+                continue;
+            }
+            const last = seen.get(file) || 0;
+            if (stat.mtimeMs <= last)
+                continue;
+            seen.set(file, stat.mtimeMs);
+            let result;
+            try {
+                result = scanFile(file);
+            }
+            catch {
+                continue;
+            }
+            if (result.issues.length === 0)
+                continue;
+            const relPath = path.relative(PROJECTS_DIR, file);
+            const eventBase = {
+                timestamp: new Date().toISOString(),
+                file: relPath,
+                issues: result.issues.length,
+                action: "detected",
+            };
+            if (autoFix) {
+                try {
+                    const fixResult = fixFile(file);
+                    if (fixResult.fixed) {
+                        logEvent({ ...eventBase, action: "fixed" });
+                    }
+                    else {
+                        logEvent({ ...eventBase, action: "error", details: "No changes applied" });
+                    }
+                }
+                catch (err) {
+                    logEvent({ ...eventBase, action: "error", details: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            else {
+                logEvent(eventBase);
+            }
+        }
+        for (const entry of Array.from(seen.keys())) {
+            if (!active.has(entry)) {
+                seen.delete(entry);
+            }
+        }
+    };
+    await checkFiles();
+    if (!asJson) {
+        console.log(`Watching ${PROJECTS_DIR} every ${intervalMs / 1000}s. Press Ctrl+C to stop.`);
+        if (autoFix) {
+            console.log("Auto-fix is enabled. Backups will be created before changes.\n");
+        }
+    }
+    setInterval(() => {
+        checkFiles().catch((err) => {
+            if (asJson) {
+                console.log(JSON.stringify({ timestamp: new Date().toISOString(), action: "error", details: err.message }));
+            }
+            else {
+                console.error("Watch error:", err);
+            }
+        });
+    }, intervalMs);
+    return new Promise(() => {
+        // Keep process alive until Ctrl+C
+    });
+}
 async function cmdFix(file, noBackup = false) {
     if (!fs.existsSync(PROJECTS_DIR)) {
         console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
@@ -574,7 +763,7 @@ async function cmdArchive(days, dryRun) {
         console.log("\x1b[33mRun without --dry-run to archive these conversations.\x1b[0m\n");
     }
 }
-async function cmdMaintenance(dryRun, auto, schedule) {
+async function cmdMaintenance(auto, schedule) {
     if (schedule) {
         console.log("Scheduled Maintenance Setup\n");
         console.log("=== For macOS (launchd) ===");
@@ -608,7 +797,7 @@ async function cmdClean(dryRun, days, category) {
     const result = cleanClaudeDirectory(undefined, { ...options, dryRun });
     console.log(formatCleanupReport(targets, result, dryRun));
 }
-async function cmdMcpValidate(file, test) {
+async function cmdMcpValidate(test) {
     const report = await diagnoseMcpServers({ test, projectDir: process.cwd() });
     console.log(formatMcpDiagnosticReport(report));
 }
@@ -672,6 +861,14 @@ async function cmdSecurityScan(file) {
     const result = scanForSecrets(undefined, { file });
     console.log(formatSecretsScanReport(result));
 }
+async function cmdPIIScan(file, details) {
+    console.log("Scanning for Personal Identifiable Information (PII)...\n");
+    if (details) {
+        console.log("\x1b[33m⚠ WARNING: Showing unmasked PII values. Handle with care!\x1b[0m\n");
+    }
+    const result = scanForPII(undefined, { file, includeFullValues: details });
+    console.log(formatPIIScanReport(result, details));
+}
 async function cmdAudit(sessionId) {
     if (!sessionId) {
         console.error("Usage: cct audit <session-id>");
@@ -732,6 +929,127 @@ async function cmdTrace(subcommand, options) {
     console.error(`Unknown trace subcommand: ${subcommand}`);
     console.error("Usage: cct trace [clean|wipe|guard]");
 }
+async function cmdSearch(query, options) {
+    if (!query || query.length < 2) {
+        console.error("Usage: cct search <query> [--role user|assistant|all] [--limit n] [--project name]");
+        console.error("Query must be at least 2 characters.");
+        process.exit(1);
+    }
+    if (!fs.existsSync(PROJECTS_DIR)) {
+        console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
+        process.exit(1);
+    }
+    console.log(`Searching for "${query}"...\n`);
+    const searchOpts = {
+        query,
+        limit: options?.limit || 50,
+        role: options?.role || "all",
+        project: options?.project,
+        daysBack: options?.days,
+    };
+    const report = searchConversations(searchOpts);
+    console.log(formatSearchReport(report));
+}
+async function cmdCost() {
+    if (!fs.existsSync(PROJECTS_DIR)) {
+        console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
+        process.exit(1);
+    }
+    console.log("Calculating API cost estimates...\n");
+    const files = findAllJsonlFiles(PROJECTS_DIR);
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let sessionCount = 0;
+    const projectCosts = new Map();
+    for (const file of files) {
+        try {
+            const estimate = estimateContextSize(file);
+            const projectName = path.basename(path.dirname(file));
+            const b = estimate.breakdown;
+            const inputTokens = b.userTokens + b.systemTokens + b.toolUseTokens;
+            const outputTokens = b.assistantTokens + b.toolResultTokens;
+            if (!projectCosts.has(projectName)) {
+                projectCosts.set(projectName, { input: 0, output: 0, sessions: 0 });
+            }
+            const project = projectCosts.get(projectName);
+            project.input += inputTokens;
+            project.output += outputTokens;
+            project.sessions++;
+            totalInputTokens += inputTokens;
+            totalOutputTokens += outputTokens;
+            sessionCount++;
+        }
+        catch {
+            // Skip
+        }
+    }
+    const inputCostPerMillion = 15;
+    const outputCostPerMillion = 75;
+    const totalInputCost = (totalInputTokens / 1_000_000) * inputCostPerMillion;
+    const totalOutputCost = (totalOutputTokens / 1_000_000) * outputCostPerMillion;
+    const totalCost = totalInputCost + totalOutputCost;
+    console.log("API Cost Estimate (Claude Sonnet pricing)\n");
+    console.log("═".repeat(50));
+    console.log(`Sessions analyzed: ${sessionCount}`);
+    console.log(`\nToken Usage:`);
+    console.log(`  Input tokens:  ${totalInputTokens.toLocaleString()}`);
+    console.log(`  Output tokens: ${totalOutputTokens.toLocaleString()}`);
+    console.log(`  Total tokens:  ${(totalInputTokens + totalOutputTokens).toLocaleString()}`);
+    console.log(`\nEstimated Cost:`);
+    console.log(`  Input:  $${totalInputCost.toFixed(2)} ($${inputCostPerMillion}/M tokens)`);
+    console.log(`  Output: $${totalOutputCost.toFixed(2)} ($${outputCostPerMillion}/M tokens)`);
+    console.log(`  \x1b[36mTotal:  $${totalCost.toFixed(2)}\x1b[0m\n`);
+    const sortedProjects = Array.from(projectCosts.entries())
+        .sort((a, b) => (b[1].input + b[1].output) - (a[1].input + a[1].output))
+        .slice(0, 10);
+    if (sortedProjects.length > 0) {
+        console.log("Top Projects by Token Usage:\n");
+        for (const [name, data] of sortedProjects) {
+            const projectTotal = data.input + data.output;
+            const projectCost = ((data.input / 1_000_000) * inputCostPerMillion) + ((data.output / 1_000_000) * outputCostPerMillion);
+            console.log(`  ${name}`);
+            console.log(`    ${projectTotal.toLocaleString()} tokens (~$${projectCost.toFixed(2)}) - ${data.sessions} session(s)`);
+        }
+    }
+    console.log("\n\x1b[33mNote: These are estimates based on stored conversation history.\x1b[0m");
+    console.log("\x1b[33mActual costs depend on your API plan and usage patterns.\x1b[0m\n");
+}
+async function cmdDiff(sessionId1, sessionId2) {
+    if (!sessionId1 || !sessionId2) {
+        console.error("Usage: cct diff <session-id-1> <session-id-2>");
+        console.error("Example: cct diff abc123 def456");
+        process.exit(1);
+    }
+    if (!fs.existsSync(PROJECTS_DIR)) {
+        console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
+        process.exit(1);
+    }
+    const diff = compareSessionsByCID({ sessionId1, sessionId2 });
+    if (!diff) {
+        console.error("One or both sessions not found.");
+        console.error("Use 'cct sessions' to list available sessions.");
+        process.exit(1);
+    }
+    console.log(formatSessionDiff(diff));
+}
+async function cmdGit() {
+    console.log("Linking sessions to git repositories...\n");
+    const report = linkSessionsToGit();
+    console.log(formatGitLinkReport(report));
+}
+async function cmdMcpPerf() {
+    console.log("Analyzing MCP tool performance...\n");
+    const report = analyzeMcpPerformance();
+    console.log(formatMcpPerformanceReport(report));
+}
+async function cmdAlerts() {
+    const report = checkAlerts();
+    console.log(formatAlertsReport(report));
+}
+async function cmdQuotas() {
+    const quotas = checkQuotas();
+    console.log(formatQuotasReport(quotas));
+}
 async function cmdHealth() {
     if (!fs.existsSync(PROJECTS_DIR)) {
         console.error(`Claude projects directory not found: ${PROJECTS_DIR}`);
@@ -772,13 +1090,14 @@ async function cmdHealth() {
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    let commandResult;
     if (!args.command) {
         printHelp();
         process.exit(0);
     }
     switch (args.command) {
         case "scan":
-            await cmdScan(args.file);
+            commandResult = await cmdScan(args.file, args.json);
             break;
         case "fix":
             await cmdFix(args.file, args.noBackup);
@@ -799,7 +1118,7 @@ async function main() {
             await cmdArchive(args.days, args.dryRun);
             break;
         case "maintenance":
-            await cmdMaintenance(args.dryRun, args.auto, args.schedule);
+            await cmdMaintenance(args.auto, args.schedule);
             break;
         case "export":
             await cmdExport(args.file, args.output, args.format, args.withTools);
@@ -816,27 +1135,51 @@ async function main() {
         case "health":
             await cmdHealth();
             break;
+        case "search":
+            await cmdSearch(args.query, { role: args.role, limit: args.limit, project: args.project, days: args.days });
+            break;
+        case "cost":
+            await cmdCost();
+            break;
         case "clean":
             await cmdClean(args.dryRun, args.days, args.category);
             break;
         case "mcp-validate":
-            await cmdMcpValidate(args.file, args.test);
+            await cmdMcpValidate(args.test);
+            break;
+        case "mcp-perf":
+            await cmdMcpPerf();
             break;
         case "sessions":
             await cmdSessions(args.project);
             break;
+        case "diff":
+            await cmdDiff(args.file, args.subcommand);
+            break;
+        case "git":
+            await cmdGit();
+            break;
         case "recover":
             await cmdRecover(args.file, args.extract, args.repair);
             break;
         case "security-scan":
             await cmdSecurityScan(args.file);
             break;
+        case "pii-scan":
+            await cmdPIIScan(args.file, args.details);
+            break;
         case "audit":
             await cmdAudit(args.file);
             break;
         case "retention":
             await cmdRetention(args.days, args.dryRun);
             break;
+        case "alerts":
+            await cmdAlerts();
+            break;
+        case "quotas":
+            await cmdQuotas();
+            break;
         case "trace":
             await cmdTrace(args.subcommand, {
                 dryRun: args.dryRun,
@@ -849,6 +1192,9 @@ async function main() {
                 install: args.install,
             });
             break;
+        case "watch":
+            await cmdWatch(args.json, args.interval, args.autoFix);
+            break;
         case "dashboard":
             if (args.stop) {
                 const stopped = stopDashboard();
@@ -866,7 +1212,7 @@ async function main() {
                 }
             }
             else {
-                await startDashboard({ port: args.port, daemon: args.daemon });
+                await startDashboard({ port: args.port, daemon: args.daemon, authToken: args.token });
             }
             break;
         default:
@@ -874,6 +1220,9 @@ async function main() {
             printHelp();
             process.exit(1);
     }
+    if (args.json && commandResult !== undefined) {
+        console.log(JSON.stringify(commandResult, null, 2));
+    }
 }
 main().catch((err) => {
     console.error("Error:", err.message);