oclif 4.7.8 → 4.8.0

package/README.md

@@ -100,11 +100,12 @@ hello world! (./src/commands/hello/world.ts)
 
 - [`oclif generate`](docs/generate.md) - Generate a new CLI
 - [`oclif help`](docs/help.md) - Display help for oclif.
+- [`oclif init`](docs/init.md) - Initialize a new oclif CLI
 - [`oclif manifest`](docs/manifest.md) - Generates plugin manifest json (oclif.manifest.json).
-- [`oclif pack`](docs/pack.md) - package an oclif CLI into installable artifacts
+- [`oclif pack`](docs/pack.md) - Package an oclif CLI into installable artifacts.
 - [`oclif promote`](docs/promote.md) - Promote CLI builds to a S3 release channel.
 - [`oclif readme`](docs/readme.md) - Adds commands to README.md in current directory.
-- [`oclif upload`](docs/upload.md) - upload installable CLI artifacts to AWS S3
+- [`oclif upload`](docs/upload.md) - Upload installable CLI artifacts to AWS S3.
 
 <!-- commandsstop -->
 

package/lib/commands/init.d.ts

@@ -0,0 +1,39 @@
+import { GeneratorCommand } from '../generator';
+export default class Generate extends GeneratorCommand<typeof Generate> {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flaggablePrompts: {
+        bin: {
+            message: string;
+            validate: (d: string) => true | "Invalid bin name";
+        };
+        'module-type': {
+            message: string;
+            options: readonly ["ESM", "CommonJS"];
+            validate: (d: string) => true | "Invalid module type";
+        };
+        'package-manager': {
+            message: string;
+            options: readonly ["npm", "yarn", "pnpm"];
+            validate: (d: string) => true | "Invalid package manager";
+        };
+        'topic-separator': {
+            message: string;
+            options: string[];
+            validate: (d: string) => true | "Invalid topic separator";
+        };
+    };
+    static flags: {
+        'output-dir': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        bin: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        "module-type": import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        "package-manager": import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        "topic-separator": import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+}

package/lib/commands/init.js

@@ -0,0 +1,161 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const generator_1 = require("../generator");
+const util_1 = require("../util");
+const VALID_MODULE_TYPES = ['ESM', 'CommonJS'];
+const VALID_PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm'];
+function isPackageManager(d) {
+    return VALID_PACKAGE_MANAGERS.includes(d);
+}
+function isModuleType(d) {
+    return VALID_MODULE_TYPES.includes(d);
+}
+const FLAGGABLE_PROMPTS = {
+    bin: {
+        message: 'Command bin name the CLI will export',
+        validate: (d) => (0, util_1.validateBin)(d) || 'Invalid bin name',
+    },
+    'module-type': {
+        message: 'Select a module type',
+        options: VALID_MODULE_TYPES,
+        validate: (d) => isModuleType(d) || 'Invalid module type',
+    },
+    'package-manager': {
+        message: 'Select a package manager',
+        options: VALID_PACKAGE_MANAGERS,
+        validate: (d) => isPackageManager(d) || 'Invalid package manager',
+    },
+    'topic-separator': {
+        message: 'Select a topic separator',
+        options: ['colons', 'spaces'],
+        validate: (d) => d === 'colons' || d === 'spaces' || 'Invalid topic separator',
+    },
+};
+class Generate extends generator_1.GeneratorCommand {
+    static description = 'This will add the necessary oclif bin files, add oclif config to package.json, and install @oclif/core and ts-node.';
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %>',
+            description: 'Initialize a new CLI in the current directory',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> --output-dir "/path/to/existing/project"',
+            description: 'Initialize a new CLI in a different directory',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> --topic-separator colons --bin mycli',
+            description: 'Supply answers for specific prompts',
+        },
+    ];
+    static flaggablePrompts = FLAGGABLE_PROMPTS;
+    static flags = {
+        ...(0, generator_1.makeFlags)(FLAGGABLE_PROMPTS),
+        'output-dir': core_1.Flags.directory({
+            char: 'd',
+            description: 'Directory to initialize the CLI in.',
+            exists: true,
+        }),
+        yes: core_1.Flags.boolean({
+            aliases: ['defaults'],
+            char: 'y',
+            description: 'Use defaults for all prompts. Individual flags will override defaults.',
+        }),
+    };
+    static summary = 'Initialize a new oclif CLI';
+    async run() {
+        const outputDir = this.flags['output-dir'] ?? process.cwd();
+        const location = (0, node_path_1.resolve)(outputDir);
+        this.log(`Initializing oclif in ${chalk_1.default.green(location)}`);
+        const packageJSON = (await (0, generator_1.readPJSON)(location));
+        if (!packageJSON) {
+            throw new core_1.Errors.CLIError(`Could not find a package.json file in ${location}`);
+        }
+        const bin = await this.getFlagOrPrompt({
+            defaultValue: location.split(node_path_1.sep).at(-1) || '',
+            name: 'bin',
+            type: 'input',
+        });
+        const topicSeparator = await this.getFlagOrPrompt({
+            defaultValue: 'spaces',
+            name: 'topic-separator',
+            type: 'select',
+        });
+        const moduleType = await this.getFlagOrPrompt({
+            defaultValue: packageJSON.type === 'module' ? 'ESM' : 'CommonJS',
+            async maybeOtherValue() {
+                return packageJSON.type === 'module' ? 'ESM' : packageJSON.type === 'commonjs' ? 'CommonJS' : undefined;
+            },
+            name: 'module-type',
+            type: 'select',
+        });
+        const packageManager = await this.getFlagOrPrompt({
+            defaultValue: 'npm',
+            async maybeOtherValue() {
+                const rootFiles = await (0, promises_1.readdir)(location);
+                if (rootFiles.includes('package-lock.json')) {
+                    return 'npm';
+                }
+                if (rootFiles.includes('yarn.lock')) {
+                    return 'yarn';
+                }
+                if (rootFiles.includes('pnpm-lock.yaml')) {
+                    return 'pnpm';
+                }
+            },
+            name: 'package-manager',
+            type: 'select',
+        });
+        this.log(`Using module type ${chalk_1.default.green(moduleType)}`);
+        this.log(`Using package manager ${chalk_1.default.green(packageManager)}`);
+        const templateOptions = { moduleType };
+        const projectBinPath = (0, node_path_1.join)(location, 'bin');
+        await this.template((0, node_path_1.join)(this.templatesDir, 'src', 'init', 'dev.cmd.ejs'), (0, node_path_1.join)(projectBinPath, 'dev.cmd'), templateOptions);
+        await this.template((0, node_path_1.join)(this.templatesDir, 'src', 'init', 'dev.js.ejs'), (0, node_path_1.join)(projectBinPath, 'dev.js'), templateOptions);
+        await this.template((0, node_path_1.join)(this.templatesDir, 'src', 'init', 'run.cmd.ejs'), (0, node_path_1.join)(projectBinPath, 'run.cmd'), templateOptions);
+        await this.template((0, node_path_1.join)(this.templatesDir, 'src', 'init', 'run.js.ejs'), (0, node_path_1.join)(projectBinPath, 'run.js'), templateOptions);
+        if (process.platform !== 'win32') {
+            await (0, generator_1.exec)(`chmod +x ${(0, node_path_1.join)(projectBinPath, 'run.js')}`);
+            await (0, generator_1.exec)(`chmod +x ${(0, node_path_1.join)(projectBinPath, 'dev.js')}`);
+        }
+        const updatedPackageJSON = {
+            ...packageJSON,
+            bin: {
+                ...packageJSON.bin,
+                [bin]: './bin/run.js',
+            },
+            oclif: {
+                bin,
+                commands: './dist/commands',
+                dirname: bin,
+                topicSeparator: topicSeparator === 'colons' ? ':' : ' ',
+                ...packageJSON.oclif,
+            },
+        };
+        await (0, promises_1.writeFile)((0, node_path_1.join)(location, 'package.json'), JSON.stringify(updatedPackageJSON, null, 2));
+        const installedDeps = Object.keys(packageJSON.dependencies ?? {});
+        if (!installedDeps.includes('@oclif/core')) {
+            this.log('Installing @oclif/core');
+            await (0, generator_1.exec)(`${packageManager} ${packageManager === 'yarn' ? 'add' : 'install'} @oclif/core`, {
+                cwd: location,
+                silent: false,
+            });
+        }
+        const allInstalledDeps = [...installedDeps, ...Object.keys(packageJSON.devDependencies ?? {})];
+        if (!allInstalledDeps.includes('ts-node')) {
+            this.log('Installing ts-node');
+            await (0, generator_1.exec)(`${packageManager} ${packageManager === 'yarn' ? 'add --dev' : 'install --save-dev'} ts-node`, {
+                cwd: location,
+                silent: false,
+            });
+        }
+        this.log(`\nCreated CLI ${chalk_1.default.green(bin)}`);
+    }
+}
+exports.default = Generate;

