@herodevs/cli 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/commands/scan/eol.js

@@ -1,199 +1,271 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { Command, Flags, ux } from '@oclif/core';
-import { batchSubmitPurls } from "../../api/nes/nes.client.js";
-import { config } from "../../config/constants.js";
-import { getErrorMessage, isErrnoException } from "../../service/error.svc.js";
-import { extractPurls, parsePurlsFile } from "../../service/purls.svc.js";
-import { createStatusDisplay, createTableForStatus, groupComponentsByStatus } from "../../ui/eol.ui.js";
-import { INDICATORS, SCAN_ID_KEY, STATUS_COLORS } from "../../ui/shared.ui.js";
-import ScanSbom from "./sbom.js";
+import { trimCdxBom } from '@herodevs/eol-shared';
+import { Command, Flags } from '@oclif/core';
+import ora from 'ora';
+import { submitScan } from "../../api/nes.client.js";
+import { config, filenamePrefix } from "../../config/constants.js";
+import { track } from "../../service/analytics.svc.js";
+import { createSbom } from "../../service/cdx.svc.js";
+import { countComponentsByStatus, formatDataPrivacyLink, formatReportSaveHint, formatScanResults, formatWebReportUrl, } from "../../service/display.svc.js";
+import { readSbomFromFile, saveArtifactToFile, validateDirectory } from "../../service/file.svc.js";
+import { getErrorMessage } from "../../service/log.svc.js";
 export default class ScanEol extends Command {
-    static description = 'Scan a given sbom for EOL data';
+    static description = 'Scan a given SBOM for EOL data';
     static enableJsonFlag = true;
     static examples = [
-        '<%= config.bin %> <%= command.id %> --dir=./my-project',
-        '<%= config.bin %> <%= command.id %> --file=path/to/sbom.json',
-        '<%= config.bin %> <%= command.id %> --purls=path/to/purls.json',
-        '<%= config.bin %> <%= command.id %> -a --dir=./my-project',
+        { description: 'Default behavior (no command or flags specified)', command: '<%= config.bin %>' },
+        { description: 'Equivalent to', command: '<%= config.bin %> <%= command.id %> --dir .' },
+        {
+            description: 'Skip SBOM generation and specify an existing file',
+            command: '<%= config.bin %> <%= command.id %> --file /path/to/sbom.json',
+        },
+        {
+            description: 'Save the report or SBOM to a file',
+            command: '<%= config.bin %> <%= command.id %> --save --saveSbom',
+        },
+        {
+            description: 'Output the report in JSON format (for APIs, CI, etc.)',
+            command: '<%= config.bin %> <%= command.id %> --json',
+        },
     ];
     static flags = {
         file: Flags.string({
             char: 'f',
-            description: 'The file path of an existing cyclonedx sbom to scan for EOL',
-        }),
-        purls: Flags.string({
-            char: 'p',
-            description: 'The file path of a list of purls to scan for EOL',
+            description: 'The file path of an existing SBOM to scan for EOL (supports CycloneDX and SPDX 2.3 formats)',
+            exclusive: ['dir'],
         }),
         dir: Flags.string({
             char: 'd',
-            description: 'The directory to scan in order to create a cyclonedx sbom',
+            default: process.cwd(),
+            defaultHelp: async () => '<current directory>',
+            description: 'The directory to scan in order to create a cyclonedx SBOM',
+            exclusive: ['file'],
         }),
         save: Flags.boolean({
             char: 's',
             default: false,
-            description: 'Save the generated report as eol.report.json in the scanned directory',
+            description: `Save the generated report as ${filenamePrefix}.report.json in the scanned directory`,
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: `Save the generated report to a custom path (defaults to ${filenamePrefix}.report.json when not provided)`,
+        }),
+        saveSbom: Flags.boolean({
+            aliases: ['save-sbom'],
+            default: false,
+            description: `Save the generated SBOM as ${filenamePrefix}.sbom.json in the scanned directory`,
+        }),
+        sbomOutput: Flags.string({
+            aliases: ['sbom-output'],
+            description: `Save the generated SBOM to a custom path (defaults to ${filenamePrefix}.sbom.json when not provided)`,
         }),
-        all: Flags.boolean({
-            char: 'a',
-            description: 'Show all components (default is EOL and SUPPORTED only)',
+        saveTrimmedSbom: Flags.boolean({
+            aliases: ['save-trimmed-sbom'],
             default: false,
+            description: `Save the trimmed SBOM as ${filenamePrefix}.sbom-trimmed.json in the scanned directory`,
         }),
-        table: Flags.boolean({
-            char: 't',
-            description: 'Display the results in a table',
+        hideReportUrl: Flags.boolean({
+            aliases: ['hide-report-url'],
             default: false,
+            description: 'Hide the generated web report URL for this scan',
         }),
+        version: Flags.version(),
     };
     async run() {
         const { flags } = await this.parse(ScanEol);
-        const scan = await this.getScan(flags, this.config);
-        ux.action.stop('\nScan completed');
-        const components = this.getFilteredComponents(scan, flags.all);
-        if (flags.save) {
-            await this.saveReport(components);
+        track('CLI EOL Scan Started', (context) => ({
+            command: context.command,
+            command_flags: context.command_flags,
+        }));
+        const sbomStartTime = performance.now();
+        const sbom = await this.loadSbom();
+        const sbomEndTime = performance.now();
+        if (!flags.file) {
+            track('CLI SBOM Generated', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+                sbom_generation_time: (sbomEndTime - sbomStartTime) / 1000,
+            }));
+        }
+        let reportOutputPath = flags.output;
+        let sbomOutputPath = flags.sbomOutput;
+        if (flags.output && !flags.save) {
+            this.warn('--output requires --save to write the report. Run again with --save to create the file.');
+            reportOutputPath = undefined;
+        }
+        if (flags.sbomOutput && !flags.saveSbom) {
+            this.warn('--sbomOutput requires --saveSbom to write the SBOM. Run again with --saveSbom to create the file.');
+            sbomOutputPath = undefined;
+        }
+        const shouldSaveSbom = !flags.file && flags.saveSbom;
+        if (shouldSaveSbom) {
+            const sbomPath = this.saveSbom(flags.dir, sbom, sbomOutputPath);
+            this.log(`SBOM saved to ${sbomPath}`);
+            track('CLI SBOM Output Saved', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+                sbom_output_path: sbomPath,
+            }));
+        }
+        if (!sbom.components?.length) {
+            track('CLI EOL Scan Ended, No Components Found', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+            }));
+            this.log('No components found in scan. Report not generated.');
+            return;
+        }
+        const scanStartTime = performance.now();
+        const scan = await this.scanSbom(sbom);
+        const scanEndTime = performance.now();
+        const componentCounts = countComponentsByStatus(scan);
+        track('CLI EOL Scan Completed', (context) => ({
+            command: context.command,
+            command_flags: context.command_flags,
+            eol_true_count: componentCounts.EOL,
+            eol_unknown_count: componentCounts.UNKNOWN,
+            nes_available_count: componentCounts.NES_AVAILABLE,
+            number_of_packages: componentCounts.TOTAL,
+            sbom_created: !flags.file,
+            scan_load_time: (scanEndTime - scanStartTime) / 1000,
+            scanned_ecosystems: componentCounts.ECOSYSTEMS,
+            web_report_link: !flags.hideReportUrl && scan.id ? `${config.eolReportUrl}/${scan.id}` : undefined,
+            web_report_hidden: flags.hideReportUrl,
+        }));
+        const shouldSaveReport = flags.save;
+        if (shouldSaveReport) {
+            const reportPath = this.saveReport(scan, flags.dir, reportOutputPath);
+            this.log(`Report saved to ${reportPath}`);
+            track('CLI JSON Scan Output Saved', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+                report_output_path: reportPath,
+            }));
         }
         if (!this.jsonEnabled()) {
-            if (flags.table) {
-                this.log(`${scan.components.size} components scanned`);
-                this.displayResultsInTable(scan, flags.all);
-            }
-            else {
-                this.displayResults(scan, flags.all);
-            }
-            if (scan.scanId) {
-                this.printWebReportUrl(scan.scanId);
-            }
+            this.displayResults(scan, flags.hideReportUrl, Boolean(reportOutputPath || sbomOutputPath));
         }
