@salesforce/sf-plugins-core 9.1.1 → 10.0.0

package/lib/ux/styledObject.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { inspect } from 'node:util';
+import ansis from 'ansis';
+function prettyPrint(obj) {
+    if (!obj)
+        return inspect(obj);
+    if (typeof obj === 'string')
+        return obj;
+    if (typeof obj === 'number')
+        return obj.toString();
+    if (typeof obj === 'boolean')
+        return obj.toString();
+    if (typeof obj === 'object') {
+        return Object.entries(obj)
+            .map(([key, value]) => `${key}: ${inspect(value)}`)
+            .join(', ');
+    }
+    return inspect(obj);
+}
+export default function styledObject(obj, keys) {
+    if (!obj)
+        return inspect(obj);
+    if (typeof obj === 'string')
+        return obj;
+    if (typeof obj === 'number')
+        return obj.toString();
+    if (typeof obj === 'boolean')
+        return obj.toString();
+    const output = [];
+    const keyLengths = Object.keys(obj).map((key) => key.toString().length);
+    const maxKeyLength = Math.max(...keyLengths) + 2;
+    const logKeyValue = (key, value) => `${ansis.blue(key)}:` + ' '.repeat(maxKeyLength - key.length - 1) + prettyPrint(value);
+    for (const [key, value] of Object.entries(obj)) {
+        if (keys && !keys.includes(key))
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > 0) {
+                output.push(logKeyValue(key, value[0]));
+                for (const e of value.slice(1)) {
+                    output.push(' '.repeat(maxKeyLength) + prettyPrint(e));
+                }
+            }
+        }
+        else if (value !== null && value !== undefined) {
+            output.push(logKeyValue(key, value));
+        }
+    }
+    return output.join('\n');
+}
+//# sourceMappingURL=styledObject.js.map

package/lib/ux/table.d.ts

@@ -0,0 +1,22 @@
+export declare function table<T extends Record<string, unknown>>(data: T[], columns: Columns<T>, options?: Options): void;
+export type Column<T extends Record<string, unknown>> = {
+    extended: boolean;
+    header: string;
+    minWidth: number;
+    get(row: T): unknown;
+};
+export type Columns<T extends Record<string, unknown>> = {
+    [key: string]: Partial<Column<T>>;
+};
+export type Options = {
+    columns?: string;
+    extended?: boolean;
+    filter?: string;
+    'no-header'?: boolean;
+    'no-truncate'?: boolean;
+    rowStart?: string;
+    sort?: string;
+    title?: string;
+    printLine?(s: unknown): void;
+};
+//# sourceMappingURL=table.d.ts.map

package/lib/ux/table.js

