codeslick-cli 1.1.3 → 1.1.5

package/README.md

@@ -259,6 +259,7 @@ The `.codeslick.json` file controls how CodeSlick scans your code.
 | `autofix` | boolean | `false` | Enable auto-fix (experimental) |
 | `exclude` | string[] | See above | Glob patterns to exclude from scanning |
 | `languages` | string[] | All | Languages to scan: `javascript`, `typescript`, `python`, `java` |
+| `telemetry` | boolean | `true` | Enable anonymous usage analytics |
 
 ### Severity Thresholds
 
@@ -533,20 +534,27 @@ MIT License - see [LICENSE](../../LICENSE) for details.
 - **Issues**: https://github.com/VitorLourenco/codeslick2/issues
 - **Email**: support@codeslick.dev
 
-## What's New in v1.0
+## What's New in v1.1
+
+- **Update Notifications** - CLI notifies you when a new version is available
+- **Anonymous Telemetry** - Usage stats for dashboard analytics (disable with `cs config set telemetry false`)
+- **Improved SSRF Detection** - Internal API routes (`/api/...`) no longer trigger false positives
+- **Fixed Critical Sorting** - CRITICAL issues now correctly appear first in reports
+- **Markdown Reports** - Auto-generates detailed reports for large scans (>20 files or >30 issues)
+
+### v1.0 Features
 
 - **Staged Files by Default** - Fast pre-commit scans (<1s for most commits)
 - **Quick Mode** - Skip TypeScript type checking with `--quick` for even faster scans
 - **Smart Output** - Only shows CRITICAL and HIGH issues by default (use `--verbose` for all)
-- **Markdown Reports** - Auto-generates detailed reports for large scans (>20 files or >30 issues)
 - **268 Security Checks** - OWASP Top 10:2025 compliant
 
 ## Roadmap
 
-### v1.1 (Q2 2026)
-- Auto-fix support (--fix flag)
+### v1.2 (Coming Soon)
 - Custom rule configuration
 - IDE integration (VS Code extension)
+- Enhanced auto-fix support
 
 ---
 

package/bin/codeslick.cjs

@@ -25,8 +25,13 @@ const { scanCommand } = require('../dist/packages/cli/src/commands/scan');
 const { initCommand } = require('../dist/packages/cli/src/commands/init');
 const { configCommand } = require('../dist/packages/cli/src/commands/config');
 const { loginCommand, logoutCommand, whoamiCommand } = require('../dist/packages/cli/src/commands/auth');
+const { startBackgroundUpdateCheck } = require('../dist/packages/cli/src/utils/version-check');
 const { version } = require('../package.json');
 
+// Start version check in background (non-blocking)
+// Will print notification at the end if update is available
+void startBackgroundUpdateCheck();
+
 // Detect if running as 'cs' or 'codeslick'
 const scriptName = process.argv[1].includes('/cs') ? 'cs' : 'codeslick';
 

package/dist/packages/cli/src/utils/version-check.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Version Check Utility
+ *
+ * Checks npm registry for newer versions and notifies users.
+ * Uses a 24-hour cache to avoid slowing down every command.
+ */
+/**
+ * Get the currently installed version
+ */
+export declare function getInstalledVersion(): string;
+/**
+ * Check for updates and return info if available
+ * Uses cache to avoid checking on every command
+ */
+export declare function checkForUpdates(): Promise<{
+    hasUpdate: boolean;
+    currentVersion: string;
+    latestVersion: string;
+} | null>;
+/**
+ * Print update notification if a new version is available
+ * Non-blocking - runs in background
+ */
+export declare function printUpdateNotification(): Promise<void>;
+/**
+ * Start update check in background (non-blocking)
+ * Returns a promise that resolves when check is complete
+ */
+export declare function startBackgroundUpdateCheck(): Promise<void>;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/packages/cli/src/utils/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../../../../src/utils/version-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAO5C;AA6ED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAAC,CAqCR;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAe7D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D"}

