@salesforce/sf-plugins-core 1.2.1 → 1.4.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.4.1](https://github.com/salesforcecli/sf-plugins-core/compare/v1.4.0...v1.4.1) (2022-03-02)
+
+### Bug Fixes
+
+- make toHelpSection types more friendly ([add364b](https://github.com/salesforcecli/sf-plugins-core/commit/add364b6be532dae6fb49f62164dad486b186347))
+
+## [1.4.0](https://github.com/salesforcecli/sf-plugins-core/compare/v1.3.0...v1.4.0) (2022-03-02)
+
+### Features
+
+- common salesforce flags ([00ab4fc](https://github.com/salesforcecli/sf-plugins-core/commit/00ab4fc94d268b44dccb6a2de02fe4f720ff0fc0))
+- debugging ([cc3fd1e](https://github.com/salesforcecli/sf-plugins-core/commit/cc3fd1e46134c08a4d76e79c74605e90e09abbb3))
+- duration flag ([b11eaab](https://github.com/salesforcecli/sf-plugins-core/commit/b11eaabb0050961094f412d85c2bbbf4b183cd40))
+
+### Bug Fixes
+
+- error keys support createError ([f094c49](https://github.com/salesforcecli/sf-plugins-core/commit/f094c49f1ec1063fb05cdc74e1aab88e7ceb7f13))
+- error message doesn't take params ([5d917bf](https://github.com/salesforcecli/sf-plugins-core/commit/5d917bf100d41077d2eaabcd89c41fa049ef6f21))
+- wrong error name ([1b3bbbe](https://github.com/salesforcecli/sf-plugins-core/commit/1b3bbbeae9f3e888faf438fe8d1f4bfd6bdac2c9))
+
+## [1.3.0](https://github.com/salesforcecli/sf-plugins-core/compare/v1.2.1...v1.3.0) (2022-02-23)
+
+### Features
+
+- add requiresProject property ([5ff0cf3](https://github.com/salesforcecli/sf-plugins-core/commit/5ff0cf34fffe896e1ed312585705ff13436e58cf))
+
 ### [1.2.1](https://github.com/salesforcecli/sf-plugins-core/compare/v1.2.0...v1.2.1) (2022-01-27)
 
 ### Bug Fixes

package/README.md

@@ -2,7 +2,7 @@
 
 # Description
 
-The @salesforce/sf-pluins-core provides utilities for writing [sf](https://github.com/salesforcecli/cli) plugins.
+The @salesforce/sf-plugins-core provides utilities for writing [sf](https://github.com/salesforcecli/cli) plugins.
 
 ## SfCommand Abstract Class
 
@@ -43,3 +43,35 @@ A general purpose class that prompts a user for information. See [inquirer NPM M
 ## Flags
 
 Flags is a convenience reference to [@oclif/core#Flags](https://github.com/oclif/core/blob/main/src/flags.ts)
+
+### Specialty Flags
+
+These flags can be imported into a command and used like any other flag. See code examples in the links
+
+- [orgApiVersionFlag](src/flags/apiVersion.ts)
+  - specifies a Salesforce API version.
+  - reads from Config (if available)
+  - validates version is still active
+  - warns if version if deprecated
+- [requiredOrgFlag](src/flags/orgFlags.ts)
+  - accepts a username or alias
+  - aware of configuration defaults
+  - throws if org or default doesn't exist or can't be found
+- [optionalOrgFlag](src/flags/orgFlags.ts)
+  - accepts a username or alias
+  - aware of configuration defaults
+  - might be undefined if an org isn't found
+- [requiredHubFlag](src/flags/orgFlags.ts)
+  - accepts a username or alias
+  - aware of configuration defaults
+  - throws if org or default doesn't exist or can't be found
+  - throws if an org is found but is not a dev hub
+- [durationFlag](src/flags/duration.ts)
+  - specify a unit
+  - optionally specify a min, max, and defaultValue
+  - returns a [Duration](https://github.com/forcedotcom/kit/blob/main/src/duration.ts)
+  - can be undefined if you don't set the default
+- [salesforceIdFlag](src/flags/salesforceId.ts)
+  - validates that IDs are valid salesforce ID
+  - optionally restrict to 15/18 char
+  - optionally require it to be begin with a certain prefix

package/lib/deauthorizer.d.ts

@@ -20,3 +20,4 @@ export declare namespace Deauthorizer {
         failures: string[];
     };
 }
+//# sourceMappingURL=deauthorizer.d.ts.map

package/lib/deployer.d.ts

@@ -71,3 +71,4 @@ export declare namespace Deployer {
         [key: string]: T;
     };
 }
+//# sourceMappingURL=deployer.d.ts.map

package/lib/exported.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 export { toHelpSection } from './util';
 export { Deployable, Deployer } from './deployer';
 export { Deauthorizer } from './deauthorizer';
@@ -5,4 +6,22 @@ export { Progress, Prompter, generateTableChoices } from './ux';
 export { SfHook } from './hooks';
 export * from './types';
 export { SfCommand, SfCommandInterface } from './sfCommand';
-export { Flags } from '@oclif/core';
+export declare const Flags: {
+    boolean: typeof import("@oclif/core/lib/parser/flags").boolean;
+    directory: (opts?: ({
+        exists?: boolean | undefined;
+    } & Partial<import("@oclif/core/lib/interfaces").OptionFlag<string>>) | undefined) => import("@oclif/core/lib/interfaces").OptionFlag<string | undefined>;
+    file: (opts?: ({
+        exists?: boolean | undefined;
+    } & Partial<import("@oclif/core/lib/interfaces").OptionFlag<string>>) | undefined) => import("@oclif/core/lib/interfaces").OptionFlag<string | undefined>;
+    integer: import("@oclif/core/lib/interfaces").Definition<number>;
+    string: import("@oclif/core/lib/interfaces").Definition<string>;
+    url: import("@oclif/core/lib/interfaces").Definition<import("url").URL>;
+    duration: (durationConfig: import("./flags/duration").DurationFlagConfig) => import("@oclif/core/lib/interfaces").OptionFlag<import("@salesforce/kit").Duration | undefined>;
+    salesforceId: (inputs?: import("./flags/salesforceId").IdFlagConfig) => import("@oclif/core/lib/interfaces").OptionFlag<string | undefined>;
+    orgApiVersion: import("@oclif/core/lib/interfaces").Definition<string>;
+    requiredOrg: import("@oclif/core/lib/interfaces").Definition<import("@salesforce/core").Org>;
+    requiredHub: import("@oclif/core/lib/interfaces").Definition<import("@salesforce/core").Org>;
+    optionalOrg: import("@oclif/core/lib/interfaces").Definition<import("@salesforce/core").Org | undefined>;
+};
+//# sourceMappingURL=exported.d.ts.map

package/lib/exported.js

@@ -17,6 +17,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Flags = exports.SfCommand = exports.SfHook = exports.generateTableChoices = exports.Prompter = exports.Progress = exports.Deauthorizer = exports.Deployer = exports.Deployable = exports.toHelpSection = void 0;
+const core_1 = require("@oclif/core");
 var util_1 = require("./util");
 Object.defineProperty(exports, "toHelpSection", { enumerable: true, get: function () { return util_1.toHelpSection; } });
 var deployer_1 = require("./deployer");
@@ -33,6 +34,23 @@ Object.defineProperty(exports, "SfHook", { enumerable: true, get: function () {
 __exportStar(require("./types"), exports);
 var sfCommand_1 = require("./sfCommand");
 Object.defineProperty(exports, "SfCommand", { enumerable: true, get: function () { return sfCommand_1.SfCommand; } });
-var core_1 = require("@oclif/core");
-Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
+// custom flags
+const orgFlags_1 = require("./flags/orgFlags");
+const salesforceId_1 = require("./flags/salesforceId");
+const orgApiVersion_1 = require("./flags/orgApiVersion");
+const duration_1 = require("./flags/duration");
+exports.Flags = {
+    boolean: core_1.Flags.boolean,
+    directory: core_1.Flags.directory,
+    file: core_1.Flags.file,
+    integer: core_1.Flags.integer,
+    string: core_1.Flags.string,
+    url: core_1.Flags.url,
+    duration: duration_1.durationFlag,
+    salesforceId: salesforceId_1.salesforceIdFlag,
+    orgApiVersion: orgApiVersion_1.orgApiVersionFlag,
+    requiredOrg: orgFlags_1.requiredOrgFlag,
+    requiredHub: orgFlags_1.requiredHubFlag,
+    optionalOrg: orgFlags_1.optionalOrgFlag,
+};
 //# sourceMappingURL=exported.js.map

package/lib/flags/duration.d.ts

@@ -0,0 +1,29 @@
+import { Interfaces } from '@oclif/core';
+import { Duration } from '@salesforce/kit';
+declare type DurationUnit = Lowercase<keyof typeof Duration.Unit>;
+export interface DurationFlagConfig extends Partial<Interfaces.OptionFlagProps> {
+    unit: Required<DurationUnit>;
+    defaultValue?: number;
+    min?: number;
+    max?: number;
+}
+/**
+ * Duration flag with built-in default and min/max validation
+ * You must specify a unit
+ * Defaults to undefined if you don't specify a default
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *    'wait': duration({
+ *       min: 1,
+ *       unit: 'minutes'
+ *       defaultValue: 33,
+ *       char: 'w',
+ *       description: 'Wait time in minutes'
+ *    }),
+ * }
+ */
+export declare const durationFlag: (durationConfig: DurationFlagConfig) => Interfaces.OptionFlag<Duration | undefined>;
+export {};
+//# sourceMappingURL=duration.d.ts.map

package/lib/flags/duration.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.durationFlag = void 0;
+/*
+ * Copyright (c) 2020, 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
+ */
+const core_1 = require("@oclif/core");
+const core_2 = require("@salesforce/core");
+const kit_1 = require("@salesforce/kit");
+core_2.Messages.importMessagesDirectory(__dirname);
+const messages = core_2.Messages.loadMessages('@salesforce/sf-plugins-core', 'messages');
+/**
+ * Duration flag with built-in default and min/max validation
+ * You must specify a unit
+ * Defaults to undefined if you don't specify a default
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *    'wait': duration({
+ *       min: 1,
+ *       unit: 'minutes'
+ *       defaultValue: 33,
+ *       char: 'w',
+ *       description: 'Wait time in minutes'
+ *    }),
+ * }
+ */
+const durationFlag = (durationConfig) => {
+    const { defaultValue, min, max, unit, ...baseProps } = durationConfig;
+    return core_1.Flags.build({
+        ...baseProps,
+        parse: async (input) => validate(input, { min, max, unit }),
+        default: defaultValue ? async () => toDuration(defaultValue, unit) : undefined,
+    })();
+};
+exports.durationFlag = durationFlag;
+const validate = (input, config) => {
+    const { min, max, unit } = config || {};
+    let parsedInput;
+    try {
+        parsedInput = parseInt(input, 10);
+        if (typeof parsedInput !== 'number' || isNaN(parsedInput)) {
+            throw messages.createError('errors.InvalidDuration');
+        }
+    }
+    catch (e) {
+        throw messages.createError('errors.InvalidDuration');
+    }
+    if (min && parsedInput < min) {
+        throw messages.createError('errors.DurationBounds', [min, max]);
+    }
+    if (max && parsedInput > max) {
+        throw messages.createError('errors.DurationBounds', [min, max]);
+    }
+    return toDuration(parsedInput, unit);
+};
+const toDuration = (parsedInput, unit) => {
+    return kit_1.Duration[unit](parsedInput);
+};
+//# sourceMappingURL=duration.js.map

package/lib/flags/orgApiVersion.d.ts

@@ -0,0 +1,13 @@
+export declare const minValidApiVersion = 21;
+export declare const maxDeprecated = 30;
+export declare const maxDeprecatedUrl = "https://help.salesforce.com/s/articleView?id=000354473&type=1;";
+/**
+ * apiVersion for a salesforce org's rest api.
+ * Will validate format and that the api version is still supported.
+ * Will default to the version specified in Config, if it exists (and will provide an override warning)
+ *
+ * CAVEAT: unlike the apiversion flag on sfdxCommand, this does not set the version on the org/connection
+ * We leave this up to the plugins to implement
+ */
+export declare const orgApiVersionFlag: import("@oclif/core/lib/interfaces").Definition<string>;
+//# sourceMappingURL=orgApiVersion.d.ts.map

package/lib/flags/orgApiVersion.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orgApiVersionFlag = exports.maxDeprecatedUrl = exports.maxDeprecated = exports.minValidApiVersion = void 0;
+/*
+ * Copyright (c) 2020, 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
+ */
+const core_1 = require("@oclif/core");
+const core_2 = require("@salesforce/core");
+core_2.Messages.importMessagesDirectory(__dirname);
+const messages = core_2.Messages.loadMessages('@salesforce/sf-plugins-core', 'messages');
+// versions below this are retired
+exports.minValidApiVersion = 21;
+// this and all un-retired versions below it are deprecated
+exports.maxDeprecated = 30;
+exports.maxDeprecatedUrl = 'https://help.salesforce.com/s/articleView?id=000354473&type=1;';
+/**
+ * apiVersion for a salesforce org's rest api.
+ * Will validate format and that the api version is still supported.
+ * Will default to the version specified in Config, if it exists (and will provide an override warning)
+ *
+ * CAVEAT: unlike the apiversion flag on sfdxCommand, this does not set the version on the org/connection
+ * We leave this up to the plugins to implement
+ */
+exports.orgApiVersionFlag = core_1.Flags.build({
+    parse: async (input) => validate(input),
+    default: async () => await getDefaultFromConfig(),
+    description: messages.getMessage('flags.apiVersion.description'),
+});
+const getDefaultFromConfig = async () => {
+    var _a;
+    // (perf) only import ConfigAggregator if necessary
+    const { ConfigAggregator } = await Promise.resolve().then(() => require('@salesforce/core'));
+    const config = await ConfigAggregator.create();
+    const apiVersionFromConfig = (_a = config.getInfo('apiVersion')) === null || _a === void 0 ? void 0 : _a.value;
+    if (apiVersionFromConfig) {
+        await core_2.Lifecycle.getInstance().emitWarning(messages.getMessage('flags.apiVersion.overrideWarning', [apiVersionFromConfig]));
+        return validate(apiVersionFromConfig);
+    }
+};
+const validate = async (input) => {
+    // basic format check
+    if (!core_2.sfdc.validateApiVersion(input)) {
+        throw messages.createError('errors.InvalidApiVersion', [input]);
+    }
+    const requestedVersion = parseInt(input, 10);
+    if (requestedVersion < exports.minValidApiVersion) {
+        throw messages.createError('errors.RetiredApiVersion', [exports.minValidApiVersion]);
+    }
+    if (requestedVersion <= exports.maxDeprecated) {
+        await core_2.Lifecycle.getInstance().emitWarning(messages.getMessage('flags.apiVersion.warning.deprecated', [exports.maxDeprecated, exports.maxDeprecatedUrl]));
+    }
+    return input;
+};
+//# sourceMappingURL=orgApiVersion.js.map

package/lib/flags/orgFlags.d.ts

@@ -0,0 +1,60 @@
+import { Org } from '@salesforce/core';
+/**
+ * An optional org specified by username or alias
+ * Will default to the default org if one is not specified.
+ * Will not throw if the specified org and default do not exist
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': Flags.optionalOrg(),
+ *    // adding properties
+ *    'flag2': Flags.optionalOrg({
+ *        required: true,
+ *        description: 'flag2 description',
+ *     }),
+ * }
+ */
+export declare const optionalOrgFlag: import("@oclif/core/lib/interfaces").Definition<Org | undefined>;
+/**
+ * An required org, specified by username or alias
+ * Will throw if the specified org default do not exist
+ * Will default to the default org if one is not specified.
+ * Will throw if no default org exists and none is specified
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': Flags.requiredOrg(),
+ *    // adding properties
+ *    'flag2': Flags.requiredOrg({
+ *        required: true,
+ *        description: 'flag2 description',
+ *        char: 'o'
+ *     }),
+ * }
+ */
+export declare const requiredOrgFlag: import("@oclif/core/lib/interfaces").Definition<Org>;
+/**
+ * An required org that is a devHub
+ * Will throw if the specified org does not exist
+ * Will default to the default dev hub if one is not specified
+ * Will throw if no default deb hub exists and none is specified
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': requiredHub(),
+ *    // adding properties
+ *    'flag2': requiredHub({
+ *        required: true,
+ *        description: 'flag2 description',
+ *        char: 'h'
+ *     }),
+ * }
+ */
+export declare const requiredHubFlag: import("@oclif/core/lib/interfaces").Definition<Org>;
+//# sourceMappingURL=orgFlags.d.ts.map

package/lib/flags/orgFlags.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requiredHubFlag = exports.requiredOrgFlag = exports.optionalOrgFlag = void 0;
+/*
+ * Copyright (c) 2020, 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
+ */
+const core_1 = require("@oclif/core");
+const core_2 = require("@salesforce/core");
+core_2.Messages.importMessagesDirectory(__dirname);
+const messages = core_2.Messages.loadMessages('@salesforce/sf-plugins-core', 'messages');
+const maybeGetOrg = async (input) => core_2.Org.create({ aliasOrUsername: input });
+const getOrgOrThrow = async (input) => {
+    const org = await maybeGetOrg(input);
+    if (!org) {
+        throw messages.createError('errors.NoDefaultEnv');
+    }
+    return org;
+};
+const getHubOrThrow = async (aliasOrUsername) => {
+    var _a, _b, _c;
+    if (!aliasOrUsername) {
+        // check config for a default
+        const config = await core_2.ConfigAggregator.create();
+        aliasOrUsername =
+            (_b = (_a = config.getInfo('target-dev-hub')) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : (_c = config.getInfo('defaultdevhubusername')) === null || _c === void 0 ? void 0 : _c.value;
+        if (!aliasOrUsername) {
+            throw messages.createError('errors.NoDefaultDevHub');
+        }
+    }
+    const org = await core_2.Org.create({ aliasOrUsername });
+    // check the synchronous, cached version and only use "determine" if we didn't get a positive result
+    if (!org.isDevHubOrg() || !(await org.determineIfDevHubOrg())) {
+        throw messages.createError('errors.NotADevHub', [aliasOrUsername]);
+    }
+    return org;
+};
+/**
+ * An optional org specified by username or alias
+ * Will default to the default org if one is not specified.
+ * Will not throw if the specified org and default do not exist
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': Flags.optionalOrg(),
+ *    // adding properties
+ *    'flag2': Flags.optionalOrg({
+ *        required: true,
+ *        description: 'flag2 description',
+ *     }),
+ * }
+ */
+exports.optionalOrgFlag = core_1.Flags.build({
+    char: 'e',
+    parse: async (input) => await maybeGetOrg(input),
+    default: async () => await maybeGetOrg(),
+});
+/**
+ * An required org, specified by username or alias
+ * Will throw if the specified org default do not exist
+ * Will default to the default org if one is not specified.
+ * Will throw if no default org exists and none is specified
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': Flags.requiredOrg(),
+ *    // adding properties
+ *    'flag2': Flags.requiredOrg({
+ *        required: true,
+ *        description: 'flag2 description',
+ *        char: 'o'
+ *     }),
+ * }
+ */
+exports.requiredOrgFlag = core_1.Flags.build({
+    char: 'e',
+    parse: async (input) => await getOrgOrThrow(input),
+    default: async () => await getOrgOrThrow(undefined),
+});
+/**
+ * An required org that is a devHub
+ * Will throw if the specified org does not exist
+ * Will default to the default dev hub if one is not specified
+ * Will throw if no default deb hub exists and none is specified
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // setting length or prefix
+ *    'target-org': requiredHub(),
+ *    // adding properties
+ *    'flag2': requiredHub({
+ *        required: true,
+ *        description: 'flag2 description',
+ *        char: 'h'
+ *     }),
+ * }
+ */
+exports.requiredHubFlag = core_1.Flags.build({
+    char: 'v',
+    parse: async (input) => await getHubOrThrow(input),
+    default: async () => await getHubOrThrow(undefined),
+});
+//# sourceMappingURL=orgFlags.js.map

package/lib/flags/salesforceId.d.ts

@@ -0,0 +1,32 @@
+import { Interfaces } from '@oclif/core';
+export interface IdFlagConfig extends Partial<Interfaces.OptionFlagProps> {
+    /**
+     * Can specify if the version must be 15 or 18 characters long.  Leave blank to allow either 15 or 18.
+     */
+    length?: 15 | 18;
+    /**
+     * If the ID belongs to a certain sobject type, specify the 3 character prefix.
+     */
+    startsWith?: string;
+}
+/**
+ * Id flag with built-in validation.  Short character is `i`
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // set length or prefix
+ *    'flag-name': salesforceId({ length: 15, startsWith: '00D' }),
+ *    // add flag properties
+ *    'flag2': salesforceId({
+ *        required: true,
+ *        description: 'flag2 description',
+ *     }),
+ *    // override the character i
+ *    'flag3': salesforceId({
+ *        char: 'j',
+ *     }),
+ * }
+ */
+export declare const salesforceIdFlag: (inputs?: IdFlagConfig) => Interfaces.OptionFlag<string | undefined>;
+//# sourceMappingURL=salesforceId.d.ts.map

package/lib/flags/salesforceId.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.salesforceIdFlag = void 0;
+/*
+ * Copyright (c) 2020, 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
+ */
+const core_1 = require("@oclif/core");
+const core_2 = require("@salesforce/core");
+core_2.Messages.importMessagesDirectory(__dirname);
+const messages = core_2.Messages.loadMessages('@salesforce/sf-plugins-core', 'messages');
+/**
+ * Id flag with built-in validation.  Short character is `i`
+ *
+ * @example
+ * import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+ * public static flags = {
+ *     // set length or prefix
+ *    'flag-name': salesforceId({ length: 15, startsWith: '00D' }),
+ *    // add flag properties
+ *    'flag2': salesforceId({
+ *        required: true,
+ *        description: 'flag2 description',
+ *     }),
+ *    // override the character i
+ *    'flag3': salesforceId({
+ *        char: 'j',
+ *     }),
+ * }
+ */
+const salesforceIdFlag = (inputs = {}) => {
+    const { length, startsWith, ...baseProps } = inputs;
+    return core_1.Flags.build({
+        char: 'i',
+        ...baseProps,
+        parse: async (input) => validate(input, { length, startsWith }),
+    })();
+};
+exports.salesforceIdFlag = salesforceIdFlag;
+const validate = (input, config) => {
+    const { length, startsWith } = config || {};
+    if (length && input.length !== length) {
+        throw messages.createError('errors.InvalidIdLength', [length]);
+    }
+    if (!length && ![15, 18].includes(input.length)) {
+        throw messages.createError('errors.InvalidIdLength', ['15 or 18']);
+    }
+    if (!core_2.sfdc.validateSalesforceId(input)) {
+        throw messages.createError('errors.InvalidId');
+    }
+    if (startsWith && !input.startsWith(startsWith)) {
+        throw messages.createError('errors.InvalidPrefix', [startsWith]);
+    }
+    return input;
+};
+//# sourceMappingURL=salesforceId.js.map

package/lib/hooks.d.ts

@@ -28,3 +28,4 @@ export declare namespace SfHook {
     type Logout = Hook<'sf:logout', SfHooks>;
 }
 export {};
+//# sourceMappingURL=hooks.d.ts.map

package/lib/sfCommand.d.ts

@@ -1,4 +1,5 @@
 import { CliUx, Command, Config, HelpSection, Interfaces } from '@oclif/core';
+import { SfdxProject } from '@salesforce/core';
 import { AnyJson } from '@salesforce/ts-types';
 import { Progress, Prompter, Spinner, Ux } from './ux';
 export interface SfCommandInterface extends Interfaces.Command {
@@ -20,11 +21,15 @@ export declare abstract class SfCommand<T> extends Command {
     static envVariablesSection?: HelpSection;
     static errorCodes?: HelpSection;
     static tableFlags: typeof CliUx.Table.table.flags;
+    static requiresProject: boolean;
     spinner: Spinner;
     progress: Progress;
+    project: SfdxProject;
     private warnings;
     private ux;
     private prompter;
+    private lifecycle;
+    protected get statics(): typeof SfCommand;
     constructor(argv: string[], config: Config);
     /**
      * Log warning to users. If --json is enabled, then the warning
@@ -66,6 +71,7 @@ export declare abstract class SfCommand<T> extends Command {
      * }
      */
     prompt<R = Prompter.Answers>(questions: Prompter.Questions<R>, initialAnswers?: Partial<R>): Promise<R>;
+    _run<R>(): Promise<R | undefined>;
     /**
      * Wrap the command result into the standardized JSON structure.
      */
@@ -74,6 +80,7 @@ export declare abstract class SfCommand<T> extends Command {
      * Wrap the command error into the standardized JSON structure.
      */
     protected toErrorJson(error: Error): SfCommand.Error;
+    protected assignProject(): Promise<SfdxProject>;
     abstract run(): Promise<T>;
 }
 export declare namespace SfCommand {
@@ -91,3 +98,4 @@ export declare namespace SfCommand {
         warnings?: Warning[];
     }
 }
+//# sourceMappingURL=sfCommand.d.ts.map

package/lib/sfCommand.js

@@ -29,6 +29,10 @@ class SfCommand extends core_1.Command {
         this.progress = new ux_1.Progress(outputEnabled);
         this.ux = new ux_1.Ux(outputEnabled);
         this.prompter = new ux_1.Prompter();
+        this.lifecycle = core_2.Lifecycle.getInstance();
+    }
+    get statics() {
+        return this.constructor;
     }
     /**
      * Log warning to users. If --json is enabled, then the warning
@@ -87,6 +91,15 @@ class SfCommand extends core_1.Command {
     async prompt(questions, initialAnswers) {
         return this.prompter.prompt(questions, initialAnswers);
     }
+    async _run() {
+        if (this.statics.requiresProject) {
+            this.project = await this.assignProject();
+        }
+        this.lifecycle.onWarning(async (warning) => {
+            this.warn(warning);
+        });
+        return super._run();
+    }
     /**
      * Wrap the command result into the standardized JSON structure.
      */
@@ -111,6 +124,17 @@ class SfCommand extends core_1.Command {
             warnings: this.warnings,
         };
     }
+    async assignProject() {
+        try {
+            return await core_2.SfdxProject.resolve();
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'InvalidProjectWorkspaceError') {
+                throw messages.createError('errors.RequiresProject');
+            }
+            throw err;
+        }
+    }
 }
 exports.SfCommand = SfCommand;
 SfCommand.enableJsonFlag = true;

package/lib/types/index.d.ts

@@ -111,3 +111,4 @@ export declare namespace Logout {
         return: T;
     };
 }
+//# sourceMappingURL=index.d.ts.map

package/lib/util.d.ts

@@ -1,5 +1,11 @@
-import { HelpSection } from '@oclif/core';
-import { OrgConfigProperties, SfdxPropertyKeys, EnvironmentVariable } from '@salesforce/core';
+import { EnvironmentVariable, OrgConfigProperties, SfdxPropertyKeys } from '@salesforce/core';
+export declare type HelpSection = {
+    header: string;
+    body: Array<{
+        name: string;
+        description: string;
+    } | undefined>;
+};
 /**
  * Function to build a help section for command help.
  * Takes a string to be used as section header text and an array of enums
@@ -9,4 +15,5 @@ import { OrgConfigProperties, SfdxPropertyKeys, EnvironmentVariable } from '@sal
  * @param header
  * @param vars
  */
-export declare function toHelpSection(header: string, ...vars: Array<OrgConfigProperties | SfdxPropertyKeys | EnvironmentVariable>): HelpSection;
+export declare function toHelpSection(header: string, ...vars: Array<OrgConfigProperties | SfdxPropertyKeys | EnvironmentVariable | string>): HelpSection;
+//# sourceMappingURL=util.d.ts.map

package/lib/ux/base.d.ts

@@ -4,3 +4,4 @@ export declare class UxBase {
     constructor(outputEnabled: boolean);
     protected maybeNoop(fn: AnyFunction<unknown>): void;
 }
+//# sourceMappingURL=base.d.ts.map

package/lib/ux/index.d.ts

@@ -3,3 +3,4 @@ export { Ux } from './ux';
 export { Progress } from './progress';
 export { Prompter, generateTableChoices } from './prompter';
 export { Spinner } from './spinner';
+//# sourceMappingURL=index.d.ts.map

package/lib/ux/progress.d.ts

@@ -46,3 +46,4 @@ export declare namespace Progress {
     };
     type Payload = Record<string, unknown>;
 }
+//# sourceMappingURL=progress.d.ts.map

package/lib/ux/prompter.d.ts

@@ -20,3 +20,4 @@ export declare namespace Prompter {
  * generateTableChoices(columns, options);
  */
 export declare function generateTableChoices<T>(columns: Dictionary<string>, choices: Array<Dictionary<Nullable<string> | T>>, padForCheckbox?: boolean): ChoiceBase[];
+//# sourceMappingURL=prompter.d.ts.map

package/lib/ux/spinner.d.ts

@@ -28,3 +28,4 @@ export declare class Spinner extends UxBase {
      */
     pause(fn: () => unknown, icon?: string): void;
 }
+//# sourceMappingURL=spinner.d.ts.map

package/lib/ux/ux.d.ts

@@ -15,3 +15,4 @@ export declare namespace Ux {
         type Options = CliUx.Table.table.Options;
     }
 }
+//# sourceMappingURL=ux.d.ts.map

package/messages/messages.md

@@ -1,3 +1,59 @@
 # warning.security
 
-This command will expose sensitive information that allows for subsequent activity using your current authenticated session. Sharing this information is equivalent to logging someone in under the current credential, resulting in unintended access and escalation of privilege. For additional information, please review the authorization section of the https://developer.salesforce.com/docs/atlas.en-us.234.0.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_web_flow.htm
+This command will expose sensitive information that allows for subsequent activity using your current authenticated session. Sharing this information is equivalent to logging someone in under the current credential, resulting in unintended access and escalation of privilege. For additional information, please review the authorization section of the <https://developer.salesforce.com/docs/atlas.en-us.234.0.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_web_flow.htm>
+
+# errors.RequiresProject
+
+This command is required to run from within a Salesforce project directory.
+
+# errors.InvalidIdLength
+
+The id must be %s characters.
+
+# errors.InvalidId
+
+The id is invalid.
+
+# errors.InvalidPrefix
+
+The id must begin with %s.
+
+# errors.NoDefaultEnv
+
+No default environment found. Use -e or --target-org to specify an environment.
+
+# errors.NoDefaultDevHub
+
+No default dev hub found. Use -v or --target-dev-hub to specify an environment.
+
+# errors.NotADevHub
+
+The specified org %s is not a Dev Hub.
+
+# flags.apiVersion.description
+
+Override the api version used for api requests made by this command
+
+# flags.apiVersion.overrideWarning
+
+apiVersion configuration overridden at %s
+
+# flags.apiVersion.warning.deprecated
+
+API versions up to %s are deprecated. See %s for more information.
+
+# errors.InvalidApiVersion
+
+%s is not a valid API version.
+
+# errors.RetiredApiVersion
+
+The API version must be greater than %s.
+
+# errors.InvalidDuration
+
+The value must be an integer.
+
+# errors.DurationBounds
+
+The value must be between %s and %s (inclusive).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sf-plugins-core",
-  "version": "1.2.1",
+  "version": "1.4.1",
   "description": "Utils for writing deploy and retrieve plugins",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -32,8 +32,8 @@
     "/messages"
   ],
   "dependencies": {
-    "@oclif/core": "^1.2.0",
-    "@salesforce/core": "3.7.3",
+    "@oclif/core": "^1.5.0",
+    "@salesforce/core": "^3.7.7",
     "@salesforce/kit": "^1.5.17",
     "@salesforce/ts-types": "^1.5.20",
     "inquirer": "^8.2.0"