@@ -0,0 +1,259 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { inspect } from 'node:util';
+import ansis from 'ansis';
+import { orderBy } from 'natural-orderby';
+import sliceAnsi from 'slice-ansi';
+import sw from 'string-width';
+import { ux } from '@oclif/core';
+function sumBy(arr, fn) {
+    return arr.reduce((sum, i) => sum + fn(i), 0);
+}
+function capitalize(s) {
+    return s ? s.charAt(0).toUpperCase() + s.slice(1).toLowerCase() : '';
+}
+function termwidth(stream) {
+    if (!stream.isTTY) {
+        return 80;
+    }
+    const [width] = stream.getWindowSize();
+    if (width < 1) {
+        return 80;
+    }
+    if (width < 40) {
+        return 40;
+    }
+    return width;
+}
+const stdtermwidth = typeof process.env.OCLIF_COLUMNS === 'string'
+    ? Number.parseInt(process.env.OCLIF_COLUMNS, 10)
+    : termwidth(process.stdout);
+class Table {
+    columns;
+    options;
+    data;
+    constructor(data, columns, options = {}) {
+        // assign columns
+        this.columns = Object.entries(columns).map(([key, col]) => {
+            const extended = col.extended ?? false;
+            // turn null and undefined into empty strings by default
+            const get = col.get ?? ((row) => row[key] ?? '');
+            const header = typeof col.header === 'string' ? col.header : capitalize(key.replaceAll('_', ' '));
+            const minWidth = Math.max(col.minWidth ?? 0, sw(header) + 1);
+            return {
+                extended,
+                get,
+                header,
+                key,
+                minWidth,
+            };
+        });
+        // assign options
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { columns: cols, extended, filter, printLine, sort, title } = options;
+        this.options = {
+            columns: cols,
+            extended,
+            filter,
+            'no-header': options['no-header'] ?? false,
+            'no-truncate': options['no-truncate'] ?? false,
+            printLine: printLine ?? ((s) => ux.stdout(s)),
+            rowStart: ' ',
+            sort,
+            title,
+        };
+        // build table rows from input array data
+        let rows = data.map((d) => Object.fromEntries(this.columns.map((col) => {
+            let val = col.get(d);
+            if (typeof val !== 'string')
+                val = inspect(val, { breakLength: Number.POSITIVE_INFINITY });
+            return [col.key, val];
+        })));
+        // filter rows
+        if (this.options.filter) {
+            // eslint-disable-next-line prefer-const
+            let [header, regex] = this.options.filter.split('=');
+            const isNot = header.startsWith('-');
+            if (isNot)
+                header = header.slice(1);
+            const col = this.findColumnFromHeader(header);
+            if (!col || !regex)
+                throw new Error('Filter flag has an invalid value');
+            rows = rows.filter((d) => {
+                const re = new RegExp(regex);
+                const val = d[col.key];
+                const match = val.match(re);
+                return isNot ? !match : match;
+            });
+        }
+        // sort rows
+        if (this.options.sort) {
+            const sorters = this.options.sort.split(',');
+            const sortHeaders = sorters.map((k) => (k.startsWith('-') ? k.slice(1) : k));
+            const sortKeys = this.filterColumnsFromHeaders(sortHeaders).map((c) => (v) => v[c.key]);
+            const sortKeysOrder = sorters.map((k) => (k.startsWith('-') ? 'desc' : 'asc'));
+            rows = orderBy(rows, sortKeys, sortKeysOrder);
+        }
+        // and filter columns
+        if (this.options.columns) {
+            const filters = this.options.columns.split(',');
+            this.columns = this.filterColumnsFromHeaders(filters);
+        }
+        else if (!this.options.extended) {
+            // show extended columns/properties
+            this.columns = this.columns.filter((c) => !c.extended);
+        }
+        this.data = rows;
+    }
+    display() {
+        const { data, options } = this;
+        // column truncation
+        //
+        // find max width for each column
+        const columns = this.columns.map((c) => {
+            const maxWidth = Math.max(sw('.'.padEnd(c.minWidth - 1)), sw(c.header), getWidestColumnWith(data, c.key)) + 1;
+            return {
+                ...c,
+                maxWidth,
+                width: maxWidth,
+            };
+        });
+        // terminal width
+        const maxWidth = stdtermwidth - 2;
+        // truncation logic
+        const maybeShorten = () => {
+            // don't shorten if full mode
+            if (options['no-truncate'] ?? (!process.stdout.isTTY && !process.env.CLI_UX_SKIP_TTY_CHECK))
+                return;
+            // don't shorten if there is enough screen width
+            const dataMaxWidth = sumBy(columns, (c) => c.width);
+            const overWidth = dataMaxWidth - maxWidth;
+            if (overWidth <= 0)
+                return;
+            // not enough room, short all columns to minWidth
+            for (const col of columns) {
+                col.width = col.minWidth;
+            }
+            // if sum(minWidth's) is greater than term width
+            // nothing can be done so
+            // display all as minWidth
+            const dataMinWidth = sumBy(columns, (c) => c.minWidth);
+            if (dataMinWidth >= maxWidth)
+                return;
+            // some wiggle room left, add it back to "needy" columns
+            let wiggleRoom = maxWidth - dataMinWidth;
+            const needyCols = columns
+                .map((c) => ({ key: c.key, needs: c.maxWidth - c.width }))
+                .sort((a, b) => a.needs - b.needs);
+            for (const { key, needs } of needyCols) {
+                if (!needs)
+                    continue;
+                const col = columns.find((c) => key === c.key);
+                if (!col)
+                    continue;
+                if (wiggleRoom > needs) {
+                    col.width = col.width + needs;
+                    wiggleRoom -= needs;
+                }
+                else if (wiggleRoom) {
+                    col.width = col.width + wiggleRoom;
+                    wiggleRoom = 0;
+                }
+            }
+        };
+        maybeShorten();
+        // print table title
+        if (options.title) {
+            options.printLine(options.title);
+            // print title divider
+            options.printLine(''.padEnd(columns.reduce((sum, col) => sum + col.width, 1), '='));
+            // TODO: avoid mutating the passed in options to prevent sideeffects where this table changes the options to other tables
+            options.rowStart = '| ';
+        }
+        // print headers
+        if (!options['no-header']) {
+            let headers = options.rowStart;
+            for (const col of columns) {
+                const header = col.header;
+                headers += header.padEnd(col.width);
+            }
+            if (headers)
+                options.printLine(ansis.bold(headers));
+            // print header dividers
+            let dividers = options.rowStart;
+            for (const col of columns) {
+                const divider = ''.padEnd(col.width - 1, '─') + ' ';
+                dividers += divider.padEnd(col.width);
+            }
+            if (dividers)
+                options.printLine(ansis.bold(dividers));
+        }
+        // print rows
+        for (const row of data) {
+            // find max number of lines
+            // for all cells in a row
+            // with multi-line strings
+            let numOfLines = 1;
+            for (const col of columns) {
+                const d = row[col.key];
+                const lines = d.split('\n').length;
+                if (lines > numOfLines)
+                    numOfLines = lines;
+            }
+            // eslint-disable-next-line unicorn/no-new-array
+            const linesIndexess = [...new Array(numOfLines).keys()];
+            // print row
+            // including multi-lines
+            for (const i of linesIndexess) {
+                let l = options.rowStart;
+                for (const col of columns) {
+                    const width = col.width;
+                    let d = row[col.key];
+                    d = d.split('\n')[i] || '';
+                    const visualWidth = sw(d);
+                    const colorWidth = d.length - visualWidth;
+                    let cell = d.padEnd(width + colorWidth);
+                    if (cell.length - colorWidth > width || visualWidth === width) {
+                        // truncate the cell, preserving ANSI escape sequences, and keeping
+                        // into account the width of fullwidth unicode characters
+                        cell = sliceAnsi(cell, 0, width - 2) + '… ';
+                        // pad with spaces; this is necessary in case the original string
+                        // contained fullwidth characters which cannot be split
+                        cell += ' '.repeat(width - sw(cell));
+                    }
+                    l += cell;
+                }
+                options.printLine(l);
+            }
+        }
+    }
+    filterColumnsFromHeaders(filters) {
+        const cols = [];
+        for (const f of [...new Set(filters)]) {
+            const c = this.columns.find((i) => i.header.toLowerCase() === f.toLowerCase());
+            if (c)
+                cols.push(c);
+        }
+        return cols;
+    }
+    findColumnFromHeader(header) {
+        return this.columns.find((c) => c.header.toLowerCase() === header.toLowerCase());
+    }
+}
+export function table(data, columns, options = {}) {
+    new Table(data, columns, options).display();
+}
+const getWidestColumnWith = (data, columnKey) => data.reduce((previous, current) => {
+    const d = current[columnKey];
+    if (typeof d !== 'string')
+        return previous;
+    // convert multi-line cell to single longest line
+    // for width calculations
+    const manyLines = d.split('\n');
+    return Math.max(previous, manyLines.length > 1 ? Math.max(...manyLines.map((r) => sw(r))) : sw(d));
+}, 0);
+//# sourceMappingURL=table.js.map