-        return { components };
+        return scan;
     }
-    async getScan(flags, config) {
-        if (flags.purls) {
-            ux.action.start(`Scanning purls from ${flags.purls}`);
-            const purls = this.getPurlsFromFile(flags.purls);
-            return batchSubmitPurls(purls);
-        }
-        const sbom = await ScanSbom.loadSbom(flags, config);
-        return this.scanSbom(sbom);
+    async loadSbom() {
+        const { flags } = await this.parse(ScanEol);
+        const spinner = ora();
+        spinner.start(flags.file ? 'Loading SBOM file' : 'Generating SBOM');
+        const sbom = flags.file ? this.getSbomFromFile(flags.file) : await this.getSbomFromScan(flags.dir);
+        if (!sbom) {
+            spinner.fail(flags.file ? 'Failed to load SBOM file' : 'Failed to generate SBOM');
+            throw new Error('SBOM not generated');
+        }
+        spinner.succeed(flags.file ? 'Loaded SBOM file' : 'Generated SBOM');
+        return sbom;
     }
-    getPurlsFromFile(filePath) {
+    async scanSbom(sbom) {
+        const { flags } = await this.parse(ScanEol);
+        const spinner = ora().start('Trimming SBOM');
+        const trimmedSbom = trimCdxBom(sbom);
+        spinner.succeed('SBOM trimmed');
+        if (flags.saveTrimmedSbom) {
+            const trimmedPath = this.saveTrimmedSbom(flags.dir, trimmedSbom);
+            this.log(`Trimmed SBOM saved to ${trimmedPath}`);
+            track('CLI Trimmed SBOM Output Saved', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+            }));
+        }
+        spinner.start('Scanning for EOL packages');
         try {
-            const purlsFileString = fs.readFileSync(filePath, 'utf8');
-            return parsePurlsFile(purlsFileString);
+            const scan = await submitScan({ sbom: trimmedSbom });
+            spinner.succeed('Scan completed');
+            return scan;
         }
         catch (error) {
-            this.error(`Failed to read purls file. ${getErrorMessage(error)}`);
+            spinner.fail('Scanning failed');
+            const errorMessage = getErrorMessage(error);
+            track('CLI EOL Scan Failed', (context) => ({
+                command: context.command,
+                command_flags: context.command_flags,
+                scan_failure_reason: errorMessage,
+            }));
+            this.error(`Failed to submit scan to NES. ${errorMessage}`);
         }
     }
