piral-cli 1.0.0-pre.2217 → 1.0.0

package/src/messages.ts

@@ -161,7 +161,7 @@ export function appInstanceNotFound_0010(name: string): QuickMessage {
  * It should be an HTML file.
  *
  * @see
- * - [Parcel HTML Asset](https://parceljs.org/html.html)
+ * - [Parcel HTML Asset](https://parceljs.org/languages/html/)
  *
  * @example
  * Make sure the package.json of the Piral instance is valid (has an "app" field).
@@ -180,6 +180,53 @@ export function appInstanceInvalid_0011(): QuickMessage {
   return [LogLevels.error, '0011', `Could not find a valid Piral instance.`];
 }
 
+/**
+ * @kind Error
+ *
+ * @summary
+ * Reported when no valid Piral instance was specified.
+ *
+ * @abstract
+ * The Piral instance is defined either in the package.json or in the pilet.json.
+ *
+ * The resolution of the Piral instance is done via the `require.resolve` function of Node.js. Thus, if the defined module is simply not yet installed this error will be shown.
+ *
+ * @see
+ * - [npm i](https://docs.npmjs.com/cli/install)
+ * - [npm install is missing modules](https://stackoverflow.com/questions/24652681/npm-install-is-missing-modules)
+ *
+ * @example
+ * Assuming that the available pilet.json of your pilet contains content such as:
+ *
+ * ```json
+ * {
+ *   // ...
+ *   "piralInstances": {
+ *     "my-app-shell": {}
+ *   }
+ * }
+ * ```
+ *
+ * However, running
+ *
+ * ```sh
+ * ls node_modules/my-app-shell
+ * ```
+ *
+ * returns an error.
+ *
+ * To mitigate it try running
+ *
+ * ```sh
+ * npm i
+ * ```
+ *
+ * which will install all dependencies.
+ */
+export function appInstancesNotGiven_0012(): QuickMessage {
+  return [LogLevels.error, '0012', `No Piral instances have been provided.`];
+}
+
 /**
  * @kind Error
  *
@@ -198,7 +245,7 @@ export function appInstanceInvalid_0011(): QuickMessage {
  * project folder has a package.json in its root.
  *
  * @see
- * - [NPM Package Specification](https://docs.npmjs.com/files/package.json)
+ * - [npm Package Specification](https://docs.npmjs.com/files/package.json)
  *
  * @example
  * You can see if you are currently in a correct folder.
@@ -235,7 +282,7 @@ export function packageJsonNotFound_0020(): QuickMessage {
  * The name of the pilet is provided by the name field specified in its package.json.
  *
  * A valid package.json file requires a valid name. The name has to follow standard naming
- * conventions of the NPM system.
+ * conventions of the npm system.
  *
  * @see
  * - [Package Naming Guidelines](https://docs.npmjs.com/package-name-guidelines)
@@ -285,7 +332,7 @@ export function packageJsonMissingName_0021(): QuickMessage {
  * specification.
  *
  * @see
- * - [NPM on Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning)
+ * - [npm on Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning)
  *
  * @example
  * Check the contents of the available package.json:
@@ -330,7 +377,7 @@ export function packageJsonMissingVersion_0022(): QuickMessage {
  * and which ones can remain at their current version.
  *
  * @see
- * - [NPM Install](https://docs.npmjs.com/cli/install)
+ * - [npm Install](https://docs.npmjs.com/cli/install)
  *
  * @example
  * Check that the package is indeed installed:
@@ -370,7 +417,7 @@ export function packageNotInstalled_0023(name: string): QuickMessage {
  * versions. If no release for the given version was found then an error is emitted.
  *
  * @see
- * - [StackOverflow Listing NPM Versions](https://stackoverflow.com/questions/41415945/how-to-list-all-versions-of-an-npm-module)
+ * - [StackOverflow Listing npm Versions](https://stackoverflow.com/questions/41415945/how-to-list-all-versions-of-an-npm-module)
  *
  * @example
  * Check that the version is valid:
@@ -392,6 +439,273 @@ export function packageVersionInvalid_0024(version: string): QuickMessage {
   return [LogLevels.error, '0024', `The given package version "${version}" is invalid.`];
 }
 
+/**
+ * @kind Error
+ *
+ * @summary
+ * Cannot add the shared dependency since its version constraint is not satisfied.
+ *
+ * @abstract
+ * The importmap definition allows you to define a version specifier separated with
+ * the '@' character. If you write down a version specifier then it has to be
+ * fulfilled already from the local version, otherwise the packaged version can
+ * potentially not be resolved at runtime. This would resolve in a pilet that fails
+ * when running in isolation and most likely fails when running with other pilets.
+ *
+ * @see
+ * - [import-maps specification](https://github.com/WICG/import-maps)
+ *
+ * @example
+ * Check the contents of the available package.json:
+ *
+ * ```sh
+ * cat package.json
+ * ```
+ *
+ * The displayed content should look similar to (i.e., contain an importmap such as):
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "foo@^3.2.1": "foo"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * For the error to occur the specifier (^3.2.1) potentially does not match the version (e.g., if
+ * the version of the dependency is 3.1.2).
+ *
+ * One strategy is to remove the specifier, which will automatically use the exact current version
+ * as specifier:
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "foo": "foo"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The best way, however, is to look at the used version and adjust the specifier to be correct again.
+ * Alternatively, change the used version to satisfy the constraint again.
+ */
+export function importMapVersionSpecNotSatisfied_0025(depName: string, version: string): QuickMessage {
+  return [LogLevels.error, '0025', `The dependency "${depName}" in only available in version "${version}".`];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * The version spec part of the importmap identifer is invalid.
+ *
+ * @abstract
+ * The importmap definition allows you to define a version specifier separated with
+ * the '@' character. This part has to follow the semver convention and rules.
+ *
+ * Check your specifier via online tools such as "Semver check" to verify it is
+ * valid and follows the semver specification.
+ *
+ * @see
+ * - [Online Checker](https://jubianchi.github.io/semver-check/)
+ *
+ * @example
+ * Check the contents of the available package.json:
+ *
+ * ```sh
+ * cat package.json
+ * ```
+ *
+ * The displayed content should look similar to (i.e., contain an importmap such as):
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "foo@bar": "foo"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * For the error to occur the specifier (bar) is not following the semver specification.
+ *
+ * One way is to remove the version spec, which will resolve to an exact version specifier
+ * and therefore always works:
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "foo": "foo"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The best way, however, is to look at the used version and adjust the specifier to be correct again,
+ * such as "^1.2.3" or "1.x" or "3" etc.
+ */
+export function importMapVersionSpecInvalid_0026(depName: string): QuickMessage {
+  return [LogLevels.error, '0026', `The dependency "${depName}" has an invalid version spec.`];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * The provided importmap reference could not be resolved.
+ *
+ * @abstract
+ * The importmap consists of keys and values. The keys represent the packages names and optional
+ * version specifiers to demand at runtime. The values represent the entry point or URL to use
+ * when the dependency is not yet loaded.
+ *
+ * In case of a non-URL value the reference has either to be a valid package name or a file path
+ * that leads to either a package or valid JS module. Either way, it needs to exist. If the path
+ * is invalid an error will be emitted.
+ *
+ * @see
+ * - [npm Install](https://docs.npmjs.com/cli/install)
+ *
+ * @example
+ * Check the contents of the available package.json:
+ *
+ * ```sh
+ * cat package.json
+ * ```
+ *
+ * The displayed content should look similar to (i.e., contain an importmap such as):
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "foo@bar": "./node_modules/prect"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Note the potential misspelling. It maybe should have been "./node_modules/preact". In such
+ * cases the reference may not be resolved locally. If everything was written correctly the
+ * node modules are most likely not installed (correctly).
+ */
+export function importMapReferenceNotFound_0027(dir: string, reference: string): QuickMessage {
+  return [
+    LogLevels.error,
+    '0027',
+    `The reference to "${reference}" could not be resolved from "${dir}". Are you sure the file or package exists?`,
+  ];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * The provided importmap file could not be found.
+ *
+ * @abstract
+ * The importmap can be referenced in a file from the package.json. If the named
+ * file cannot be found the build process has to be stopped. Make sure that the
+ * file has been specified relative to the package.json where it was referenced
+ * from.
+ *
+ * @see
+ * - [import-maps specification](https://github.com/WICG/import-maps)
+ *
+ * @example
+ * Check the contents of the available package.json:
+ *
+ * ```sh
+ * cat package.json
+ * ```
+ *
+ * The displayed content should look similar to (i.e., contain an importmap such as):
+ *
+ * ```json
+ * {
+ *   "importmap": "./import-map.json"
+ * }
+ * ```
+ *
+ * If the importmap has instead been (re)named "importmap.json" then this will not work.
+ * Likewise, with the reference above the file is expected to be in the same directory
+ * as the package.json. If it is, e.g., in the "src" subfolder you'd should reference it
+ * as "./src/import-map.json" instead.
+ */
+export function importMapFileNotFound_0028(dir: string, file: string): QuickMessage {
+  return [LogLevels.error, '0028', `The importmap "${file}" could not be found at "${dir}".`];
+}
+
+/**
+ * @kind Warning
+ *
+ * @summary
+ * The given dependency seems to be a Piral plugin and should not be exposed
+ * as a shared dependency.
+ *
+ * @abstract
+ * While you should be quite restrictive in general regarding sharing dependencies,
+ * there are some dependencies that should never be shared. One area are dependencies
+ * that are only meant for the app shell and don't make sense somewhere else.
+ *
+ * Even though many dependencies might exist that fall into that area the only ones
+ * we know for sure are the so-called Piral plugins. These are dependencies that only
+ * make sense to be used within an app shell, i.e., a Piral instance (or host application).
+ *
+ * When the Piral CLI detects that you want to share such a dependency from an app shell,
+ * or alternatively within a pilet directly, it will print a warning. There might be false
+ * positives here, so having an error here might be a bit too much. Nevertheless, depending
+ * on your scenario you might want to treat these warnings as errors.
+ *
+ * @see
+ * - [Sharing dependencies](https://docs.piral.io/concepts/I08-importmap)
+ *
+ * @example
+ * Check the contents of the available package.json:
+ *
+ * ```sh
+ * cat package.json
+ * ```
+ *
+ * The displayed content should look similar to (i.e., contain an importmap such as):
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "piral-ng": ""
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * This would share the whole Piral plugin, which does not make much sense. First of all,
+ * the plugin is presumably already installed - it even could only be installed in a
+ * Piral instance. Second, there is no use of the exported function somewhere else.
+ *
+ * Instead, you potentially might want to share a submodule. For instance, in the example
+ * above the "piral-ng/common" submodule should be shared.
+ *
+ * ```json
+ * {
+ *   "importmap": {
+ *     "imports": {
+ *       "piral-ng/common": ""
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function invalidSharedDependency_0029(name: string): QuickMessage {
+  return [LogLevels.warning, '0029', `The dependency "${name}" should not be shared.`];
+}
+
 /**
  * @kind Error
  *
@@ -481,7 +795,7 @@ export function projectReferenceNotSupported_0032(fullPath: string): QuickMessag
  * CLI via command line parameters.
  *
  * @see
- * - [NPM Package Specification](https://docs.npmjs.com/files/package.json)
+ * - [npm Package Specification](https://docs.npmjs.com/files/package.json)
  *
  * @example
  * Make sure you are in the right directory by calling commands such as
@@ -527,7 +841,7 @@ export function invalidPiletTarget_0040(): QuickMessage {
  * contains an object with additional fields.
  *
  * @see
- * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/metadata#pilets---package-definition)
+ * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/C31-pilet-metadata)
  *
  * @example
  * Your pilet's package.json may look similar to the following snippet:
@@ -576,7 +890,7 @@ export function invalidPiletPackage_0041(): QuickMessage {
  * should contain (among others) a field `name` pointing to the Piral instance to use.
  *
  * @see
- * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/metadata#pilets---package-definition)
+ * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/C31-pilet-metadata)
  *
  * @example
  * If your Piral instance is called `my-piral` then the package.json may look similar to
@@ -611,12 +925,12 @@ export function invalidPiletPackage_0042(): QuickMessage {
  * Even though everything seems to be correct on the first glance it may be that the
  * actual reference is broken. This could be due to various reasons.
  *
- * - NPM linking is broken
+ * - npm linking is broken
  * - The dependencies have not been installed yet (run `npm i`)
  * - The Piral instance's name is invalid (e.g., due to a typo)
  *
  * @see
- * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/metadata#pilets---package-definition)
+ * - [Pilet Package Definition](https://docs.piral.io/reference/documentation/C31-pilet-metadata)
  * - [Node Modules Loading](https://nodejs.org/api/modules.html#modules_loading_from_node_modules_folders)
  *
  * @example
@@ -750,6 +1064,41 @@ export function cannotFindFile_0046(file: string): QuickMessage {
   return [LogLevels.error, '0046', `The file "${file}" does not exist!`];
 }
 
+/**
+ * @kind Warning
+ *
+ * @summary
+ * Reported when the provided / default port was not available.
+ *
+ * @abstract
+ * By default, the debug commands spawn at the port 1234. However, under certain
+ * circumstances (e.g., another debug command running somewhere) this port may not
+ * be free.
+ *
+ * The piral-cli can select a new port, which is free, however, it will still report
+ * a warning message in such cases. You can then always abort the current debug
+ * process and start a new one - either closing the other run blocking the port or
+ * explicitly selecting a new one using the `--port` flag.
+ *
+ * @see
+ * - [Port (computer networking)](https://en.wikipedia.org/wiki/Port_(computer_networking))
+ *
+ * @example
+ * If you start one process to debug an app shell using `piral debug` and another process
+ * to debug some pilet using `pilet debug` both processes would want to run on the default
+ * port 1234.
+ *
+ * As a mitigation you can now either be very explicit, e.g., `piral debug --port 1010` and
+ * `pilet debug --port 1020` or you can just drop one of the two and always only run a single
+ * debug process.
+ *
+ * In any case, running both without any options also works, but then a new port will be chosen.
+ * The output of the Piral CLI will always show you what port is currently used.
+ */
+export function portNotFree_0047(newPort: number, oldPort: number): QuickMessage {
+  return [LogLevels.warning, '0047', `The selected port "${oldPort}" is already used. Changed port to "${newPort}".`];
+}
+
 /**
  * @kind Warning
  *
@@ -762,8 +1111,8 @@ export function cannotFindFile_0046(file: string): QuickMessage {
  * Since the local resolution only works against a filename the update process has also to be triggered with
  * a file location. Otherwise, there is no chance to know a different file location.
  *
- * Potentially, you wanted to switch / resolve the module from NPM instead. Therefore, we are then trying to
- * obtain the Piral instance from NPM instead using the known name.
+ * Potentially, you wanted to switch / resolve the module from npm instead. Therefore, we are then trying to
+ * obtain the Piral instance from npm instead using the known name.
  *
  * @see
  * - [Local File Dependencies](https://stackoverflow.com/questions/14381898/local-dependency-in-package-json)
@@ -800,11 +1149,11 @@ export function localeFileForUpgradeMissing_0050(): QuickMessage {
  * Right now we only support "latest" for Git resolved Piral instances. In this scenario we obtain the
  * current head from the repository's default branch and update accordingly.
  *
- * Potentially, you wanted to switch / resolve the module from NPM instead. Therefore, we are then trying to
- * obtain the Piral instance from NPM instead using the known name.
+ * Potentially, you wanted to switch / resolve the module from npm instead. Therefore, we are then trying to
+ * obtain the Piral instance from npm instead using the known name.
  *
  * @see
- * - [Git Dependencies in NPM](https://medium.com/@jonchurch/use-github-branch-as-dependency-in-package-json-5eb609c81f1a)
+ * - [Git Dependencies in npm](https://medium.com/@jonchurch/use-github-branch-as-dependency-in-package-json-5eb609c81f1a)
  *
  * @example
  * You may have set up the pilet using a locally available tgz file. In this case your original command may
@@ -850,7 +1199,7 @@ export function gitLatestForUpgradeMissing_0051(): QuickMessage {
  * - Disk failures
  *
  * @see
- * - [Piral Instance Package Definition](https://docs.piral.io/reference/documentation/metadata#piral-instance---package-definition)
+ * - [Piral Instance Package Definition](https://docs.piral.io/reference/documentation/C21-piral-metadata)
  *
  * @example
  * The primary example hits when a dev dependency was specified that is otherwise not given.
@@ -911,7 +1260,7 @@ export function cannotResolveVersion_0052(name: string): QuickMessage {
  * - Disk failures
  *
  * @see
- * - [Piral Instance Package Definition](https://docs.piral.io/reference/documentation/metadata#piral-instance---package-definition)
+ * - [Piral Instance Package Definition](https://docs.piral.io/reference/documentation/C21-piral-metadata)
  *
  * @example
  * The primary example hits when a dev dependency was specified that is otherwise not given.
@@ -944,9 +1293,14 @@ export function cannotResolveVersion_0052(name: string): QuickMessage {
  *     }
  *   }
  * }
+ * ```
  */
-export function cannotResolveDependency_0053(name: string, rootDir: string): QuickMessage {
-  return [LogLevels.warning, '0053', `Could not resolve "${name}" from "${rootDir}". Taking "latest" version.`];
+export function cannotResolveDependency_0053(names: Array<string>, rootDir: string): QuickMessage {
+  return [
+    LogLevels.warning,
+    '0053',
+    `Could not resolve any package (tried "${names.join('", "')}") from "${rootDir}". Taking "latest" version.`,
+  ];
 }
 
 /**
@@ -995,7 +1349,7 @@ export function missingPiletFeedUrl_0060(): QuickMessage {
  * directly.
  *
  * @see
- * - [NPM Pack](https://docs.npmjs.com/cli-commands/pack.html)
+ * - [npm Pack](https://docs.npmjs.com/cli-commands/pack.html)
  *
  * @example
  * Make sure to have build a pilet beforehand:
@@ -1025,8 +1379,8 @@ export function missingPiletFeedUrl_0060(): QuickMessage {
  * Using multiple commands is preferred if you use custom options, otherwise
  * just go for the single command.
  */
-export function missingPiletTarball_0061(source: string): QuickMessage {
-  return [LogLevels.error, '0061', `No files found using pattern "${source}".`];
+export function missingPiletTarball_0061(sources: Array<string>): QuickMessage {
+  return [LogLevels.error, '0061', `No files found using pattern "${sources.join('", "')}".`];
 }
 
 /**
@@ -1277,10 +1631,10 @@ export function failedHttpGet_0068(error: string): QuickMessage {
  *
  * @abstract
  * While submitting the HTTP get request an error was reported.
- * 
+ *
  * Potentially, the server returned some more indicative error message. In this
  * case read it carefully to know what version was already published.
- * 
+ *
  * In any case only the documentation of the corresponding feed service can be
  * conclusive how this can be resolved. Presumably, some payment of some fee
  * is necessary to publish pilets.
@@ -1299,28 +1653,28 @@ export function failedToUploadPayment_0161(response: any): QuickMessage {
  *
  * @abstract
  * While submitting the HTTP get request an error was reported.
- * 
+ *
  * Potentially, the server returned some more indicative error message. In this
  * case read it carefully to know what version was already published.
- * 
+ *
  * In any case you need to change the version to continue. You can do that by
  * editing the "version" field in the pilet's package.json or using `npm version`.
  *
  * @example
  * If you already published the pilet, e.g., via
- * 
+ *
  * ```sh
  * pilet publish --api-key ... --url ...
  * ```
- * 
+ *
  * then doing this again without any change should result in this error.
- * 
+ *
  * Now we can patch-upgrade the version of the pilet:
- * 
+ *
  * ```sh
  * npm version patch
  * ```
- * 
+ *
  * And try the `pilet publish` command again. This time it should just work.
  */
 export function failedToUploadVersion_0162(response: any): QuickMessage {
@@ -1337,10 +1691,10 @@ export function failedToUploadVersion_0162(response: any): QuickMessage {
  *
  * @abstract
  * While submitting the HTTP get request an error was reported.
- * 
+ *
  * Potentially, the server returned some more indicative error message. In this
  * case read it carefully to know how much the limit was exceeded.
- * 
+ *
  * In any case the pilet must be somehow trimmed down. Most often, the size is
  * dominantly determined by some external packages that are referened. Use a
  * page such as bundlephobia.com or some IDE tools to find out which packages
@@ -1541,10 +1895,10 @@ export function entryPointDoesNotExist_0073(app: string): QuickMessage {
  * point for the bundler.
  *
  * @see
- * - [NPM Init](https://docs.npmjs.com/cli/init)
+ * - [npm Init](https://docs.npmjs.com/cli/init)
  *
  * @example
- * You can create a new NPM project using the `npm init` command. This will essentially guide
+ * You can create a new npm project using the `npm init` command. This will essentially guide
  * you through a number of decisions for creating a proper package.json.
  *
  * Even better you could start a new Piral instance using the following command:
@@ -1577,10 +1931,10 @@ export function packageJsonMissing_0074(): QuickMessage {
  * point for the bundler.
  *
  * @see
- * - [NPM Init](https://docs.npmjs.com/cli/init)
+ * - [npm Init](https://docs.npmjs.com/cli/init)
  *
  * @example
- * You can create a new NPM project using the `npm init` command. This will essentially guide
+ * You can create a new npm project using the `npm init` command. This will essentially guide
  * you through a number of decisions for creating a proper package.json.
  *
  * Even better you could start a new pilet using the following command:
@@ -1642,7 +1996,7 @@ export function packageJsonMissing_0075(): QuickMessage {
  * The TypeScript declaration generator will take all files as input to
  * gather all required information for constructing the API declaration.
  */
-export function declarationCouldNotBeGenerated_0076(rootDir: string, error: Error): QuickMessage {
+export function declarationCouldNotBeGenerated_0076(rootDir: string, error: Error | string): QuickMessage {
   return [LogLevels.error, '0076', `Could not create the declaration in "${rootDir}". Error: ${error}`];
 }
 
@@ -1682,6 +2036,67 @@ export function entryFileMissing_0077(): QuickMessage {
   return [LogLevels.error, '0077', 'No valid entry file for the pilet found.'];
 }
 
+/**
+ * @kind Warning
+ *
+ * @summary
+ * The Piral instance is not referencing any framework package.
+ *
+ * @abstract
+ * A Piral instance has to reference either `piral-base`, `piral-core`
+ * or the whole `piral` framework package. If none of these dependencies
+ * is found then no framework dependencies can be shared automatically.
+ * Framework dependencies include react and react-router.
+ *
+ * @example
+ * You might use a monorepo where most / all dependencies are declared in
+ * a top-level package.json. Therefore, the package.json of the actual
+ * Piral instance could look like this:
+ *
+ * ```json
+ * {
+ *   "name": "my-piral-instance",
+ *   "version": "1.0.0",
+ *   "app": "./src/index.html",
+ *   "pilets": {}
+ * }
+ * ```
+ *
+ * While perfectly valid, this one lacks `dependencies` and `devDependencies`.
+ * Surely, those are not really needed in the described case, but under
+ * those conditions we cannot know what dependencies you may want to share. It
+ * could be that you only reference `piral-base` and therefore don't want to
+ * share anything except `tslib`. Or you use `piral-core` and also share things
+ * like `react` or `react-router-dom`.
+ *
+ * Either way, in order to recognize that you'll need to include the correct
+ * reference:
+ *
+ * ```json
+ * {
+ *   "name": "my-piral-instance",
+ *   "version": "1.0.0",
+ *   "app": "./src/index.html",
+ *   "pilets": {},
+ *   "dependencies": {
+ *     "piral": "latest"
+ *   }
+ * }
+ * ```
+ *
+ * If you only want to use `piral-base` or `piral-core` then replace `piral` in
+ * the example above. Also use the version that you'll like to use - `latest`
+ * is just one example.
+ *
+ */
+export function frameworkLibMissing_0078(frameworkLibs: Array<string>): QuickMessage {
+  return [
+    LogLevels.warning,
+    '0078',
+    `Did not find any reference to either ${frameworkLibs.join(', ')}. No framework dependencies are shared.`,
+  ];
+}
+
 /**
  * @kind Error
  *
@@ -1841,6 +2256,26 @@ export function toolingIncompatible_0101(piralVersion: string, cliVersion: strin
   ];
 }
 
+/**
+ * @kind Info
+ *
+ * @summary
+ * The Piral CLI could not detect the tooling version used by the app shell. Therefore, it may be incompatible to the
+ * currently used version of the piral-cli. Keep an eye on weird errors.
+ *
+ * @abstract
+ * The emulator contains a special section to inform the Piral CLI about the used version of the tooling. This is
+ * important to detect potential alignment or incompatibilities. The used version of the emulator does not contain
+ * this information and therefore may be incompatible.
+ */
+export function appShellMaybeIncompatible_0102(cliVersion: string): QuickMessage {
+  return [
+    LogLevels.info,
+    '0100',
+    `The Piral instance's CLI version is unknown and may be incompatible to the used version (${cliVersion}).`,
+  ];
+}
+
 /**
  * @kind Error
  *
@@ -1855,7 +2290,7 @@ export function toolingIncompatible_0101(piralVersion: string, cliVersion: strin
  *
  * @example
  * The following command first removes the output directory, then starts the build,
- * and finally publishes the emulator to NPM.
+ * and finally publishes the emulator to npm.
  *
  * ```sh
  * rm -rf dist
@@ -1881,7 +2316,7 @@ export function publishDirectoryMissing_0110(directory: string): QuickMessage {
  *
  * @example
  * The following command first removes the output directory, then starts the build,
- * and finally publishes the emulator to NPM.
+ * and finally publishes the emulator to npm.
  *
  * ```sh
  * rm -rf dist
@@ -1897,24 +2332,24 @@ export function publishEmulatorFilesUnexpected_0111(directory: string): QuickMes
  * @kind Error
  *
  * @summary
- * The "xcopy" provider requires a "--fields.target" argument.
+ * The "xcopy" provider requires a "--opts.target" argument.
  *
  * @abstract
  * The `piral publish --type release` command requires the selection of a suitable
  * provider for running successfully. The "xcopy" provider just copies the sources from
  * the output directory (source) to a specified target directory.
  *
- * Make sure to supply the target directory via the `--fields.target` command line flag.
+ * Make sure to supply the target directory via the `--opts.target` command line flag.
  *
  * @example
  * The following command would specify `/temp/dest` as target directory:
  *
  * ```sh
- * piral publish --type release --provider xcopy --fields.target "/temp/dest"
+ * piral publish --type release --provider xcopy --opts.target "/temp/dest"
  * ```
  */
 export function publishXcopyMissingTarget_0112(): QuickMessage {
-  return [LogLevels.error, '0112', `The "xcopy" provider requires a "--fields.target" argument.`];
+  return [LogLevels.error, '0112', `The "xcopy" provider requires a "--opts.target" argument.`];
 }
 
 /**
@@ -1937,7 +2372,7 @@ export function publishXcopyMissingTarget_0112(): QuickMessage {
  * The following command uses the in-built "xcopy" provider for releasing to a local directory.
  *
  * ```sh
- * piral publish --type release --provider xcopy --fields.target "/temp/dest"
+ * piral publish --type release --provider xcopy --opts.target "/temp/dest"
  * ```
  */
 export function publishProviderMissing_0113(providerName: string, availableProviders: Array<string>): QuickMessage {
@@ -1958,13 +2393,73 @@ export function publishProviderMissing_0113(providerName: string, availableProvi
  * The following command uses the in-built "xcopy" provider for releasing to a local directory.
  *
  * ```sh
- * piral publish --type release --provider xcopy --fields.target "/temp/dest"
+ * piral publish --type release --provider xcopy --opts.target "/temp/dest"
  * ```
- * 
+ *
  * The type is "release".
  */
 export function publishEmulatorSourcesInvalid_0114(): QuickMessage {
-  return [LogLevels.error, '0114', `The command "publish" cannot be done with "--type emulator-sources". Use another type instead.`];
+  return [
+    LogLevels.error,
+    '0114',
+    `The command "publish" cannot be done with "--type emulator-sources". Use another type instead.`,
+  ];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * The "feed" provider requires a "--opts.url" argument.
+ *
+ * @abstract
+ * The `piral publish --type release` command requires the selection of a suitable
+ * provider for running successfully. The "feed" provider releases the files to
+ * the a Piral Feed Service with the static page feature.
+ *
+ * Make sure to supply the URL for the feed service via the `--opts.url` command
+ * line flag.
+ *
+ * @example
+ * The following command would specify `https://feed.piral.cloud/api/v1/feed/sample/page`
+ * for the feed service:
+ *
+ * ```sh
+ * piral publish --type release --provider feed --opts.url "https://feed.piral.cloud/api/v1/feed/sample/page" --opts.apikey "foobar123"
+ * ```
+ */
+export function publishFeedMissingUrl_0115(): QuickMessage {
+  return [LogLevels.error, '0115', `The "feed" provider requires a "--opts.url" argument.`];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * The "feed" provider requires a "--opts.version" argument.
+ *
+ * @abstract
+ * The `piral publish --type release` command requires the selection of a suitable
+ * provider for running successfully. The "feed" provider releases the files to
+ * the a Piral Feed Service with the static page feature.
+ *
+ * Make sure to supply the version either explicitly via the `--opts.version` argument
+ * or implicitly by having the artifacts stored in a sub-directory of the project's root,
+ * which contains a package.json with the version to use.
+ *
+ * @example
+ * The following command would specify version "1.2.3" for the feed service:
+ *
+ * ```sh
+ * piral publish --type release --provider feed --opts.url "..." --opts.apikey "..." --opts.version "1.2.3"
+ * ```
+ */
+export function publishFeedMissingVersion_0116(): QuickMessage {
+  return [
+    LogLevels.error,
+    '0116',
+    `The "feed" provider requires either a "--opts.version" argument or a package.json with a version.`,
+  ];
 }
 
 /**
@@ -1986,7 +2481,7 @@ export function publishEmulatorSourcesInvalid_0114(): QuickMessage {
  * - The API for opening the default browser is invalid
  *
  * @see
- * - [NPM Open Package](https://www.npmjs.com/package/open)
+ * - [npm Open Package](https://www.npmjs.com/package/open)
  *
  * @example
  * The browser is usually just opened via the command line:
@@ -2010,13 +2505,19 @@ export function failedToOpenBrowser_0170(error: string): QuickMessage {
  * the interpretation of compatible feed services slightly and has an impact of the usage
  * of the pilet in the browser.
  *
- * The selected schema version needs to be either "v0" or "v1".
+ * The selected schema version needs to be either "v0", "v1", or "v2".
  *
  * - v0: will download and evaluate the pilet explicitly
- * - v1: will use a script tag for integration of the pilet (default)
+ * - v1: will use a script tag for integration of the pilet
+ * - v2: will use SystemJS for integration of the pilet (default)
  *
  * The v1 version has better support for older browsers, but requires a polyfill to work
- * correctly. This polyfill is part of the standard Piral polyfills.
+ * correctly. This polyfill is part of the `piral-ie11polyfills-utils` package.
+ * Alternatively, use the `currentScript-polyfill` package.
+ *
+ * The v2 version uses a SystemJS format for the pilet. It has the broadest browser support
+ * but requires the custom format as output. Most bundlers support SystemJS directly or
+ * indirectly, making it a quite broad choice.
  *
  * @see
  * - [GitHub currentScript-polyfill](https://github.com/amiller-gh/currentScript-polyfill)
@@ -2041,8 +2542,8 @@ export function invalidSchemaVersion_0171(schemaVersion: string, schemas: Array<
  *
  * @abstract
  * Piral allows you to set up your own tooling for building and debugging. This
- * is a powerful concept. By default, the Webpack bundler is used. Alternatives
- * include Parcel and Rollup.
+ * is a powerful concept. By default, the Webpack v5 bundler is used.
+ * Alternatives include Parcel and Rollup.
  *
  * In case where multiple bundlers are installed the first one is picked. This
  * may not be what you want. In this scenario you can override the selection by
@@ -2053,7 +2554,9 @@ export function invalidSchemaVersion_0171(schemaVersion: string, schemas: Array<
  * @see
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [esbuild](https://esbuild.github.io)
+ * - [rspack](https://www.rspack.dev/)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2075,8 +2578,8 @@ export function bundlerMissing_0172(bundlerName: string, installed: Array<string
  *
  * @abstract
  * Piral allows you to set up your own tooling for building and debugging. This
- * is a powerful concept. By default, the Webpack bundler is used. Alternatives
- * include Parcel and Rollup.
+ * is a powerful concept. By default, the Webpack v5 bundler is used.
+ * Alternatives include Parcel and Rollup.
  *
  * In case where no bundler is installed and the default bundler could not be
  * successfully installed this error is shown.
@@ -2084,7 +2587,9 @@ export function bundlerMissing_0172(bundlerName: string, installed: Array<string
  * @see
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [esbuild](https://esbuild.github.io)
+ * - [rspack](https://www.rspack.dev/)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2115,7 +2620,9 @@ export function defaultBundlerMissing_0173(): QuickMessage {
  * @see
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [esbuild](https://esbuild.github.io)
+ * - [rspack](https://www.rspack.dev/)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2136,8 +2643,8 @@ export function bundlingFailed_0174(error: string): QuickMessage {
  *
  * @abstract
  * Piral allows you to set up your own tooling for building and debugging. This
- * is a powerful concept. By default, the Webpack bundler is used. Alternatives
- * include Parcel and Rollup.
+ * is a powerful concept. By default, the Webpack v5 bundler is used.
+ * Alternatives include Parcel and Rollup.
  *
  * In case where multiple bundlers are installed the first one is picked. This
  * may not be what you want. In this scenario you can explicitly set the bundler
@@ -2148,7 +2655,7 @@ export function bundlingFailed_0174(error: string): QuickMessage {
  * dependent we recommend setting the bundler explicitly.
  *
  * @see
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to explicitly choose the Parcel bundler:
@@ -2166,6 +2673,85 @@ export function bundlerUnspecified_0175(available: Array<string>): QuickMessage
   ];
 }
 
+/**
+ * @kind Warning
+ *
+ * @summary
+ * No bundler has been installed yet.
+ *
+ * @abstract
+ * Piral allows you to set up your own tooling for building and debugging. This
+ * is a powerful concept. By default, the Webpack v5 bundler is used.
+ * Alternatives include Parcel and Rollup.
+ *
+ * In case no bundler is yet installed the Piral CLI will automatically install
+ * the default bundler. However, you should consider installing a bundler of your
+ * choice (even if this could also be the default bundler) explicitly.
+ *
+ * @see
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
+ *
+ * @example
+ * Use the following command to install esbuild as a bundler with the npm client:
+ *
+ * ```sh
+ * npm i piral-cli-esbuild --save-dev
+ * ```
+ */
+export function bundlerNotInstalled_0176(): QuickMessage {
+  return [LogLevels.warning, '0176', `Installing default bundler since no bundler has been found.`];
+}
+
+/**
+ * @kind Warning
+ *
+ * @summary
+ * No pilet.json has been found.
+ *
+ * @abstract
+ * For some functionality such as multi Piral instance support when debugging
+ * a pilet, a special file called pilet.json is required. While this file is
+ * optional in general, it must be available for certain tasks such as adding
+ * or removing a Piral instance for debugging purposes.
+ *
+ * @see
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
+ *
+ * @example
+ * If no pilet.json is yet available you can create one. It should be adjacent to
+ * the package.json of your pilet, even though different locations are also possible.
+ * By default, the following content can be used for an empty file:
+ *
+ * ```json
+ * {
+ *   "$schema": "https://docs.piral.io/schemas/pilet-v0.json"
+ * }
+ * ```
+ */
+export function piletJsonNotAvailable_0180(root: string): QuickMessage {
+  return [LogLevels.warning, '0180', `No "pilet.json" was found for the pilet at "${root}".`];
+}
+
+/**
+ * @kind Error
+ *
+ * @summary
+ * Using the given platform is not supported.
+ *
+ * @abstract
+ * The Piral instance can run on multiple platforms. The platform is specified via
+ * the piral.json file.
+ *
+ * The standard platform is "web", which starts a web server using the server
+ * proxy kras.
+ *
+ * @example
+ * (tbd)
+ */
+export function platformNotSupported_0190(platform: string): QuickMessage {
+  return [LogLevels.error, '0190', `The given platform "${platform}" is not supported.`];
+}
+
 /**
  * @kind Warning
  *