piral-cli 0.15.0 → 0.15.1-beta.4903

package/src/commands.ts

@@ -61,7 +61,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source root directory or index.html file for collecting all the information.',
+          describe: 'Sets the source Piral instance path for collecting all the information.',
           default: apps.debugPiralDefaults.entry,
         })
         .string('target')
@@ -121,7 +121,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source root directory or index.html file for collecting all the information.',
+          describe: 'Sets the source Piral instance path for collecting all the information.',
           default: apps.buildPiralDefaults.entry,
         })
         .string('target')
@@ -234,7 +234,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source root directory or index.html file for collecting all the information.',
+          describe: 'Sets the source Piral instance path for collecting all the information.',
           default: apps.declarationPiralDefaults.entry,
         })
         .string('target')
@@ -388,7 +388,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source root directory or index.html file for collecting all the information.',
+          describe: 'Sets the source Piral instance path for collecting all the information.',
           default: apps.validatePiralDefaults.entry,
         })
         .number('log-level')
@@ -489,7 +489,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source index.tsx file for collecting all the information.',
+          describe: 'Sets the source pilet path for collecting all the information.',
           default: apps.buildPiletDefaults.entry,
         })
         .string('target')
@@ -568,7 +568,7 @@ const allCommands: Array<ToolCommand<any>> = [
       return argv
         .positional('source', {
           type: 'string',
-          describe: 'Sets the source package.json file for creating the package.',
+          describe: 'Sets the source pilet path for creating the package.',
           default: apps.packPiletDefaults.source,
         })
         .string('target')
@@ -807,6 +807,78 @@ const allCommands: Array<ToolCommand<any>> = [
       });
     },
   },