package/lib/generator.d.ts

@@ -3,12 +3,31 @@ import { Command, Interfaces } from '@oclif/core';
 import { ExecOptions } from 'node:child_process';
 export type FlaggablePrompt = {
     message: string;
-    options?: string[];
+    options?: readonly string[] | string[];
     validate: (d: string) => boolean | string;
 };
 export type FlagsOfPrompts<T extends Record<string, FlaggablePrompt>> = Record<keyof T, Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>>;
 export type Flags<T extends typeof Command> = Interfaces.InferredFlags<(typeof GeneratorCommand)['baseFlags'] & T['flags']>;
 export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
+export type GetFlagOrPromptOptions = {
+    /**
+     * The default value for the prompt if the `--yes` flag is provided.
+     */
+    defaultValue: string;
+    /**
+     * A function that returns a value if the user has not provided the value via the flag. This will rerun before
+     * the check for the `--yes` flag.
+     */
+    maybeOtherValue?: () => Promise<string | undefined>;
+    /**
+     * The name of the flaggable prompt. Corresponds to the key in `this.flags`.
+     */
+    name: string;
+    /**
+     * The type of prompt to display.
+     */
+    type: 'input' | 'select';
+};
 export declare function exec(command: string, opts?: ExecOptions & {
     silent?: boolean;
 }): Promise<{
@@ -24,11 +43,16 @@ export declare abstract class GeneratorCommand<T extends typeof Command> extends
     protected flaggablePrompts: Record<string, FlaggablePrompt>;
     protected flags: Flags<T>;
     templatesDir: string;
-    getFlagOrPrompt({ defaultValue, name, type, }: {
-        defaultValue: string;
-        name: string;
-        type: 'input' | 'select';
-    }): Promise<any>;
+    /**
+     * Get a flag value or prompt the user for a value.
+     *
+     * Resolution order:
+     * - Flag value provided by the user
+     * - Value returned by `maybeOtherValue`
+     * - `defaultValue` if the `--yes` flag is provided
+     * - Prompt the user for a value
+     */
+    getFlagOrPrompt({ defaultValue, maybeOtherValue, name, type }: GetFlagOrPromptOptions): Promise<string>;
     init(): Promise<void>;
     template(source: string, destination: string, data?: Record<string, unknown>): Promise<void>;
 }

