@lifterlms/dev v0.2.2

LifterLMS Dev CLI

A command-line interface (CLI) for LifterLMS contributors and maintainers. This packages provides a reusable set of tools to reduce redundant dev tasks and chores such as release publication, changelog maintenance, pot file generation, and etc...

CHANGELOG

CHANGELOG

Installation

npm install --save-dev @lifterlms/dev`

Setup

This packages offers a command-line interfaces and exposes the llms-dev binary. It is recommended to add a shorthand script to access the binary by adding a new script to your package.json file:

{
  "scripts": {
    "dev": "llms-dev"
  }
}

After adding this you may access any of the CLI's commands by running:

npm run dev <command> [options...]

Available Commands and Usage

List available commands by running: llms-dev help.

Get help with a specific command by running: llms-dev help [command].

changelog add

Usage: index changelog add [options]

Create a new changelog entry.

Options:
  -s, --significance <level>     The semantic version significance of the
                                 change. Accepts: major, minor, patch.
                                 (default: "patch")
  -t, --type <type>              The type of change. Accepts: added, changed,
                                 fixed, deprecated, removed, dev, performance,
                                 security. (default: "changed")
  -c, --comment <comment>        An internal-use comment to include with the
                                 changelog entry which is not published with
                                 the final changelog.
  -l, --links <issues...>        Link the changelog to one or more GitHub
                                 issues. Can be provided multiple times to link
                                 to multiple issues.
  -a, --attributions <users...>  Attribute the changelog entry to one or more
                                 individuals. Attributions are provided to
                                 thank contributions which originate from
                                 outside the LifterLMS organization. Provide a
                                 GitHub username or a markdown-formatted
                                 anchor. Can be provided multiple times to
                                 attribute to multiple users.
  -e, --entry <entry>            The changelog entry.
  -T, --title <title>            Changelog entry file name. Uses the current
                                 git branch name as the default. Automatically
                                 appends a number to the title if the title
                                 already exists. (default: "trunk")
  -i, --interactive              Create the changelog interactively. (default:
                                 false)
  -E, --use-editor               When creating a changelog interactively, will
                                 open an editor to write the entry, This is
                                 useful when creating multi-line entries.
  -d, --dir <directory>          Directory where changelog entries are stored.
                                 (default: ".changelogs")
  -h, --help                     display help for command

changelog list

Usage: index changelog list [options]

List existing changelog entries.

Options:
  -d, --dir <directory>  Directory where changelog entries are stored.
                         (default: ".changelogs")
  -h, --help             display help for command

changelog validate

Usage: index changelog validate [options] [entries...]

Validate existing changelog entries.

Arguments:
  entries                Optionally specify a list of changelog entries to
                         validate. If omitted will validate all existing
                         entries.

Options:
  -f, --format [format]  Output format. Accepts: list, json, yaml. (default:
                         "list")
  -s, --silent           Skip validation output and communicate validation
                         status only through the exit status of the command.
  -d, --dir <directory>  Directory where changelog entries are stored.
                         (default: ".changelogs")
  -h, --help             display help for command

changelog version

Usage: index changelog version [options] <which>

List existing changelog entries.

Arguments:
  which                     Which version to retrieve. Accepts: current, next.

Options:
  -p, --preid <identifier>  Identifier to be used to prefix premajor, preminor,
                            prepatch or prerelease version increments.
  -d, --dir <directory>     Directory where changelog entries are stored.
                            (default: ".changelogs")
  -h, --help                display help for command

changelog write

Usage: index changelog write [options]

Write existing changelog entries to the changelog file.

Options:
  -p, --preid <identifier>  Identifier to be used to prefix premajor, preminor,
                            prepatch or prerelease version increments.
  -F, --force <version>     Use the specified version string instead of
                            determining the version based on changelog entry
                            significance.
  -l, --log-file <file>     The changelog file. (default: "CHANGELOG.md")
  -d, --date <YYYY-MM-DD>   Changelog publication date. (default: "2022-08-11")
  -L, --links               Add GitHub links to templates and issues in
                            changelog entries. (default: false)
  -n, --no-links            Do not add GitHub links in changelog entries. Use
                            this option to override the --links flag.
  -D, --dry-run             Output what would be written to the changelog
                            instead of writing it to the changelog file.
  -k, --keep-entries        Preserve entry files deletion after the changelog
                            is written.
  -d, --dir <directory>     Directory where changelog entries are stored.
                            (default: ".changelogs")
  -h, --help                display help for command

docgen

Usage: index docgen [options]

Generates documentation for the CLI.

Options:
  -h, --help  display help for command

meta parse

Usage: index meta parse [options]

Retrieves metadata from the project's main file.

Options:
  -F, --file <file>      Main project file name. (default: "dev.php")
  -k, --key <key>        Retrieves a single metadata by key name.
  -f, --format [format]  Output format. Accepts: table, json, yaml. (default:
                         "table")
  -h, --help             display help for command

pot

Usage: index pot [options]

Generate i18n pot and json files using the WP-CLI.

Options:
  -d, --text-domain <text-domain>  Specify the text domain. Used to generate
                                   the filenames for generated files. (default:
                                   "dev")
  -e, --exclude <glob...>          Specify files to exclude from scanning.
                                   (default: "vendor/**, node_modules/**,
                                   tmp/**, dist/**, docs/**, src/**, tests/**,
                                   *.js.map")
  -ee, --extra-exclude <glob...>   Additional files to add to the --exclude
                                   option.
  -d, --dir <directory>            Output directory where generated files will
                                   be stored. (default: "i18n")
  -t, --translator <translator>    Customize the Last Translator header.
                                   (default: "Team LifterLMS
                                   <team@lifterlms.com>")
  -b, --bugs <url>                 Customize the bug report location header.
                                   (default:
                                   "https://lifterlms.com/my-account/my-tickets")
  -h, --help                       display help for command

readme

Usage: index readme [options]

Create a readme.txt file suitable for the WordPress.org plugin repository.

Options:
  -o, --output-file <filename>     Specify the output readme file name.
                                   (default: "readme.txt")
  -i, --input-file <filename>      Specify the input changelog file name.
                                   (default: "CHANGELOG.md")
  -m, --main-file <filename>       Specify the project main file name where
                                   metadata is stored. (default: "dev.php")
  -d, --dir <directory>            Directory where the readme part files are
                                   stored (default: ".wordpress-org/readme")
  -l, --changelog-length <number>  Specify the number of versions to display
                                   before truncating the changelog. (default:
                                   10)
  -r, --read-more <url>            Specify the "Read More" url where changelogs
                                   are published. (default:
                                   "https://make.lifterlms.com/tag/dev")
  -h, --help                       display help for command

Merge codes:
  The following merge codes can be used in any of the readme part markdown files.

  | Merge Code                    | Description                                                            | Source       |
  | ----------------------------- | -----------------------------------------------------------------------| ------------ |
  | {{__CHANGELOG_ENTRIES__}}     | The most recent 10 changelog entries.                                  | --input-file |
  | {{__LICENSE__}}               | The project's license (GPLv3).                                         | --main-file  |
  | {{__LICENSE_URI__}}           | The URI to the project's license.                                      | --main-file  |
  | {{__MIN_WP_VERSION__}}        | The minimum required WordPress core version.                           | --main-file  |
  | {{__MIN_LLMS_VERSION__}}      | The minimum required LifterLMS version.                                | --main-file  |
  | {{__MIN_PHP_VERSION__}}       | The minimum required PHP version.                                      | --main-file  |
  | {{__PROJECT_URI__}}           | The project's URI.                                                     | --main-file  |
  | {{__READ_MORE_LINK__}}        | A link to the full project changelog.                                  | --main-file  |
  | {{__SHORT_DESCRIPTION__}}     | A short description of the project.                                    | --main-file  |
  | {{__TESTED_LLMS_VERSION__}}   | The latest LifterLMS version the project has been tested against.      | --main-file  |
  | {{__TESTED_WP_VERSION__}}     | The latest WordPress core version the project has been tested against. | --main-file  |
  | {{__VERSION__}}               | The current project version.                                           | package.json |
	

release archive

Usage: index release archive [options]

Build a distribution archive (.zip) file for the project.

Options:
  -i, --inspect    Automatically unzip the zip file after creation. (default:
                   false)
  -d, --dir <dir>  Directory where the generated archive file will be saved,
                   relative to the project root directory. (default: "dist")
  -v, --verbose    Output extra information with result messages. (default:
                   false)
  -h, --help       display help for command

release create

Usage: index release create [options]

Create a GitHub release and tag from a specified file or branch.

Options:
  -a, --archive <zip>               If specified, the zip file will be
                                    committed and force-pushed to the specified
                                    branch before creating the release. Pass
                                    --no-archive to skip this step. (default:
                                    "dev-0.0.5.zip")
  -A, --no-archive                  Skip creation from an archive file and use
                                    the target --branch for release creation.
  -c, --commit-message <message>    Customize the commit message used when
                                    pushing to the target branch. Used only
                                    when releasing from an archive. The
                                    placeholder "%s" is replaced with the
                                    release version. (default: "Release v%s [ci
                                    skip]")
  -d, --dir <directory>             Directory where distribution files are
                                    stored. (default: "dist")
  -b, --branch <branch>             Target branch to use when creating the
                                    release. (default: "release")
  -l, --logfile <file>              Specify the changelog file. (default:
                                    "CHANGELOG.md")
  -p, --prerelease                  Mark the GitHub release as a prerelease and
                                    skip merging.
  -P, --prerelease-branch <branch>  When creating a prerelease, use this branch
                                    as the target branch in favor of the
                                    default branch specified via the --branch
                                    option. (default: "prerelease")
  -D, --draft                       Create the release as an unpublished draft
                                    and skip merging.
  -M, --merge <branch>              Merge open PRs on the specified branch
                                    before creating the release. If publishing
                                    a prerelease, or draft merging is
                                    automatically disabled as if passing
                                    "--no-merge". (default: "dev")
  -n, --no-merge                    Disable merging before release creation.
                                    Automatically passed when publishing a
                                    prerelease.
  -Y, --yes                         Skip confirmations.
  -v, --verbose                     Output extra information with result
                                    messages.
  -h, --help                        display help for command

release prepare

Usage: index release prepare [options]

Prepare and build a release.

Options:
  -F, --force <version>     Specify a version to use. If not specified uses
                            `changelog version next` to determine the version.
  -p, --preid <identifier>  Identifier to be used to prefix premajor, preminor,
                            prepatch or prerelease version increments.
  -y, --yes                 Specify no-interaction mode. Responds "yes" to all
                            confirmation prompts.
  -b, --build <cmd>         Specify an npm script to use for the build command.
                            (default: "build")
  -B, --no-build            Disabled build script.
  -h, --help                display help for command

update-version

Usage: index update-version [options]

Update the project version and replace all [version] placeholders.

Options:
  -i, --increment <level>                     Increment the version by the specified level. Accepts: major, minor, patch, premajor, preminor, prepatch, or prerelease. (default: "patch")
  -p, --preid <identifier>                    Identifier to be used to prefix premajor, preminor, prepatch or prerelease version increments.
  -F, --force <version>                       Specify an explicit version instead of incrementing the current version with --increment.
  -r, --replacements <replacement...>]        Replacements to be made. Each replacement is an array containing a list of globs for the files to be tested, a regex used to perform the replacement, and an optional list of RegEx flags (defaults to `g` if not supplied). It is recommended that this argument to configured via a configuration file as opposed to being passed via a CLI flag. (default: [["./**","(?<=@(?:since|version|deprecated) +)(\\[version\\])"],["./*.php,./**/*.php","(?<=(?:_deprecated_argument|_deprecated_constructor|_deprecated_hook|_deprecated_file|_deprecated_function|_doing_it_wrong|apply_filters_deprecated|do_action_deprecated|llms_deprecated_function\\().+)(?<=')(\\[version\\])(?=')"],["*lifterlms*.php","(?<=[Vv]ersion *[:=] *[ '\"])(0|[1-9]d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?"],["*lifterlms*.php","(?<=define\\( '(?:LLMS|LIFTERLMS).*_VERSION', ')(.*)(?=' \\);)"],["./style.css","(?<=Version: )(.+)"]])
  -e, --extra-replacements <replacement...>]  Additional replacements added to --replacements array. This option allows adding to the default replacements instead of overwriting them. (default: [])
  -E, --exclude <glob...>                     Specify files to exclude from the update. (default: "./vendor/**, ./node_modules/**, ./tmp/**, ./dist/**, ./docs/**, ./packages/**")
  -s, --skip-config                           Skip updating the version of the package.json or composer.json file. (default: true)
  -h, --help                                  display help for command

Configuration Files

The default values for all command options may be customized by placing a YAML configuration file in the project's root directory name .llmsdev.yml.

The configuration file may contain any number of objects, the top-level keys correspond to the command being configured. The keys of each object represent the long form (eg: --option-name) option flag for the option being configured. When configuring a subcommand, separate the parent and child commands with a dot ..

The following is an annotated configuration example:

# Configure the archive command defaults, eg `llms-dev archive`.
archive:
  # Equivalent to always passing `llms-dev archive --inspect`.
  inspect: true

# Configure the the changelog add command, eg `llms-dev changelog add`
changelog.add
  type: added