package/dist/packages/cli/src/utils/version-check.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Version Check Utility
+ *
+ * Checks npm registry for newer versions and notifies users.
+ * Uses a 24-hour cache to avoid slowing down every command.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstalledVersion = getInstalledVersion;
+exports.checkForUpdates = checkForUpdates;
+exports.printUpdateNotification = printUpdateNotification;
+exports.startBackgroundUpdateCheck = startBackgroundUpdateCheck;
+const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const chalk_1 = __importDefault(require("chalk"));
+const PACKAGE_NAME = 'codeslick-cli';
+const CACHE_FILE = (0, path_1.join)((0, os_1.homedir)(), '.codeslick', 'version-cache.json');
+const CACHE_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CHECK_TIMEOUT_MS = 3000; // 3 seconds - don't slow down the CLI
+/**
+ * Get the currently installed version
+ */
+function getInstalledVersion() {
+    try {
+        const pkg = require('../../package.json');
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Compare two semver versions
+ * Returns: 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a, b) {
+    const partsA = a.split('.').map(Number);
+    const partsB = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const numA = partsA[i] || 0;
+        const numB = partsB[i] || 0;
+        if (numA > numB)
+            return 1;
+        if (numA < numB)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * Read cached version info
+ */
+function readCache() {
+    try {
+        if (!(0, fs_1.existsSync)(CACHE_FILE))
+            return null;
+        const data = JSON.parse((0, fs_1.readFileSync)(CACHE_FILE, 'utf-8'));
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write version info to cache
+ */
+function writeCache(latestVersion) {
+    try {
+        const cacheDir = (0, path_1.join)((0, os_1.homedir)(), '.codeslick');
+        if (!(0, fs_1.existsSync)(cacheDir)) {
+            (0, fs_1.mkdirSync)(cacheDir, { recursive: true });
+        }
+        const cache = {
+            latestVersion,
+            checkedAt: Date.now(),
+        };
+        (0, fs_1.writeFileSync)(CACHE_FILE, JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Silently ignore cache write errors
+    }
+}
+/**
+ * Fetch latest version from npm registry
+ */
+async function fetchLatestVersion() {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+        const response = await fetch(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                'Accept': 'application/json',
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok)
+            return null;
+        const data = await response.json();
+        return data.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check for updates and return info if available
+ * Uses cache to avoid checking on every command
+ */
+async function checkForUpdates() {
+    try {
+        const currentVersion = getInstalledVersion();
+        // Check cache first
+        const cache = readCache();
+        const now = Date.now();
+        let latestVersion = null;
+        if (cache && (now - cache.checkedAt) < CACHE_DURATION_MS) {
+            // Use cached version
+            latestVersion = cache.latestVersion;
+        }
+        else {
+            // Fetch from npm (fire and forget - don't block)
+            latestVersion = await fetchLatestVersion();
+            if (latestVersion) {
+                writeCache(latestVersion);
+            }
+            else if (cache) {
+                // Use stale cache if fetch failed
+                latestVersion = cache.latestVersion;
+            }
+        }
+        if (!latestVersion)
+            return null;
+        const hasUpdate = compareVersions(latestVersion, currentVersion) > 0;
+        return {
+            hasUpdate,
+            currentVersion,
+            latestVersion,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Print update notification if a new version is available
+ * Non-blocking - runs in background
+ */
+async function printUpdateNotification() {
+    try {
+        const result = await checkForUpdates();
+        if (result?.hasUpdate) {
+            console.log('');
+            console.log(chalk_1.default.cyan('┌─────────────────────────────────────────────────┐'));
+            console.log(chalk_1.default.cyan('│') + chalk_1.default.yellow(`  Update available: ${result.currentVersion} → ${result.latestVersion}`.padEnd(47)) + chalk_1.default.cyan('│'));
+            console.log(chalk_1.default.cyan('│') + chalk_1.default.gray('  Run: ') + chalk_1.default.green('npm install -g codeslick-cli'.padEnd(39)) + chalk_1.default.cyan('│'));
+            console.log(chalk_1.default.cyan('└─────────────────────────────────────────────────┘'));
+            console.log('');
+        }
+    }
+    catch {
+        // Silently ignore errors - don't disrupt user workflow
+    }
+}
+/**
+ * Start update check in background (non-blocking)
+ * Returns a promise that resolves when check is complete
+ */
+function startBackgroundUpdateCheck() {
+    return printUpdateNotification().catch(() => { });
+}
+//# sourceMappingURL=version-check.js.map

package/dist/packages/cli/src/utils/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../../../../src/utils/version-check.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeslick-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "CodeSlick CLI tool for pre-commit security scanning",
   "main": "dist/index.js",
   "bin": {

package/src/utils/version-check.ts

@@ -0,0 +1,185 @@
+/**
+ * Version Check Utility
+ *
+ * Checks npm registry for newer versions and notifies users.
+ * Uses a 24-hour cache to avoid slowing down every command.
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import chalk from 'chalk';
+
+const PACKAGE_NAME = 'codeslick-cli';
+const CACHE_FILE = join(homedir(), '.codeslick', 'version-cache.json');
+const CACHE_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CHECK_TIMEOUT_MS = 3000; // 3 seconds - don't slow down the CLI
+
+interface VersionCache {
+  latestVersion: string;
+  checkedAt: number;
+}
+
+/**
+ * Get the currently installed version
+ */
+export function getInstalledVersion(): string {
+  try {
+    const pkg = require('../../package.json');
+    return pkg.version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Compare two semver versions
+ * Returns: 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a: string, b: string): number {
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Read cached version info
+ */
+function readCache(): VersionCache | null {
+  try {
+    if (!existsSync(CACHE_FILE)) return null;
+    const data = JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
+    return data as VersionCache;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write version info to cache
+ */
+function writeCache(latestVersion: string): void {
+  try {
+    const cacheDir = join(homedir(), '.codeslick');
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true });
+    }
+    const cache: VersionCache = {
+      latestVersion,
+      checkedAt: Date.now(),
+    };
+    writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+  } catch {
+    // Silently ignore cache write errors
+  }
+}
+
+/**
+ * Fetch latest version from npm registry
+ */
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: controller.signal,
+      headers: {
+        'Accept': 'application/json',
+      },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) return null;
+
+    const data = await response.json() as { version?: string };
+    return data.version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check for updates and return info if available
+ * Uses cache to avoid checking on every command
+ */
+export async function checkForUpdates(): Promise<{
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion: string;
+} | null> {
+  try {
+    const currentVersion = getInstalledVersion();
+
+    // Check cache first
+    const cache = readCache();
+    const now = Date.now();
+
+    let latestVersion: string | null = null;
+
+    if (cache && (now - cache.checkedAt) < CACHE_DURATION_MS) {
+      // Use cached version
+      latestVersion = cache.latestVersion;
+    } else {
+      // Fetch from npm (fire and forget - don't block)
+      latestVersion = await fetchLatestVersion();
+
+      if (latestVersion) {
+        writeCache(latestVersion);
+      } else if (cache) {
+        // Use stale cache if fetch failed
+        latestVersion = cache.latestVersion;
+      }
+    }
+
+    if (!latestVersion) return null;
+
+    const hasUpdate = compareVersions(latestVersion, currentVersion) > 0;
+
+    return {
+      hasUpdate,
+      currentVersion,
+      latestVersion,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Print update notification if a new version is available
+ * Non-blocking - runs in background
+ */
+export async function printUpdateNotification(): Promise<void> {
+  try {
+    const result = await checkForUpdates();
+
+    if (result?.hasUpdate) {
+      console.log('');
+      console.log(chalk.cyan('┌─────────────────────────────────────────────────┐'));
+      console.log(chalk.cyan('│') + chalk.yellow(`  Update available: ${result.currentVersion} → ${result.latestVersion}`.padEnd(47)) + chalk.cyan('│'));
+      console.log(chalk.cyan('│') + chalk.gray('  Run: ') + chalk.green('npm install -g codeslick-cli'.padEnd(39)) + chalk.cyan('│'));
+      console.log(chalk.cyan('└─────────────────────────────────────────────────┘'));
+      console.log('');
+    }
+  } catch {
+    // Silently ignore errors - don't disrupt user workflow
+  }
+}
+
+/**
+ * Start update check in background (non-blocking)
+ * Returns a promise that resolves when check is complete
+ */
+export function startBackgroundUpdateCheck(): Promise<void> {
+  return printUpdateNotification().catch(() => {});
+}