-    printWebReportUrl(scanId) {
-        this.logLine();
-        const id = scanId.split(SCAN_ID_KEY)[1];
-        const reportCardUrl = config.eolReportUrl;
-        const url = ux.colorize('blue', `${reportCardUrl}/${id}`);
-        this.log(`🌐 View your free EOL report at: ${ux.colorize('blue', url)}`);
-    }
-    async scanSbom(sbom) {
-        let scan;
-        let purls;
+    saveReport(report, dir, outputPath) {
         try {
-            purls = await extractPurls(sbom);
+            return saveArtifactToFile(dir, { kind: 'report', payload: report, outputPath });
         }
         catch (error) {
-            this.error(`Failed to extract purls from sbom. ${getErrorMessage(error)}`);
+            const errorMessage = getErrorMessage(error);
+            track('CLI Error Encountered', () => ({ error: errorMessage }));
+            this.error(errorMessage);
         }
+    }
+    saveSbom(dir, sbom, outputPath) {
         try {
-            scan = await batchSubmitPurls(purls);
+            return saveArtifactToFile(dir, { kind: 'sbom', payload: sbom, outputPath });
         }
         catch (error) {
-            this.error(`Failed to submit scan to NES from sbom. ${getErrorMessage(error)}`);
-        }
-        if (scan.components.size === 0) {
-            this.warn('No components found in scan');
+            const errorMessage = getErrorMessage(error);
+            track('CLI Error Encountered', () => ({ error: errorMessage }));
+            this.error(errorMessage);
         }
-        return scan;
-    }
-    getFilteredComponents(scan, all) {
-        return Array.from(scan.components.values()).filter((component) => all || ['EOL', 'SUPPORTED'].includes(component.info.status));
     }
-    async saveReport(components) {
-        const { flags } = await this.parse(ScanEol);
-        const reportPath = path.join(flags.dir || process.cwd(), 'eol.report.json');
+    saveTrimmedSbom(dir, sbom) {
         try {
-            fs.writeFileSync(reportPath, JSON.stringify({ components }, null, 2));
-            this.log('Report saved to eol.report.json');
+            return saveArtifactToFile(dir, { kind: 'sbomTrimmed', payload: sbom });
         }
         catch (error) {
-            if (!isErrnoException(error)) {
-                this.error(`Failed to save report: ${getErrorMessage(error)}`);
-            }
-            switch (error.code) {
-                case 'EACCES':
-                    this.error('Permission denied. Unable to save report to eol.report.json');
-                    break;
-                case 'ENOSPC':
-                    this.error('No space left on device. Unable to save report to eol.report.json');
-                    break;
-                default:
-                    this.error(`Failed to save report: ${getErrorMessage(error)}`);
-            }
+            const errorMessage = getErrorMessage(error);
+            track('CLI Error Encountered', () => ({ error: errorMessage }));
+            this.error(errorMessage);
         }
     }
-    displayResults(scan, all) {
-        const { UNKNOWN, OK, SUPPORTED, EOL } = createStatusDisplay(scan.components, all);
-        if (!UNKNOWN.length && !OK.length && !SUPPORTED.length && !EOL.length) {
-            this.displayNoComponentsMessage(all);
-            return;
+    displayResults(report, hideReportUrl, hasCustomOutput) {
+        const lines = formatScanResults(report);
+        for (const line of lines) {
+            this.log(line);
         }
-        this.log(ux.colorize('bold', 'Here are the results of the scan:'));
-        this.logLine();
-        // Display sections in order of increasing severity
-        for (const components of [UNKNOWN, OK, SUPPORTED, EOL]) {
-            this.displayStatusSection(components);
+        if (!hideReportUrl && report.id) {
+            const lines = formatWebReportUrl(report.id, config.eolReportUrl);
+            for (const line of lines) {
+                this.log(line);
+            }
         }
-        this.logLegend();
-    }
-    displayResultsInTable(scan, all) {
-        const grouped = groupComponentsByStatus(scan.components);
-        const statuses = ['SUPPORTED', 'EOL'];
-        if (all) {
-            statuses.unshift('UNKNOWN', 'OK');
-        }
-        for (const status of statuses) {
-            const components = grouped[status];
-            if (components.length > 0) {
-                const table = createTableForStatus(grouped, status);
-                this.displayTable(table, components.length, status);
+        else if (hideReportUrl && !hasCustomOutput) {
+            const lines = formatReportSaveHint();
+            for (const line of lines) {
+                this.log(line);
             }
         }
-        this.logLegend();
-    }
-    displayTable(table, count, status) {
-        this.log(ux.colorize(STATUS_COLORS[status], `${INDICATORS[status]} ${count} ${status} Component(s):`));
-        this.log(ux.colorize(STATUS_COLORS[status], table));
+        const privacyLines = formatDataPrivacyLink();
+        for (const line of privacyLines) {
+            this.log(line);
+        }
+        this.log('* Use --json to output the report payload');
+        this.log(`* Use --save to save the report to ${filenamePrefix}.report.json`);
+        this.log('* Use --help for more commands or options');
     }
-    displayNoComponentsMessage(all) {
-        if (!all) {
-            this.log(ux.colorize('yellow', 'No End-of-Life or Supported components found in scan.'));
-            this.log(ux.colorize('yellow', 'Use --all flag to view all components.'));
+    async getSbomFromScan(dirPath) {
+        try {
+            validateDirectory(dirPath);
+            const sbom = await createSbom(dirPath);
+            if (!sbom) {
+                this.error(`SBOM failed to generate for dir: ${dirPath}`);
+            }
+            return sbom;
         }
-        else {
-            this.log(ux.colorize('yellow', 'No components found in scan.'));
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
+            track('CLI Error Encountered', () => ({ error: errorMessage }));
+            this.error(`Failed to scan directory: ${errorMessage}`);
         }
     }
-    logLine() {
-        this.log(ux.colorize('bold', '-'.repeat(50)));
-    }
-    displayStatusSection(components) {
-        if (components.length > 0) {
-            this.log(components.join('\n'));
-            this.logLine();
+    getSbomFromFile(filePath) {
+        try {
+            return readSbomFromFile(filePath);
+        }
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
+            track('CLI Error Encountered', () => ({ error: errorMessage }));
+            this.error(errorMessage);
         }
-    }
-    logLegend() {
-        this.log(ux.colorize(STATUS_COLORS.UNKNOWN, `${INDICATORS.UNKNOWN} = No Known Issues`));
-        this.log(ux.colorize(STATUS_COLORS.OK, `${INDICATORS.OK} = OK`));
-        this.log(ux.colorize(STATUS_COLORS.SUPPORTED, `${INDICATORS.SUPPORTED}= Supported: End-of-Life (EOL) is scheduled`));
-        this.log(ux.colorize(STATUS_COLORS.EOL, `${INDICATORS.EOL} = End of Life (EOL)`));
     }
 }

package/dist/config/constants.d.ts

@@ -1,9 +1,15 @@
-export declare const EOL_REPORT_URL = "https://eol-report-card.apps.herodevs.com/reports";
-export declare const GRAPHQL_HOST = "https://api.nes.herodevs.com";
+export declare const EOL_REPORT_URL = "https://apps.herodevs.com/eol/reports";
+export declare const GRAPHQL_HOST = "https://gateway.prod.apps.herodevs.io";
 export declare const GRAPHQL_PATH = "/graphql";
+export declare const ANALYTICS_URL = "https://apps.herodevs.com/api/eol/track";
+export declare const CONCURRENT_PAGE_REQUESTS = 3;
+export declare const PAGE_SIZE = 500;
 export declare const config: {
     eolReportUrl: string;
     graphqlHost: string;
     graphqlPath: string;
-    showVulnCount: boolean;
+    analyticsUrl: string;
+    concurrentPageRequests: number;
+    pageSize: number;
 };
+export declare const filenamePrefix = "herodevs";

package/dist/config/constants.js

@@ -1,9 +1,25 @@
-export const EOL_REPORT_URL = 'https://eol-report-card.apps.herodevs.com/reports';
-export const GRAPHQL_HOST = 'https://api.nes.herodevs.com';
+export const EOL_REPORT_URL = 'https://apps.herodevs.com/eol/reports';
+export const GRAPHQL_HOST = 'https://gateway.prod.apps.herodevs.io';
 export const GRAPHQL_PATH = '/graphql';
+export const ANALYTICS_URL = 'https://apps.herodevs.com/api/eol/track';
+export const CONCURRENT_PAGE_REQUESTS = 3;
+export const PAGE_SIZE = 500;
+let concurrentPageRequests = CONCURRENT_PAGE_REQUESTS;
+const parsed = Number.parseInt(process.env.CONCURRENT_PAGE_REQUESTS ?? '0', 10);
+if (parsed > 0) {
+    concurrentPageRequests = parsed;
+}
+let pageSize = PAGE_SIZE;
+const parsedPageSize = Number.parseInt(process.env.PAGE_SIZE ?? '0', 10);
+if (parsedPageSize > 0) {
+    pageSize = parsedPageSize;
+}
 export const config = {
     eolReportUrl: process.env.EOL_REPORT_URL || EOL_REPORT_URL,
     graphqlHost: process.env.GRAPHQL_HOST || GRAPHQL_HOST,
     graphqlPath: process.env.GRAPHQL_PATH || GRAPHQL_PATH,
-    showVulnCount: false,
+    analyticsUrl: process.env.ANALYTICS_URL || ANALYTICS_URL,
+    concurrentPageRequests,
+    pageSize,
 };
+export const filenamePrefix = 'herodevs';

package/dist/hooks/finally/finally.d.ts

@@ -0,0 +1,3 @@
+import type { Hook } from '@oclif/core';
+declare const hook: Hook<'finally'>;
+export default hook;

package/dist/hooks/finally/finally.js

@@ -0,0 +1,18 @@
+import ora, {} from 'ora';
+import { track } from "../../service/analytics.svc.js";
+const hook = async (opts) => {
+    const isHelpOrVersionCmd = opts.argv.includes('--help') || opts.argv.includes('--version');
+    const hasError = Boolean(opts.error);
+    let spinner;
+    if (!isHelpOrVersionCmd && !hasError) {
+        spinner = ora().start('Cleaning up');
+    }
+    await track('CLI Session Ended', (context) => ({
+        cli_version: context.cli_version,
+        ended_at: new Date(),
+    })).promise;
+    if (!isHelpOrVersionCmd && !hasError) {
+        spinner?.stop();
+    }
+};
+export default hook;

package/dist/hooks/{npm-update-notifier.js → init/00_npm-update-notifier.js}

@@ -1,7 +1,7 @@
 import updateNotifier, {} from 'update-notifier';
-import pkg from '../../package.json' with { type: 'json' };
-import { debugLogger } from "../service/log.svc.js";
-const updateNotifierHook = async (options) => {
+import pkg from '../../../package.json' with { type: 'json' };
+import { debugLogger } from "../../service/log.svc.js";
+const updateNotifierHook = async () => {
     debugLogger('pkg.version', pkg.version);
     const distTag = getDistTag(pkg.version);
     debugLogger('distTag', distTag);

package/dist/hooks/init/01_initialize_amplitude.d.ts

@@ -0,0 +1,3 @@
+import type { Hook } from '@oclif/core';
+declare const hook: Hook.Init;
+export default hook;

package/dist/hooks/init/01_initialize_amplitude.js

@@ -0,0 +1,15 @@
+import { parseArgs } from 'node:util';
+import { initializeAnalytics, track } from "../../service/analytics.svc.js";
+const hook = async () => {
+    const args = parseArgs({ allowPositionals: true, strict: false });
+    initializeAnalytics();
+    track('CLI Command Submitted', (context) => ({
+        command: args.positionals.join(' ').trim(),
+        command_flags: Object.entries(args.values).flat().join(' '),
+        app_used: context.app_used,
+        ci_provider: context.ci_provider,
+        cli_version: context.cli_version,
+        started_at: context.started_at,
+    }));
+};
+export default hook;

package/dist/service/analytics.svc.d.ts

@@ -0,0 +1,27 @@
+import { Types } from '@amplitude/analytics-node';
+interface AnalyticsContext {
+    locale?: string;
+    os_platform?: string;
+    os_release?: string;
+    started_at?: Date;
+    ended_at?: Date;
+    app_used?: string;
+    ci_provider?: string;
+    cli_version?: string;
+    command?: string;
+    command_flags?: string;
+    error?: string;
+    eol_true_count?: number;
+    eol_unknown_count?: number;
+    nes_available_count?: number;
+    nes_remediation_count?: number;
+    number_of_packages?: number;
+    sbom_created?: boolean;
+    scan_load_time?: number;
+    scanned_ecosystems?: string[];
+    scan_failure_reason?: string;
+    web_report_link?: string;
+}
+export declare function initializeAnalytics(): void;
+export declare function track(event: string, getProperties?: (context: AnalyticsContext) => Partial<AnalyticsContext>): Types.AmplitudeReturn<Types.Result>;
+export {};