+  {
+    name: 'add-piral-instance-pilet',
+    alias: ['add-shell-pilet', 'install-shell-pilet', 'add-app-pilet', 'with-app-pilet'],
+    description: 'Adds another Piral instance to the available apps hosting the current pilet.',
+    arguments: ['[source]'],
+    flags(argv) {
+      return argv
+        .positional('app', {
+          type: 'string',
+          describe: 'Sets the name of the Piral instance to be added.',
+          default: apps.addPiralInstancePiletDefaults.app,
+        })
+        .positional('source', {
+          type: 'string',
+          describe: 'Sets the source pilet path where the Piral instance should be added.',
+          default: apps.addPiralInstancePiletDefaults.source,
+        })
+        .number('log-level')
+        .describe('log-level', 'Sets the log level to use (1-5).')
+        .default('log-level', apps.addPiralInstancePiletDefaults.logLevel)
+        .choices('npm-client', clientTypeKeys)
+        .describe('npm-client', 'Sets the npm client to be used for adding the Piral instance.')
+        .default('npm-client', apps.addPiralInstancePiletDefaults.npmClient)
+        .boolean('selected')
+        .describe('selected', 'Defines if the provided Piral instance should be selected initially.')
+        .default('selected', apps.addPiralInstancePiletDefaults.selected)
+        .string('base')
+        .default('base', process.cwd())
+        .describe('base', 'Sets the base directory. By default the current directory is used.');
+    },
+    run(args) {
+      return apps.addPiralInstancePilet(args.base as string, {
+        logLevel: args['log-level'] as LogLevels,
+        selected: args.selected as boolean,
+        npmClient: args['npm-client'] as NpmClientType,
+        app: args.app as string,
+        source: args.source as string,
+      });
+    },
+  },
+  {
+    name: 'remove-piral-instance-pilet',
+    alias: ['remove-shell-pilet', 'uninstall-shell-pilet', 'remove-app-pilet', 'without-app-pilet'],
+    description: 'Removes an existing Piral instance from the available apps hosting the current pilet.',
+    arguments: ['[source]'],
+    flags(argv) {
+      return argv
+        .positional('app', {
+          type: 'string',
+          describe: 'Sets the name of the Piral instance to be removed.',
+          default: apps.removePiralInstancePiletDefaults.app,
+        })
+        .positional('source', {
+          type: 'string',
+          describe: 'Sets the source pilet path where the Piral instance should be removed.',
+          default: apps.removePiralInstancePiletDefaults.source,
+        })
+        .number('log-level')
+        .describe('log-level', 'Sets the log level to use (1-5).')
+        .default('log-level', apps.removePiralInstancePiletDefaults.logLevel)
+        .string('base')
+        .default('base', process.cwd())
+        .describe('base', 'Sets the base directory. By default the current directory is used.');
+    },
+    run(args) {
+      return apps.removePiralInstancePilet(args.base as string, {
+        logLevel: args['log-level'] as LogLevels,
+        app: args.app as string,
+        source: args.source as string,
+      });
+    },
+  },
 ];
 
 class Commands implements ListCommands {

package/src/common/declaration.ts

@@ -2,7 +2,7 @@ import { DeclOptions, generateDeclaration, createExcludePlugin, Logger } from 'd
 import { dirname, basename, resolve, extname } from 'path';
 import { progress, log, logWarn, logVerbose, logInfo } from './log';
 import { ForceOverwrite } from './enums';
-import { retrievePiralRoot, retrievePiletsInfo } from './package';
+import { retrievePiralRoot, retrievePiletsInfo, flattenExternals } from './package';
 import { entryModuleExtensions, piralBaseRoot } from './constants';
 import { readText, getEntryFiles, matchFiles, createFileIfNotExists } from './io';
 import { getModulePath } from '../external';
@@ -167,7 +167,7 @@ export async function createPiralDeclaration(
     types: findDeclaredTypings(root),
     apis: findPiralBaseApi(root, framework),
     noModuleDeclaration: true,
-    imports: externals.map(m => m.name),
+    imports: flattenExternals(externals),
     logLevel,
     logger: createLogger(),
   };

package/src/common/emulator.ts

@@ -1,5 +1,5 @@
 import { join, resolve, relative } from 'path';
-import { findDependencyVersion, copyScaffoldingFiles, isValidDependency } from './package';
+import { findDependencyVersion, copyScaffoldingFiles, isValidDependency, flattenExternals } from './package';
 import { createPiralStubIndexIfNotExists } from './template';
 import { filesTar, filesOnceTar } from './constants';
 import { cliVersion } from './info';
@@ -96,7 +96,7 @@ export async function createEmulatorSources(
       ...allDeps,
       ...externalDependencies,
     },
-    sharedDependencies: externals.map(m => m.name),
+    sharedDependencies: flattenExternals(externals),
     repository: piralPkg.repository,
     bugs: piralPkg.bugs,
     author: piralPkg.author,

package/src/common/index.ts

@@ -29,6 +29,7 @@ export * from './port';
 export * from './rules';
 export * from './scaffold';
 export * from './scripts';
+export * from './shell';
 export * from './spec';
 export * from './template';
 export * from './url';

package/src/common/npm.ts

@@ -394,7 +394,7 @@ export function combinePackageRef(name: string, version: string, type: PackageTy
   return name;
 }
 
-export async function getPackageName(root: string, name: string, type: PackageType) {
+export async function getPackageName(root: string, name: string, type: PackageType): Promise<string> {
   switch (type) {
     case 'file':
       const originalPackageJson = await readJson(name, 'package.json');

package/src/common/package.ts

@@ -532,6 +532,14 @@ export async function findPackageVersion(rootPath: string, packageName: string |
   return 'latest';
 }
 
+function onlyUnique<T>(value: T, index: number, self: Array<T>) {
+  return self.indexOf(value) === index;
+}
+
+export function flattenExternals(dependencies: Array<SharedDependency>) {
+  return dependencies.map((m) => m.name).filter(onlyUnique);
+}
+
 export async function retrieveExternals(root: string, packageInfo: any): Promise<Array<SharedDependency>> {
   const sharedDependencies = await readImportmap(root, packageInfo);
 
@@ -729,17 +737,21 @@ export function combinePiletExternals(
   return externals;
 }
 
-export async function retrievePiletData(target: string, app?: string) {
-  const piletJson = await findFile(target, 'pilet.json');
-  const proposedRoot = piletJson ? dirname(piletJson) : target;
+export async function findPiletRoot(proposedRoot: string) {
   const packageJson = await findFile(proposedRoot, 'package.json');
 
   if (!packageJson) {
     fail('packageJsonMissing_0075');
   }
 
-  const root = dirname(packageJson);
-  const piletPackage = require(packageJson);
+  return dirname(packageJson);
+}
+
+export async function retrievePiletData(target: string, app?: string) {
+  const piletJson = await findFile(target, 'pilet.json');
+  const proposedRoot = piletJson ? dirname(piletJson) : target;
+  const root = await findPiletRoot(proposedRoot);
+  const piletPackage = require(resolve(root, 'package.json'));
   const piletDefinition = piletJson && require(piletJson);
   const appPackages = findPiralInstances(app && [app], piletPackage, piletDefinition, target);
   const apps: Array<AppDefinition> = [];

package/src/common/shell.ts

@@ -0,0 +1,34 @@
+import { progress } from './log';
+import {
+  combinePackageRef,
+  dissectPackageName,
+  getPackageName,
+  getPackageVersion,
+  installNpmPackage,
+  isLinkedPackage,
+} from './npm';
+import { NpmClientType } from '../types';
+
+export async function installPiralInstance(
+  usedSource: string,
+  baseDir: string,
+  rootDir: string,
+  npmClient: NpmClientType,
+): Promise<[name: string, version: string]> {
+  const [sourceName, sourceVersion, hadVersion, type] = await dissectPackageName(baseDir, usedSource);
+  const isLocal = isLinkedPackage(sourceName, type, hadVersion);
+
+  if (!isLocal) {
+    const packageRef = combinePackageRef(sourceName, sourceVersion, type);
+
+    progress(`Installing npm package %s ...`, packageRef);
+    await installNpmPackage(npmClient, packageRef, rootDir, '--save-dev', '--save-exact');
+  } else {
+    progress(`Using locally available npm package %s ...`, sourceName);
+  }
+
+  const packageName = await getPackageName(rootDir, sourceName, type);
+  const packageVersion = getPackageVersion(hadVersion, sourceName, sourceVersion, type, rootDir);
+
+  return [packageName, packageVersion];
+}

package/src/messages.ts

@@ -777,7 +777,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:
@@ -826,7 +826,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
@@ -866,7 +866,7 @@ export function invalidPiletPackage_0042(): QuickMessage {
  * - 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
@@ -1135,7 +1135,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.
@@ -1196,7 +1196,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.
@@ -2491,7 +2491,7 @@ export function invalidSchemaVersion_0171(schemaVersion: string, schemas: Array<
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
  * - [esbuild](https://esbuild.github.io)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2523,7 +2523,7 @@ export function bundlerMissing_0172(bundlerName: string, installed: Array<string
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
  * - [esbuild](https://esbuild.github.io)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2555,7 +2555,7 @@ export function defaultBundlerMissing_0173(): QuickMessage {
  * - [Webpack](https://webpack.js.org)
  * - [Parcel](https://parceljs.org)
  * - [esbuild](https://esbuild.github.io)
- * - [Pluggable bundlers](https://docs.piral.io/reference/documentation/bundlers)
+ * - [Pluggable bundlers](https://docs.piral.io/concepts/T02-bundlers)
  *
  * @example
  * Use the following command to make the parcel bundler available:
@@ -2588,7 +2588,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:
@@ -2622,7 +2622,7 @@ export function bundlerUnspecified_0175(available: Array<string>): QuickMessage
  * choice (even if this could also be the default 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 install esbuild as a bundler with the npm client:
@@ -2635,6 +2635,34 @@ 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
+ *
+ * ```
+ */
+export function piletJsonNotAvailable_0180(root: string): QuickMessage {
+  return [LogLevels.warning, '0180', `No "pilet.json" was found for the pilet at "${root}".`];
+}
+
 /**
  * @kind Warning
  *