package/lib/ux/ux.d.ts

@@ -1,7 +1,7 @@
-import { ux } from '@oclif/core';
 import { AnyJson } from '@salesforce/ts-types';
 import { UxBase } from './base.js';
 import { Spinner } from './spinner.js';
+import { Columns as TableColumns, Options as TableOptions } from './table.js';
 /**
  * UX methods for plugins. Automatically suppress console output if outputEnabled is set to false.
  *
@@ -31,6 +31,13 @@ export declare class Ux extends UxBase {
      * @param args Args to be used for formatting.
      */
     log(message?: string, ...args: string[]): void;
+    /**
+     * Log a message to stderr. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Message to log. Formatting is supported.
+     * @param args Args to be used for formatting.
+     */
+    logToStderr(message?: string, ...args: string[]): void;
     /**
      * Log a warning message to the console. This will be automatically suppressed if output is disabled.
      *
@@ -58,7 +65,7 @@ export declare class Ux extends UxBase {
      *
      * @param obj JSON to display
      */
-    styledJSON(obj: AnyJson): void;
+    styledJSON(obj: AnyJson, theme?: Record<string, string>): void;
     /**
      * Display stylized object to the console. This will be automatically suppressed if output is disabled.
      *
@@ -76,8 +83,8 @@ export declare class Ux extends UxBase {
 export declare namespace Ux {
     namespace Table {
         type Data = Record<string, unknown>;
-        type Columns<T extends Data> = ux.Table.table.Columns<T>;
-        type Options = ux.Table.table.Options;
+        type Columns<T extends Data> = TableColumns<T>;
+        type Options = TableOptions;
     }
 }
 //# sourceMappingURL=ux.d.ts.map

package/lib/ux/ux.js

@@ -4,9 +4,13 @@
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
+import ansis from 'ansis';
 import { ux } from '@oclif/core';
+import terminalLink from 'terminal-link';
 import { UxBase } from './base.js';
 import { Spinner } from './spinner.js';
+import { table } from './table.js';
+import styledObject from './styledObject.js';
 /**
  * UX methods for plugins. Automatically suppress console output if outputEnabled is set to false.
  *
@@ -38,7 +42,16 @@ export class Ux extends UxBase {
      * @param args Args to be used for formatting.
      */
     log(message, ...args) {
-        this.maybeNoop(() => ux.log(message, ...args));
+        this.maybeNoop(() => ux.stdout(message, ...args));
+    }
+    /**
+     * Log a message to stderr. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Message to log. Formatting is supported.
+     * @param args Args to be used for formatting.
+     */
+    logToStderr(message, ...args) {
+        this.maybeNoop(() => ux.stderr(message, ...args));
     }
     /**
      * Log a warning message to the console. This will be automatically suppressed if output is disabled.
@@ -56,7 +69,7 @@ export class Ux extends UxBase {
      * @param options Options for how the table should be displayed
      */
     table(data, columns, options) {
-        this.maybeNoop(() => ux.table(data, columns, { 'no-truncate': true, ...options }));
+        this.maybeNoop(() => table(data, columns, { 'no-truncate': true, ...options }));
     }
     /**
      * Display a url to the console. This will be automatically suppressed if output is disabled.
@@ -66,15 +79,25 @@ export class Ux extends UxBase {
      * @param params
      */
     url(text, uri, params = {}) {
-        this.maybeNoop(() => ux.url(text, uri, params));
+        this.maybeNoop(() => ux.stdout(terminalLink(text, uri, { fallback: () => uri, ...params })));
     }
     /**
      * Display stylized JSON to the console. This will be automatically suppressed if output is disabled.
      *
      * @param obj JSON to display
      */