package/lib/generator.js

@@ -62,7 +62,16 @@ class GeneratorCommand extends core_1.Command {
     flaggablePrompts;
     flags;
     templatesDir;
-    async getFlagOrPrompt({ defaultValue, name, type, }) {
+    /**
+     * Get a flag value or prompt the user for a value.
+     *
+     * Resolution order:
+     * - Flag value provided by the user
+     * - Value returned by `maybeOtherValue`
+     * - `defaultValue` if the `--yes` flag is provided
+     * - Prompt the user for a value
+     */
+    async getFlagOrPrompt({ defaultValue, maybeOtherValue, name, type }) {
         if (!this.flaggablePrompts)
             throw new Error('No flaggable prompts defined');
         if (!this.flaggablePrompts[name])
@@ -79,9 +88,19 @@ class GeneratorCommand extends core_1.Command {
                 return defaultValue;
             }
         };
+        const checkMaybeOtherValue = async () => {
+            if (!maybeOtherValue)
+                return;
+            const otherValue = await maybeOtherValue();
+            if (otherValue) {
+                this.log(`${chalk_1.default.green('?')} ${chalk_1.default.bold(this.flaggablePrompts[name].message)} ${chalk_1.default.cyan(otherValue)}`);
+                return otherValue;
+            }
+        };
         switch (type) {
             case 'select': {
                 return (maybeFlag() ??
+                    (await checkMaybeOtherValue()) ??
                     maybeDefault() ??
                     // Dynamic import because @inquirer/select is ESM only. Once oclif is ESM, we can make this a normal import
                     // so that we can avoid importing on every single question.
@@ -93,6 +112,7 @@ class GeneratorCommand extends core_1.Command {
             }
             case 'input': {
                 return (maybeFlag() ??
+                    (await checkMaybeOtherValue()) ??
                     maybeDefault() ??
                     // Dynamic import because @inquirer/input is ESM only. Once oclif is ESM, we can make this a normal import
                     // so that we can avoid importing on every single question.

package/oclif.manifest.json

@@ -173,6 +173,127 @@
         "generate.js"
       ]
     },
+    "init": {
+      "aliases": [],
+      "args": {},
+      "description": "This will add the necessary oclif bin files, add oclif config to package.json, and install @oclif/core and ts-node.",
+      "examples": [
+        {
+          "command": "<%= config.bin %> <%= command.id %>",
+          "description": "Initialize a new CLI in the current directory"
+        },
+        {
+          "command": "<%= config.bin %> <%= command.id %> --output-dir \"/path/to/existing/project\"",
+          "description": "Initialize a new CLI in a different directory"
+        },
+        {
+          "command": "<%= config.bin %> <%= command.id %> --topic-separator colons --bin mycli",
+          "description": "Supply answers for specific prompts"
+        }
+      ],
+      "flags": {
+        "bin": {
+          "description": "Supply answer for prompt: Command bin name the CLI will export",
+          "name": "bin",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "module-type": {
+          "description": "Supply answer for prompt: Select a module type",
+          "name": "module-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "ESM",
+            "CommonJS"
+          ],
+          "type": "option"
+        },
+        "package-manager": {
+          "description": "Supply answer for prompt: Select a package manager",
+          "name": "package-manager",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "npm",
+            "yarn",
+            "pnpm"
+          ],
+          "type": "option"
+        },
+        "topic-separator": {
+          "description": "Supply answer for prompt: Select a topic separator",
+          "name": "topic-separator",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "colons",
+            "spaces"
+          ],
+          "type": "option"
+        },
+        "output-dir": {
+          "char": "d",
+          "description": "Directory to initialize the CLI in.",
+          "name": "output-dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "yes": {
+          "aliases": [
+            "defaults"
+          ],
+          "char": "y",
+          "description": "Use defaults for all prompts. Individual flags will override defaults.",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "oclif",
+      "pluginName": "oclif",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Initialize a new oclif CLI",
+      "flaggablePrompts": {
+        "bin": {
+          "message": "Command bin name the CLI will export"
+        },
+        "module-type": {
+          "message": "Select a module type",
+          "options": [
+            "ESM",
+            "CommonJS"
+          ]
+        },
+        "package-manager": {
+          "message": "Select a package manager",
+          "options": [
+            "npm",
+            "yarn",
+            "pnpm"
+          ]
+        },
+        "topic-separator": {
+          "message": "Select a topic separator",
+          "options": [
+            "colons",
+            "spaces"
+          ]
+        }
+      },
+      "isESM": false,
+      "relativePath": [
+        "lib",
+        "commands",
+        "init.js"
+      ]
+    },
     "lock": {
       "aliases": [],
       "args": {},
@@ -911,5 +1032,5 @@
       ]
     }
   },
-  "version": "4.7.8"
+  "version": "4.8.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oclif",
   "description": "oclif: create your own CLI",
-  "version": "4.7.8",
+  "version": "4.8.0",
   "author": "Salesforce",
   "bin": {
     "oclif": "bin/run.js"
@@ -114,10 +114,10 @@
     },
     "topics": {
       "pack": {
-        "description": "package an oclif CLI into installable artifacts"
+        "description": "Package an oclif CLI into installable artifacts."
       },
       "upload": {
-        "description": "upload installable CLI artifacts to AWS S3"
+        "description": "Upload installable CLI artifacts to AWS S3."
       }
     }
   },
@@ -134,6 +134,7 @@
     "prepare": "husky",
     "test:integration:cli": "mocha test/integration/cli.test.ts --timeout 600000",
     "test:integration:deb": "mocha test/integration/deb.test.ts --timeout 900000",
+    "test:integration:init": "mocha test/integration/init.test.ts --timeout 600000",
     "test:integration:macos": "mocha test/integration/macos.test.ts --timeout 900000",
     "test:integration:publish": "mocha test/integration/publish.test.ts --timeout 900000",
     "test:integration:sf": "mocha test/integration/sf.test.ts --timeout 600000",

package/templates/src/init/dev.cmd.ejs

@@ -0,0 +1,12 @@
+<% switch (moduleType) {
+  case 'ESM' : _%>
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*
+          <%_ break;
+  case 'CommonJS' : _%>
+@echo off
+
+node "%~dp0\dev" %*
+          <%_ break;
+  } _%>

package/templates/src/init/dev.js.ejs

@@ -0,0 +1,17 @@
+<% switch (moduleType) {
+  case 'ESM' : _%>
+#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+await execute({development: true, dir: import.meta.url})
+          <%_ break;
+  case 'CommonJS' : _%>
+#!/usr/bin/env node_modules/.bin/ts-node
+
+// eslint-disable-next-line node/shebang, unicorn/prefer-top-level-await
+(async () => {
+  const oclif = await import('@oclif/core')
+  await oclif.execute({development: true, dir: __dirname})
+})()
+          <%_ break;
+  } _%>

package/templates/src/init/run.cmd.ejs

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

package/templates/src/init/run.js.ejs

@@ -0,0 +1,17 @@
+<% switch (moduleType) {
+  case 'ESM' : _%>
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+await execute({dir: import.meta.url})
+          <%_ break;
+  case 'CommonJS' : _%>
+#!/usr/bin/env node
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+(async () => {
+  const oclif = await import('@oclif/core')
+  await oclif.execute({development: false, dir: __dirname})
+})()
+          <%_ break;
+  } _%>