Extensibility: Package hooks and addons plugins

[Draft]

Intro

The goal is to provide a system that allows arbitrary packages (in an Ignite UI CLI project or potentially globally installed) to provide extended functionality - be it to run setup scripts of their own logic on install/update or simply to allow to extend the CLI with additional templates and in the process also allow our existing templates to be split into multiple packages and made optional if we so choose.

Detection of participating packages

In order to run the extended functionality provided by external packages, the CLI needs to be aware of them in the first place.

Options:

• Automatic via keyword in tags (Ember-stye) or custom property in package.json. Should be used with caution despite the convenience, as it can become costly depending on the amount of packages and the scanning nature.
• Manual package inclusion in two flavors:
  • Using the package name in the command as positional arg (i.e. update <package>) or through parameter (--option).
  • Config listing of recognized packages (graceful failure if not found)

Likely sticking with the second option as much as possible, as it's a bit more clear being explicit and removes the need of scanning for patterns. It should also be fairly easy for example to pre-configure our own template packages for loading in the future, reducing config friction to a minimum.

Extensibility points

Initial list of extensibility points, leaving open for future additions.

Update migrations

Specialized form of hook logic with multiple entry points per version. Each separate entry point could still rely on a common interface if any. Entry points are to be described in a collection and associated with a version.

// TODO: Separate wiki for ig update

Command ig update:

1. Read current versions (from actual installed) of package dependencies listed package.json)
2. Get metadata from npm API services
3. Check for Ignite CLI property and compare version
4. List available for update

Command ig update <package>[@<version>]:

Ideally maintain as close API as possible with existing package manager commands like npm i/update.

Upon execution the CLI should make note of the current version of the target package in the project. If specified with a range - then resolve the actually installed one (preferably from actual install to be on the safe side). While with packages following semver we might be able to just use the range for comparisons, for compatibility we should just always resolve the actual version anyway.

• Clean node_modules before starting install (?)
• Consider updating the latest version of the CLI to perform the update if updated packages rely on newer features (P1)(?)

Then it should install the newer version (either left default to latest tag or as specified). Once the updated package is installed look for the following field in the package.json:

{
  "name": "<package-name>",
  "version": "1.0.0",
  ...
  "igMigrations": "path/to/migrations.json"
  OR
  "igCLI": {
    "migrations": "path/to/migrations.json"
  }
}

From this migration list look for versions greater than the previously installed (likely using semver's lt/gt comparisons) and execute each in order.

Expectation is for the migration to have default export function to be run from the CLI (with await to allow for async hooks). The external functions should be executed in an isolated try-catch block to avoid halting the entire process if they throw and also to be able to do error logging.

Should also consider providing the CLI file system facade to the package hooks - either to limit the reach of hook logic to the project itself (though that can't really guarantee safety with Node modules's access) or more feasibly if we decide to track file modification and/or compound changes in a virtual FS cache for speed. At the very least the interface will allow us to change that seamlessly.

Note: In Angular projects the update command can simply be a proxy for upgrade

Requirements

Give adequate feedback on operations performed:

• Updated package <X> to <version>
• Executing migration logic for <version>
• Error log in case the execution fails
• Verbose logging of each operation for tracing needs (P1)
• Migrate-only option (P1)

Could also add a safety check in the form of confirmation (w/ potential guidance) before actually executing the migration.

Template packages (P2)

Split the existing platform templates into separate packages as those carry a lot of the bulk of the CLI package atm. Could configure those in the CLI config as pre-recognized template sources so the experience with them installed can remain virtually the same. Could also offer (upon first run of ig/ig-new) the option for the user to choose additional template packages to install from the list if they are not already.

General Requirements

• Project created OR new project being created with Ignite UI CLI
• Clean git state (if git is initialized).
• Nicety: a dry run, though with git predominantly active on projects (or alternative SC), it has less of a value.

Considerations

• To consider potentially useful API to expose through the cli-core package or a separate dev kit package in order to make the development of package hooks easier. At the very least the interfaces for the FS and a JSON schema for config files would be nice.