-    styledJSON(obj) {
-        this.maybeNoop(() => ux.styledJSON(obj));
+    styledJSON(obj, theme) {
+        // Default theme if sf's theme.json does not have the json property set. This will allow us
+        // to ship sf-plugins-core before the theme.json is updated.
+        const defaultTheme = {
+            key: 'blueBright',
+            string: 'greenBright',
+            number: 'blue',
+            boolean: 'redBright',
+            null: 'blackBright',
+        };
+        const mergedTheme = { ...defaultTheme, ...theme };
+        this.maybeNoop(() => ux.stdout(ux.colorizeJson(obj, { theme: mergedTheme })));
     }
     /**
      * Display stylized object to the console. This will be automatically suppressed if output is disabled.
@@ -83,7 +106,7 @@ export class Ux extends UxBase {
      * @param keys Keys of object to display
      */
     styledObject(obj, keys) {
-        this.maybeNoop(() => ux.styledObject(obj, keys));
+        this.maybeNoop(() => ux.stdout(styledObject(obj, keys)));
     }
     /**
      * Display stylized header to the console. This will be automatically suppressed if output is disabled.
@@ -91,7 +114,7 @@ export class Ux extends UxBase {
      * @param text header to display
      */
     styledHeader(text) {
-        this.maybeNoop(() => ux.styledHeader(text));
+        this.maybeNoop(() => ux.stdout(ansis.dim('=== ') + ansis.bold(text) + '\n'));
     }
 }
 //# sourceMappingURL=ux.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sf-plugins-core",
-  "version": "9.1.1",
+  "version": "10.0.0",
   "description": "Utils for writing Salesforce CLI plugins",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -20,6 +20,7 @@
     "prepack": "sf-prepack",
     "prepare": "sf-install",
     "test": "wireit",
+    "test:integration": "mocha test/**/*.integration.ts --timeout 30000",
     "test:only": "wireit"
   },
   "exports": {
@@ -45,16 +46,22 @@
   "dependencies": {
     "@inquirer/confirm": "^3.1.9",
     "@inquirer/password": "^2.1.9",
-    "@oclif/core": "^3.26.6",
-    "@salesforce/core": "^7.3.9",
+    "@oclif/core": "^4",
+    "@salesforce/core": "^7.3.10",
     "@salesforce/kit": "^3.1.2",
     "@salesforce/ts-types": "^2.0.9",
-    "chalk": "^5.3.0"
+    "ansis": "^3.1.1",
+    "cli-progress": "^3.12.0",
+    "natural-orderby": "^3.0.2",
+    "slice-ansi": "^7.1.0",
+    "string-width": "^7.1.0",
+    "terminal-link": "^3.0.0"
   },
   "devDependencies": {
     "@inquirer/type": "^1.3.3",
     "@salesforce/dev-scripts": "^9.1.2",
-    "eslint-plugin-sf-plugin": "^1.18.4",
+    "@types/cli-progress": "^3.11.5",
+    "eslint-plugin-sf-plugin": "^1.18.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.5"
   },