@herodevs/cli 0.3.1 → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,7 @@
+# Copyright (c) 2025 HeroDevs, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,11 +1,151 @@
-# cli
+# @herodevs/cli
 
-This library was generated with [Nx](https://nx.dev).
+The HeroDevs CLI
 
-## Building
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![Version](https://img.shields.io/npm/v/@herodevs/cli.svg)](https://npmjs.org/package/@herodevs/cli)
+[![Downloads/week](https://img.shields.io/npm/dw/@herodevs/cli.svg)](https://npmjs.org/package/@herodevs/cli)
 
-Run `nx build cli` to build the library.
+<!-- toc -->
+* [@herodevs/cli](#herodevscli)
+<!-- tocstop -->
+## Usage
+<!-- usage -->
+```sh-session
+$ npm install -g @herodevs/cli
+$ hd COMMAND
+running command...
+$ hd (--version)
+@herodevs/cli/1.0.0-beta.1 linux-x64 node-v22.14.0
+$ hd --help [COMMAND]
+USAGE
+  $ hd COMMAND
+...
+```
+<!-- usagestop -->
+## Commands
+<!-- commands -->
+* [`hd report committers`](#hd-report-committers)
+* [`hd report purls`](#hd-report-purls)
+* [`hd scan eol`](#hd-scan-eol)
+* [`hd scan sbom`](#hd-scan-sbom)
 
-## Running unit tests
+## `hd report committers`
 
-Run `nx test cli` to execute the unit tests via [Jest](https://jestjs.io).
+Generate report of committers to a git repository
+
+```
+USAGE
+  $ hd report committers [--json] [-m <value>] [-o text|json|csv] [-s]
+
+FLAGS
+  -m, --months=<value>   [default: 12] The number of months of git history to review
+  -o, --output=<option>  [default: text] Output format: text, json, or csv
+                         <options: text|json|csv>
+  -s, --save             Save the committers report as nes.committers.<output>
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Generate report of committers to a git repository
+
+EXAMPLES
+  $ hd report committers
+
+  $ hd report committers -o csv -s
+
+  $ hd report committers --output=json
+
+  $ hd report committers --output=csv
+```
+
+_See code: [src/commands/report/committers.ts](https://github.com/herodevs/cli/blob/v1.0.0-beta.1/src/commands/report/committers.ts)_
+
+## `hd report purls`
+
+Generate a list of purls from a sbom
+
+```
+USAGE
+  $ hd report purls [--json] [-f <value>] [-d <value>] [-s] [-o json|csv]
+
+FLAGS
+  -d, --dir=<value>      The directory to scan in order to create a cyclonedx sbom
+  -f, --file=<value>     The file path of an existing cyclonedx sbom to scan for EOL
+  -o, --output=<option>  [default: json] The format of the saved file (when using --save)
+                         <options: json|csv>
+  -s, --save             Save the list of purls as nes.purls.<output>
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Generate a list of purls from a sbom
+
+EXAMPLES
+  $ hd report purls --dir=./my-project
+
+  $ hd report purls --file=path/to/sbom.json
+
+  $ hd report purls --dir=./my-project --save
+
+  $ hd report purls --save --output=csv
+```
+
+_See code: [src/commands/report/purls.ts](https://github.com/herodevs/cli/blob/v1.0.0-beta.1/src/commands/report/purls.ts)_
+
+## `hd scan eol`
+
+Scan a given sbom for EOL data
+
+```
+USAGE
+  $ hd scan eol [--json] [-f <value>] [-d <value>] [-s]
+
+FLAGS
+  -d, --dir=<value>   The directory to scan in order to create a cyclonedx sbom
+  -f, --file=<value>  The file path of an existing cyclonedx sbom to scan for EOL
+  -s, --save          Save the generated SBOM as nes.sbom.json in the scanned directory
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Scan a given sbom for EOL data
+
+EXAMPLES
+  $ hd scan eol --dir=./my-project
+
+  $ hd scan eol --file=path/to/sbom.json
+```
+
+_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v1.0.0-beta.1/src/commands/scan/eol.ts)_
+
+## `hd scan sbom`
+
+Scan a SBOM for purls
+
+```
+USAGE
+  $ hd scan sbom [--json] [-f <value>] [-d <value>] [-s]
+
+FLAGS
+  -d, --dir=<value>   The directory to scan in order to create a cyclonedx sbom
+  -f, --file=<value>  The file path of an existing cyclonedx sbom to scan for EOL
+  -s, --save          Save the generated SBOM as nes.sbom.json in the scanned directory
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Scan a SBOM for purls
+
+EXAMPLES
+  $ hd scan sbom --dir=./my-project
+
+  $ hd scan sbom --file=path/to/sbom.json
+```
+
+_See code: [src/commands/scan/sbom.ts](https://github.com/herodevs/cli/blob/v1.0.0-beta.1/src/commands/scan/sbom.ts)_
+<!-- commandsstop -->

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+process.env.GRAPHQL_HOST = 'http://localhost:3000';
+
+async function run() {
+  const oclif = await import('@oclif/core');
+  await oclif.execute({ development: true, dir: import.meta.dirname });
+  console.log('\n\n\n=> OCLIF: Command complete.');
+}
+
+run();

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const oclif = await import('@oclif/core');
+await oclif.execute({ dir: import.meta.dirname });

package/dist/api/client.d.ts

@@ -0,0 +1,14 @@
+import * as apollo from '@apollo/client/core/index.js';
+export interface ApolloHelper {
+    mutate<T, V extends apollo.OperationVariables>(mutation: apollo.DocumentNode, variables?: V): Promise<apollo.FetchResult<T>>;
+    query<T, V extends apollo.OperationVariables | undefined = undefined>(query: apollo.DocumentNode, variables?: V): Promise<apollo.ApolloQueryResult<T>>;
+}
+export declare const createApollo: (url: string) => apollo.ApolloClient<apollo.NormalizedCacheObject>;
+export declare class ApolloError extends Error {
+}
+export declare class ApolloClient implements ApolloHelper {
+    #private;
+    constructor(url: string);
+    mutate<T, V extends apollo.OperationVariables>(mutation: apollo.DocumentNode, variables?: V): Promise<apollo.FetchResult<T>>;
+    query<T, V extends apollo.OperationVariables | undefined>(query: apollo.DocumentNode, variables?: V): Promise<apollo.ApolloQueryResult<T>>;
+}

package/dist/api/client.js

@@ -0,0 +1,42 @@
+import * as apollo from '@apollo/client/core/index.js';
+export const createApollo = (url) => new apollo.ApolloClient({
+    cache: new apollo.InMemoryCache({
+        addTypename: false,
+    }),
+    headers: {
+        'User-Agent': `hdcli/${process.env.npm_package_version ?? 'unknown'}`,
+    },
+    link: apollo.ApolloLink.from([
+        new apollo.HttpLink({
+            uri: url,
+        }),
+    ]),
+});
+export class ApolloError extends Error {
+}
+export class ApolloClient {
+    #apollo;
+    constructor(url) {
+        this.#apollo = createApollo(url);
+    }
+    async mutate(mutation, variables) {
+        return this.#apollo
+            .mutate({
+            mutation,
+            variables,
+        })
+            .catch((error) => {
+            throw new ApolloError('Failed GQL Mutation', error);
+        });
+    }
+    async query(query, variables) {
+        return this.#apollo
+            .query({
+            query,
+            variables,
+        })
+            .catch((error) => {
+            throw new ApolloError('Failed GQL Query', error);
+        });
+    }
+}

package/dist/api/nes/nes.client.d.ts

@@ -0,0 +1,16 @@
+import type * as apollo from '@apollo/client/core/index.js';
+import type { ScanResult } from '../../api/types/nes.types.ts';
+export interface NesClient {
+    scan: {
+        sbom: (purls: string[]) => Promise<ScanResult>;
+    };
+}
+export declare class NesApolloClient implements NesClient {
+    #private;
+    scan: {
+        sbom: (purls: string[]) => Promise<ScanResult>;
+    };
+    constructor(url: string);
+    mutate<T, V extends Record<string, unknown>>(mutation: apollo.DocumentNode, variables?: V): Promise<apollo.FetchResult<T>>;
+    query<T, V extends Record<string, unknown> | undefined>(query: apollo.DocumentNode, variables?: V): Promise<apollo.ApolloQueryResult<T>>;
+}

package/dist/api/nes/nes.client.js

@@ -0,0 +1,17 @@
+import { ApolloClient } from "../../api/client.js";
+import { SbomScanner } from "../../service/nes/nes.svc.js";
+export class NesApolloClient {
+    scan = {
+        sbom: SbomScanner(this),
+    };
+    #apollo;
+    constructor(url) {
+        this.#apollo = new ApolloClient(url);
+    }
+    mutate(mutation, variables) {
+        return this.#apollo.mutate(mutation, variables);
+    }
+    query(query, variables) {
+        return this.#apollo.query(query, variables);
+    }
+}

package/dist/api/queries/nes/sbom.d.ts

@@ -0,0 +1,3 @@
+export declare const M_SCAN: {
+    gql: import("graphql/language/ast.js").DocumentNode;
+};

package/dist/api/queries/nes/sbom.js

@@ -0,0 +1,29 @@
+import { gql } from '@apollo/client/core/core.cjs';
+export const M_SCAN = {
+    gql: gql `
+    mutation EolScan($input: InsightsEolScanInput!) {
+        insights {
+          scan {
+            eol(input: $input) {
+            components {
+              purl
+              info {
+                isEol
+                isUnsafe
+                eolAt
+              }
+            } 
+            diagnostics
+            message
+            scanId
+            success
+            warnings {
+              purl
+              type
+            }
+          }
+        }
+      }
+    }
+  `,
+};

package/{report-ingestion/src/lib/queries.d.ts → dist/api/queries/nes/telemetry.d.ts}

@@ -1,2 +1,2 @@
-export declare const TELEMETRY_INITIALIZE_MUTATION: import("graphql/language/ast").DocumentNode;
-export declare const TELEMETRY_REPORT_MUTATION: import("graphql/language/ast").DocumentNode;
+export declare const TELEMETRY_INITIALIZE_MUTATION: import("graphql/language/ast.js").DocumentNode;
+export declare const TELEMETRY_REPORT_MUTATION: import("graphql/language/ast.js").DocumentNode;

package/{report-ingestion/src/lib/queries.js → dist/api/queries/nes/telemetry.js}

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEMETRY_REPORT_MUTATION = exports.TELEMETRY_INITIALIZE_MUTATION = void 0;
-const core_1 = require("@apollo/client/core");
-exports.TELEMETRY_INITIALIZE_MUTATION = (0, core_1.gql) `
+import { gql } from '@apollo/client/core/core.cjs';
+export const TELEMETRY_INITIALIZE_MUTATION = gql `
   mutation Telemetry($clientName: String!) {
     telemetry {
       initialize(input: { context: { client: { id: $clientName } } }) {
@@ -13,7 +10,7 @@ exports.TELEMETRY_INITIALIZE_MUTATION = (0, core_1.gql) `
     }
   }
 `;
-exports.TELEMETRY_REPORT_MUTATION = (0, core_1.gql) `
+export const TELEMETRY_REPORT_MUTATION = gql `
   mutation Report($key: String!, $report: JSON!, $metadata: JSON) {
     telemetry {
       report(input: { key: $key, report: $report, metadata: $metadata }) {
@@ -25,4 +22,3 @@ exports.TELEMETRY_REPORT_MUTATION = (0, core_1.gql) `
     }
   }
 `;
-//# sourceMappingURL=queries.js.map

package/dist/api/types/nes.types.d.ts

@@ -0,0 +1,35 @@
+export type ScanInput = {
+    components: string[];
+    type: 'SBOM';
+} | {
+    type: 'OTHER';
+};
+export interface ScanResponse {
+    insights: {
+        scan: {
+            eol: ScanResponseReport;
+        };
+    };
+}
+export interface ScanResponseReport {
+    components: ScanResultComponent[];
+    diagnostics?: Record<string, unknown>;
+    message: string;
+    success: boolean;
+}
+export type ComponentStatus = 'EOL' | 'LTS' | 'OK';
+export interface ScanResultComponent {
+    info: {
+        eolAt: Date | null;
+        isEol: boolean;
+        isUnsafe: boolean;
+    };
+    purl: string;
+    status?: ComponentStatus;
+}
+export interface ScanResult {
+    components: Map<string, ScanResultComponent>;
+    diagnostics?: Record<string, unknown>;
+    message: string;
+    success: boolean;
+}

package/dist/api/types/nes.types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/report/committers.d.ts

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+export default class Committers extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        months: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * Generates structured report data
+     * @param entries - parsed git log output for commits
+     */
+    private generateReportData;
+    /**
+     * Fetches git commit data with month and author information
+     * @param sinceDate - Date range for git log
+     */
+    private fetchGitCommitData;
+}

package/dist/commands/report/committers.js

@@ -0,0 +1,104 @@
+import { spawnSync } from 'node:child_process';
+import { Command, Flags } from '@oclif/core';
+import fs from 'node:fs';
+import path from 'node:path';
+import { calculateOverallStats, formatOutputBasedOnFlag, groupCommitsByMonth, parseGitLogOutput, } from "../../service/committers.svc.js";
+export default class Committers extends Command {
+    static description = 'Generate report of committers to a git repository';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> -o csv -s',
+        '<%= config.bin %> <%= command.id %> --output=json',
+        '<%= config.bin %> <%= command.id %> --output=csv',
+    ];
+    static flags = {
+        months: Flags.integer({
+            char: 'm',
+            description: 'The number of months of git history to review',
+            default: 12,
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Output format: text, json, or csv',
+            options: ['text', 'json', 'csv'],
+            default: 'text',
+        }),
+        save: Flags.boolean({
+            char: 's',
+            description: 'Save the committers report as nes.committers.<output>',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Committers);
+        const { months, output, save } = flags;
+        const sinceDate = `${months} months ago`;
+        try {
+            // Generate structured report data
+            const entries = this.fetchGitCommitData(sinceDate);
+            const reportData = this.generateReportData(entries);
+            const formattedOutput = formatOutputBasedOnFlag(output, reportData);
+            // Output to file or stdout
+            if (save) {
+                fs.writeFileSync(path.resolve(`nes.committers.${output}`), formattedOutput);
+                this.log(`Report written to ${output}`);
+            }
+            else {
+                this.log(formattedOutput);
+            }
+        }
+        catch (error) {
+            this.error(`Failed to generate report: ${error.message}`);
+        }
+    }
+    /**
+     * Generates structured report data
+     * @param entries - parsed git log output for commits
+     */
+    generateReportData(entries) {
+        if (entries.length === 0) {
+            return { monthly: {}, overall: { total: 0 } };
+        }
+        const monthlyData = groupCommitsByMonth(entries);
+        const overallStats = calculateOverallStats(entries);
+        const grandTotal = entries.length;
+        // Format into a structured report data object
+        const report = {
+            monthly: {},
+            overall: { ...overallStats, total: grandTotal },
+        };
+        // Add monthly totals
+        for (const [month, authors] of Object.entries(monthlyData)) {
+            const monthTotal = Object.values(authors).reduce((sum, count) => sum + count, 0);
+            report.monthly[month] = { ...authors, total: monthTotal };
+        }
+        return report;
+    }
+    /**
+     * Fetches git commit data with month and author information
+     * @param sinceDate - Date range for git log
+     */
+    fetchGitCommitData(sinceDate) {
+        try {
+            const logProcess = spawnSync('git', [
+                'log',
+                '--all', // Include committers on all branches in the repo
+                '--format="%ad|%an"', // Format: date|author
+                '--date=format:%Y-%m', // Format date as YYYY-MM
+                `--since="${sinceDate}"`,
+            ], { encoding: 'utf-8' });
+            if (logProcess.error) {
+                throw new Error(`Git command failed: ${logProcess.error.message}`);
+            }
+            if (!logProcess.stdout) {
+                return [];
+            }
+            return parseGitLogOutput(logProcess.stdout);
+        }
+        catch (error) {
+            this.error(`Failed to fetch git data: ${error.message}`);
+            return []; // This line won't execute due to this.error() above
+        }
+    }
+}

package/dist/commands/report/purls.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class ReportPurls extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<string[]>;
+}

package/dist/commands/report/purls.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command, Flags, ux } from '@oclif/core';
+import { extractPurls, getPurlOutput } from "../../service/purls.svc.js";
+import SbomScan from "../scan/sbom.js";
+export default class ReportPurls extends Command {
+    static description = 'Generate a list of purls from a sbom';
+    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 %> --dir=./my-project --save',
+        '<%= config.bin %> <%= command.id %> --save --output=csv',
+    ];
+    static flags = {
+        file: Flags.string({
+            char: 'f',
+            description: 'The file path of an existing cyclonedx sbom to scan for EOL',
+        }),
+        dir: Flags.string({
+            char: 'd',
+            description: 'The directory to scan in order to create a cyclonedx sbom',
+        }),
+        save: Flags.boolean({
+            char: 's',
+            default: false,
+            description: 'Save the list of purls as nes.purls.<output>',
+        }),
+        output: Flags.string({
+            char: 'o',
+            options: ['json', 'csv'],
+            default: 'json',
+            description: 'The format of the saved file (when using --save)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ReportPurls);
+        const { dir: _dirFlag, file: _fileFlag, save, output } = flags;
+        // Load the SBOM: Only pass the file, dir, and save flags to SbomScan
+        const sbomArgs = SbomScan.getSbomArgs(flags);
+        const sbomCommand = new SbomScan(sbomArgs, this.config);
+        const sbom = await sbomCommand.run();
+        // Extract purls from SBOM
+        const purls = await extractPurls(sbom);
+        ux.action.stop('Scan completed');
+        // Print the purls
+        this.log('Found purls:');
+        for (const purl of purls) {
+            this.log(purl);
+        }
+        // Save if requested
+        if (save) {
+            try {
+                const outputPath = path.join(_dirFlag || process.cwd(), `nes.purls.${output}`);
+                const purlOutput = getPurlOutput(purls, output);
+                fs.writeFileSync(outputPath, purlOutput);
+                this.log(`\nPurls saved to ${outputPath}`);
+            }
+            catch (error) {
+                const errorMessage = error && typeof error === 'object' && 'message' in error ? error.message : 'Unknown error';
+                this.warn(`Failed to save purls: ${errorMessage}`);
+            }
+        }
+        return purls;
+    }
+}

package/dist/commands/scan/eol.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import type { ScanResult } from '../../api/types/nes.types.ts';
+export default class ScanEol extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<ScanResult | {
+        components: [];
+    }>;
+    private checkEolScanDisabled;
+}