piral-cli 1.0.0-pre.2296 → 1.0.1-beta.5640

package/src/common/package.ts

@@ -2,15 +2,86 @@ import { resolve, join, extname, basename, dirname, relative } from 'path';
 import { log, fail } from './log';
 import { cliVersion } from './info';
 import { unpackTarball } from './archive';
-import { getDevDependencies } from './language';
-import { SourceLanguage, ForceOverwrite } from './enums';
+import { ForceOverwrite } from './enums';
 import { checkAppShellCompatibility } from './compatibility';
-import { filesTar, filesOnceTar, declarationEntryExtensions } from './constants';
-import { getHash, checkIsDirectory, matchFiles, getFileNames } from './io';
-import { readJson, copy, updateExistingJson, findFile, checkExists } from './io';
-import { Framework, FileInfo, PiletsInfo, TemplateFileLocation } from '../types';
-import { isGitPackage, isLocalPackage, makeGitUrl, makeFilePath, makeExternals } from './npm';
 import { deepMerge } from './merge';
+import { onlyUnique } from './utils';
+import { readImportmap } from './importmap';
+import { getHash, checkIsDirectory, matchFiles } from './io';
+import { readJson, copy, updateExistingJson, findFile, checkExists } from './io';
+import { isGitPackage, isLocalPackage, makeGitUrl, makeFilePath, tryResolvePackage, isNpmPackage } from './npm';
+import { makePiletExternals, makeExternals, findPackageRoot, findSpecificVersion, makeNpmAlias } from './npm';
+import { getModulePath } from '../external';
+import { getDependencies, getDependencyPackages, getDevDependencies } from './language';
+import { getDevDependencyPackages, getFrameworkDependencies } from './language';
+import {
+  declarationEntryExtensions,
+  piralJsonSchemaUrl,
+  piletJsonSchemaUrl,
+  filesTar,
+  filesOnceTar,
+  bundlerNames,
+  frameworkLibs,
+  piralJson,
+  piletJson,
+  packageJson,
+} from './constants';
+import {
+  SourceLanguage,
+  Framework,
+  FileInfo,
+  PiletsInfo,
+  TemplateFileLocation,
+  PiletPackageData,
+  PiralPackageData,
+  SharedDependency,
+  PiletDefinition,
+  AppDefinition,
+  PiralInstancePackageData,
+} from '../types';
+
+export interface PiralInstanceData {
+  packageName: Framework;
+  language: SourceLanguage;
+  reactVersion: number;
+  reactRouterVersion: number;
+}
+
+async function appendBundler(devDependencies: Record<string, string>, bundler: string, proposedVersion: string) {
+  if (bundler && bundler !== 'none') {
+    if (isValidDependency(bundler)) {
+      const sep = bundler.indexOf('@', 1);
+      const hasVersion = sep !== -1;
+      const proposedName = bundler.substring(0, hasVersion ? sep : bundler.length);
+      const givenVersion = hasVersion ? bundler.substring(sep + 1) : proposedVersion;
+      const name = bundlerNames.includes(proposedName as any) ? `piral-cli-${bundler}` : proposedName;
+      const versions = new Set([
+        givenVersion,
+        givenVersion.includes('-beta.') && 'next',
+        givenVersion.includes('-alpha.') && 'canary',
+        givenVersion.includes('.') && givenVersion.split('.').slice(0, 2).join('.'),
+        'latest',
+      ]);
+
+      for (const version of versions) {
+        if (version) {
+          const isAvailable = await findSpecificVersion(name, version);
+
+          // only if something was returned we know that the version exists; so we can take it.
+          if (isAvailable) {
+            devDependencies[name] = version;
+            return;
+          }
+        }
+      }
+
+      log('generalWarning_0001', `Could not find a valid version for the provided bundler "${bundler}".'`);
+    } else {
+      //Error case - print warning and ignore
+      log('generalWarning_0001', `The provided bundler name "${bundler}" does not refer to a valid package name.'`);
+    }
+  }
+}
 
 function getDependencyVersion(
   name: string,
@@ -86,101 +157,157 @@ async function getMatchingFiles(
 }
 
 export function getPiralPath(root: string, name: string) {
-  const path = require.resolve(`${name}/package.json`, {
-    paths: [root],
-  });
+  const path = findPackageRoot(name, root);
+
+  if (!path) {
+    fail('invalidPiralReference_0043');
+  }
+
   return dirname(path);
 }
 
-export function findPackageRoot(pck: string, baseDir: string) {
-  try {
-    return require.resolve(`${pck}/package.json`, {
-      paths: [baseDir],
-    });
-  } catch (ex) {
-    log('generalDebug_0003', `Could not find the package root in "${baseDir}": ${ex}.`);
-    return undefined;
+export async function findPiralInstance(
+  proposedApp: string,
+  baseDir: string,
+  port: number,
+): Promise<PiralInstancePackageData> {
+  const path = findPackageRoot(proposedApp, baseDir);
+
+  if (path) {
+    log('generalDebug_0003', `Following the app package in "${path}" ...`);
+    const root = dirname(path);
+    const appPackage = await readJson(root, basename(path));
+    const relPath = appPackage && appPackage.app;
+    appPackage.app = relPath && resolve(root, relPath);
+    appPackage.root = root;
+    appPackage.port = port;
+    return appPackage;
   }
-}
 
-function findPackage(pck: string | Array<string>, baseDir: string) {
-  if (Array.isArray(pck)) {
-    for (const item of pck) {
-      const result = findPackage(item, baseDir);
+  fail('appInstanceNotFound_0010', proposedApp);
+}
 
-      if (result) {
-        return result;
-      }
+export async function findPiralInstances(
+  proposedApps: Array<string>,
+  piletPackage: PiletPackageData,
+  piletDefinition: undefined | PiletDefinition,
+  baseDir: string,
+) {
+  if (proposedApps) {
+    // do nothing
+  } else if (piletDefinition) {
+    const availableApps = Object.keys(piletDefinition.piralInstances || {});
+    proposedApps = availableApps.filter((m) => piletDefinition.piralInstances[m].selected);
+
+    if (proposedApps.length === 0) {
+      proposedApps = availableApps.slice(0, 1);
     }
   } else {
-    const path = findPackageRoot(pck, baseDir);
-
-    if (path) {
-      log('generalDebug_0003', `Following the app package in "${path}" ...`);
-      const appPackage = require(path);
-      const relPath = appPackage && appPackage.app;
-      appPackage.app = relPath && resolve(dirname(path), relPath);
-      return appPackage;
-    }
+    proposedApps = [piletPackage.piral?.name].filter(Boolean);
   }
 
-  return undefined;
+  if (proposedApps.length > 0) {
+    return Promise.all(
+      proposedApps.map((proposedApp) =>
+        findPiralInstance(proposedApp, baseDir, piletDefinition?.piralInstances?.[proposedApp]?.port ?? 0),
+      ),
+    );
+  }
+
+  return [];
 }
 
-export function readPiralPackage(root: string, name: string) {
+export function readPiralPackage(root: string, name: string): Promise<PiralPackageData> {
   log('generalDebug_0003', `Reading the piral package in "${root}" ...`);
   const path = getPiralPath(root, name);
   return readJson(path, 'package.json');
 }
 
-export function getPiralPackage(
+export async function patchPiralPackage(
+  root: string,
   app: string,
-  language: SourceLanguage,
+  data: PiralInstanceData,
   version: string,
-  framework: Framework,
   bundler?: string,
 ) {
-  const typings = framework === 'piral-base' ? {} : undefined;
+  log('generalDebug_0003', `Patching the package.json in "${root}" ...`);
+  const pkg = await getPiralPackage(app, data, version, bundler);
+
+  await updateExistingJson(root, 'package.json', pkg);
+  log('generalDebug_0003', `Succesfully patched the package.json.`);
+
+  await updateExistingJson(root, piralJson, {
+    $schema: piralJsonSchemaUrl,
+    pilets: getPiletsInfo({}),
+  });
+  log('generalDebug_0003', `Succesfully patched the pilet.json.`);
+}
+
+export async function getPiralPackage(app: string, data: PiralInstanceData, version: string, bundler?: string) {
+  const framework = data.packageName;
   const devDependencies = {
-    ...getDevDependencies(language, typings),
+    ...getDevDependencies(
+      data.language,
+      getDevDependencyPackages(framework, data.reactVersion, data.reactRouterVersion),
+    ),
     'piral-cli': `${version}`,
   };
+  const dependencies = {
+    ...getFrameworkDependencies(framework, version),
+    ...getDependencies(data.language, getDependencyPackages(framework, data.reactVersion, data.reactRouterVersion)),
+  };
 
-  if (bundler && bundler !== 'none') {
-    devDependencies[`piral-cli-${bundler}`] = `${version}`;
-  }
+  await appendBundler(devDependencies, bundler, version);
 
   return {
     app,
     scripts: {
       start: 'piral debug',
       build: 'piral build',
+      postinstall: 'piral declaration',
     },
-    pilets: getPiletsInfo({}),
+    types: 'dist/index.d.ts',
+    importmap: {
+      imports: {},
+      inherit: [
+        'piral-base', // this we take in any case
+        framework !== 'piral-base' && 'piral-core', // this we take unless we selected piral-base, then obviously core is not invited to the party
+        framework === 'piral' && 'piral', // this we take only if we selected piral
+      ].filter(Boolean),
+    },
+    dependencies,
     devDependencies,
   };
 }
 
-async function getAvailableFiles(root: string, name: string, tarBall: string): Promise<Array<FileDescriptor>> {
+async function getAvailableFiles(
+  root: string,
+  name: string,
+  dirName: string,
+  fileMap: Array<TemplateFileLocation>,
+): Promise<Array<FileDescriptor>> {
   const source = getPiralPath(root, name);
-  log('generalDebug_0003', `Checking if "files.tar" exists in "${source}" ...`);
-  const exists = await checkExists(resolve(source, `${tarBall}.tar`));
+  const tgz = `${dirName}.tar`;
+  log('generalDebug_0003', `Checking if "${tgz}" exists in "${source}" ...`);
+  const exists = await checkExists(resolve(source, tgz));
 
   if (exists) {
-    await unpackTarball(source, `${tarBall}.tar`);
+    await unpackTarball(source, tgz);
   }
 
   log('generalDebug_0003', `Get matching files from "${source}".`);
-  const base = resolve(source, tarBall);
+  const base = resolve(source, dirName);
   const files = await matchFiles(base, '**/*');
+
   return files.map((file) => ({
     sourcePath: file,
     targetPath: resolve(root, relative(base, file)),
   }));
 }
 
-export async function getFileStats(root: string, name: string) {
-  const files = await getAvailableFiles(root, name, filesTar);
+export async function getFileStats(root: string, name: string, fileMap: Array<TemplateFileLocation> = []) {
+  const files = await getAvailableFiles(root, name, filesTar, fileMap);
+
   return await Promise.all(
     files.map(async (file) => {
       const { sourcePath, targetPath } = file;
@@ -201,6 +328,7 @@ async function copyFiles(
   subfiles: Array<FileDescriptor>,
   forceOverwrite: ForceOverwrite,
   originalFiles: Array<FileInfo>,
+  variables?: Record<string, string>,
 ) {
   for (const subfile of subfiles) {
     const { sourcePath, targetPath } = subfile;
@@ -221,6 +349,7 @@ export async function copyScaffoldingFiles(
   target: string,
   files: Array<string | TemplateFileLocation>,
   piralInfo?: any,
+  variables?: Record<string, string>,
 ) {
   log('generalDebug_0003', `Copying the scaffolding files ...`);
   const allFiles: Array<FileDescriptor> = [];
@@ -234,7 +363,7 @@ export async function copyScaffoldingFiles(
     await extendPackageOverridesFromTemplateFragment(target, piralInfo, allFiles);
   }
 
-  await copyFiles(allFiles, ForceOverwrite.yes, []);
+  await copyFiles(allFiles, ForceOverwrite.yes, [], variables);
 }
 
 async function extendPackageOverridesFromTemplateFragment(root: string, piralInfo: any, files: Array<FileDescriptor>) {
@@ -263,31 +392,47 @@ async function extendPackageOverridesFromTemplateFragment(root: string, piralInf
   }
 }
 
+function isTemplateFileLocation(item: string | TemplateFileLocation): item is TemplateFileLocation {
+  return typeof item === 'object';
+}
+
+function tryFindPackageVersion(packageName: string): string {
+  try {
+    const { version } = require(`${packageName}/package.json`);
+    return version;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function copyPiralFiles(
   root: string,
   name: string,
-  piralInfo: any,
+  piralInfo: PiralPackageData,
   forceOverwrite: ForceOverwrite,
+  variables: Record<string, string>,
   originalFiles?: Array<FileInfo>,
 ) {
   log('generalDebug_0003', `Copying the Piral files ...`);
-  const files = await getAvailableFiles(root, name, filesTar);
+  const { files: _files } = getPiletsInfo(piralInfo);
+  const fileMap = _files.filter(isTemplateFileLocation);
+  const files = await getAvailableFiles(root, name, filesTar, fileMap);
 
   if (originalFiles === undefined) {
-    const initialFiles = await getAvailableFiles(root, name, filesOnceTar);
+    const initialFiles = await getAvailableFiles(root, name, filesOnceTar, fileMap);
     files.push(...initialFiles);
     originalFiles = [];
   }
 
   await extendPackageOverridesFromTemplateFragment(root, piralInfo, files);
-  await copyFiles(files, forceOverwrite, originalFiles);
+  await copyFiles(files, forceOverwrite, originalFiles, variables);
 }
 
-export function getPiletsInfo(piralInfo: any): PiletsInfo {
+export function getPiletsInfo(piralInfo: Partial<PiralPackageData>): PiletsInfo {
   const {
     files = [],
-    externals = [],
     scripts = {},
+    template = 'default',
     validators = {},
     devDependencies = {},
     preScaffold = '',
@@ -299,8 +444,8 @@ export function getPiletsInfo(piralInfo: any): PiletsInfo {
 
   return {
     files,
-    externals,
     scripts,
+    template,
     validators,
     devDependencies,
     preScaffold,
@@ -350,37 +495,88 @@ function checkArrayOrUndefined(obj: Record<string, any>, key: string) {
   return undefined;
 }
 
-export function findDependencyVersion(
+export async function findDependencyVersion(
   pckg: Record<string, any>,
   rootPath: string,
-  packageName: string,
+  dependency: SharedDependency,
 ): Promise<string> {
   const { devDependencies = {}, dependencies = {} } = pckg;
+  const packageName = dependency.name;
   const desiredVersion = dependencies[packageName] ?? devDependencies[packageName];
+  const [parent] = dependency.parents || [];
 
   if (desiredVersion) {
-    if (isGitPackage(desiredVersion)) {
-      return Promise.resolve(makeGitUrl(desiredVersion));
+    if (isNpmPackage(desiredVersion)) {
+      return desiredVersion;
+    } else if (isGitPackage(desiredVersion)) {
+      return makeGitUrl(desiredVersion);
     } else if (isLocalPackage(rootPath, desiredVersion)) {
-      return Promise.resolve(makeFilePath(rootPath, desiredVersion));
+      return makeFilePath(rootPath, desiredVersion);
+    }
+  }
+
+  if (parent) {
+    // in case the dependency came from another package (= parent)
+    // we should start the lookup in its directory (pnpm issue)
+    const parentPath = tryResolvePackage(parent, rootPath);
+
+    if (parentPath) {
+      rootPath = dirname(parentPath);
     }
   }
 
-  return findPackageVersion(rootPath, packageName);
+  const version = await findPackageVersion(rootPath, packageName);
+
+  if (dependency.alias) {
+    return makeNpmAlias(dependency.alias, version);
+  }
+
+  return version;
 }
 
-export async function findPackageVersion(rootPath: string, packageName: string): Promise<string> {
-  try {
-    log('generalDebug_0003', `Finding the version of "${packageName}" in "${rootPath}".`);
-    const moduleName = require.resolve(packageName, {
-      paths: [rootPath],
-    });
-    const packageJson = await findFile(moduleName, 'package.json');
-    return require(packageJson).version;
-  } catch (e) {
-    log('cannotResolveDependency_0053', packageName, rootPath);
-    return 'latest';
+export async function findPackageVersion(rootPath: string, packageName: string | Array<string>): Promise<string> {
+  const packages = Array.isArray(packageName) ? packageName : [packageName];
+
+  for (const pckg of packages) {
+    try {
+      log('generalDebug_0003', `Finding the version of "${packageName}" in "${rootPath}".`);
+      const moduleName = getModulePath(rootPath, pckg);
+      const packageJson = await findFile(moduleName, 'package.json');
+      const root = dirname(packageJson);
+      const { version } = await readJson(root, 'package.json');
+      return version;
+    } catch {}
+  }
+
+  log('cannotResolveDependency_0053', packages, rootPath);
+  return 'latest';
+}
+
+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);
+
+  if (sharedDependencies.length === 0) {
+    const allDeps = {
+      ...packageInfo.devDependencies,
+      ...packageInfo.dependencies,
+    };
+    const deps = packageInfo.pilets?.externals;
+    const externals = await makeExternals(root, allDeps, deps);
+    return externals.map((ext) => ({
+      id: ext,
+      name: ext,
+      entry: ext,
+      type: 'local',
+      ref: undefined,
+      requireId: ext,
+    }));
   }
+
+  return sharedDependencies;
 }
 
 export async function retrievePiletsInfo(entryFile: string) {
@@ -390,29 +586,51 @@ export async function retrievePiletsInfo(entryFile: string) {
     fail('entryPointDoesNotExist_0073', entryFile);
   }
 
-  const packageJson = await findFile(entryFile, 'package.json');
+  const packageJsonPath = await findFile(entryFile, packageJson);
 
-  if (!packageJson) {
+  if (!packageJsonPath) {
     fail('packageJsonMissing_0074');
   }
 
-  const packageInfo = require(packageJson);
+  const root = dirname(packageJsonPath);
+  const packageInfo = await readJson(root, packageJson);
+  const piralJsonPkg = await readJson(root, piralJson);
+  const pilets: PiletsInfo = {
+    ...getPiletsInfo(packageInfo),
+    ...piralJsonPkg.pilets,
+  };
+  const externals = await retrieveExternals(root, packageInfo);
+  const dependencies = {
+    std: packageInfo.dependencies || {},
+    dev: packageInfo.devDependencies || {},
+    peer: packageInfo.peerDependencies || {},
+  };
+  const framework = frameworkLibs.find((lib) => lib in dependencies.std || lib in dependencies.dev);
 
   return {
-    ...getPiletsInfo(packageInfo),
+    ...pilets,
+    externals,
     name: packageInfo.name,
     version: packageInfo.version,
-    dependencies: {
-      std: packageInfo.dependencies || {},
-      dev: packageInfo.devDependencies || {},
-      peer: packageInfo.peerDependencies || {},
-    },
+    framework,
+    dependencies,
     scripts: packageInfo.scripts,
     ignored: checkArrayOrUndefined(packageInfo, 'preservedDependencies'),
-    root: dirname(packageJson),
+    root,
   };
 }
 
+export function validateSharedDependencies(externals: Array<SharedDependency>) {
+  // See #591 - we should warn in case somebody shared piral packages
+  for (const external of externals) {
+    const name = external.name;
+
+    if (external.type === 'local' && name.startsWith('piral-') && name.indexOf('/') === -1) {
+      log('invalidSharedDependency_0029', name);
+    }
+  }
+}
+
 export function isValidDependency(name: string) {
   // super simple check at the moment
   // just to filter out things like "redux-saga/effects" and "@scope/redux-saga/effects"
@@ -423,21 +641,41 @@ export async function patchPiletPackage(
   root: string,
   name: string,
   version: string,
-  piralInfo: any,
+  piralInfo: PiralPackageData,
+  fromEmulator: boolean,
   newInfo?: { language: SourceLanguage; bundler: string },
 ) {
   log('generalDebug_0003', `Patching the package.json in "${root}" ...`);
-  const { externals, packageOverrides, ...info } = getPiletsInfo(piralInfo);
-  const piral = {
-    comment: 'Keep this section to use the Piral CLI.',
-    name,
-  };
+  const pkg = await getPiletPackage(root, name, version, piralInfo, fromEmulator, newInfo);
+
+  await updateExistingJson(root, packageJson, pkg);
+  log('generalDebug_0003', `Succesfully patched the package.json.`);
+
+  await updateExistingJson(root, piletJson, {
+    $schema: piletJsonSchemaUrl,
+    piralInstances: {
+      [name]: {},
+    },
+  });
+  log('generalDebug_0003', `Succesfully patched the pilet.json.`);
+}
+
+async function getPiletPackage(
+  root: string,
+  name: string,
+  version: string,
+  piralInfo: PiralPackageData,
+  fromEmulator: boolean,
+  newInfo?: { language: SourceLanguage; bundler: string },
+) {
+  const { piralCLI = { version: cliVersion } } = piralInfo;
+  const { packageOverrides, ...info } = getPiletsInfo(piralInfo);
   const piralDependencies = {
     ...piralInfo.devDependencies,
     ...piralInfo.dependencies,
   };
+  const toolVersion = piralCLI.version;
   const typeDependencies = newInfo ? getDevDependencies(newInfo.language) : {};
-  const allExternals = makeExternals(externals);
   const scripts = newInfo
     ? {
         start: 'pilet debug',
@@ -446,21 +684,8 @@ export async function patchPiletPackage(
         ...info.scripts,
       }
     : info.scripts;
-  const peerModules = [];
-  const peerDependencies = {
-    ...allExternals.reduce((deps, name) => {
-      const valid = isValidDependency(name);
-      deps[name] = valid ? '*' : undefined;
-
-      if (!valid) {
-        peerModules.push(name);
-      }
-
-      return deps;
-    }, {}),
-    [name]: `*`,
-  };
-  const devDependencies = {
+  const allExternals = await makePiletExternals(root, piralDependencies, fromEmulator, piralInfo);
+  const devDependencies: Record<string, string> = {
     ...Object.keys(typeDependencies).reduce((deps, name) => {
       deps[name] = piralDependencies[name] || typeDependencies[name];
       return deps;
@@ -470,7 +695,7 @@ export async function patchPiletPackage(
       return deps;
     }, {}),
     ...allExternals.filter(isValidDependency).reduce((deps, name) => {
-      const version = piralDependencies[name];
+      const version = piralDependencies[name] || tryFindPackageVersion(name);
 
       if (version || newInfo) {
         // set only if we have an explicit version or we are in the scaffolding case
@@ -480,36 +705,30 @@ export async function patchPiletPackage(
       return deps;
     }, {}),
     [name]: `${version || piralInfo.version}`,
+    ['piral-cli']: toolVersion,
   };
 
   if (newInfo) {
-    const bundler = newInfo.bundler;
-    devDependencies['piral-cli'] = `^${cliVersion}`;
-
-    if (bundler && bundler !== 'none') {
-      devDependencies[`piral-cli-${bundler}`] = `^${cliVersion}`;
-    }
+    await appendBundler(devDependencies, newInfo.bundler, toolVersion);
   }
 
-  const packageContent = deepMerge(packageOverrides, {
-    piral,
+  return deepMerge(packageOverrides, {
+    importmap: {
+      imports: {},
+      inherit: [name],
+    },
     devDependencies,
-    peerDependencies,
-    peerModules,
     dependencies: {
       [name]: undefined,
     },
     scripts,
   });
-
-  await updateExistingJson(root, 'package.json', packageContent);
-  log('generalDebug_0003', `Succesfully patched the package.json.`);
 }
 
 /**
  * Returns true if its an emulator package, otherwise it has to be a "raw" app shell.
  */
-export function checkAppShellPackage(appPackage: any) {
+export function checkAppShellPackage(appPackage: PiralPackageData) {
   const { piralCLI = { generated: false, version: cliVersion } } = appPackage;
 
   if (piralCLI.generated) {
@@ -521,26 +740,73 @@ export function checkAppShellPackage(appPackage: any) {
   return false;
 }
 
-export async function retrievePiletData(target: string, app?: string) {
-  const packageJson = await findFile(target, 'package.json');
+export function combinePiletExternals(
+  appShells: Array<string>,
+  peerDependencies: Record<string, string>,
+  peerModules: Array<string>,
+  importmap: Array<SharedDependency>,
+) {
+  const externals = [...Object.keys(peerDependencies), ...peerModules];
+
+  for (let i = importmap.length; i--; ) {
+    const entry = importmap[i];
+
+    // if the entry has no parents, i.e., it was explicitly mentioned in the importmap
+    // then keep it in the importmap (=> prefer the distributed approach, which will always work)
+    if (Array.isArray(entry.parents)) {
+      // only accept entry as a centrally shared dependency if the entry appears in all
+      // mentioned / referenced app shells
+      // in other cases (e.g., if one app shell does not share this) use the distributed
+      // mechanism to ensure that the dependency can also be resolved in this shell
+      if (appShells.every((app) => entry.parents.includes(app))) {
+        externals.push(entry.name);
+        importmap.splice(i, 1);
+      }
+    }
+  }
+
+  return externals;
+}
+
+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);
-  const appPackage = findPackage(
-    app || (piletPackage.piral && piletPackage.piral.name) || Object.keys(piletPackage.devDependencies),
-    target,
-  );
-  const appFile: string = appPackage && appPackage.app;
+  return dirname(packageJson);
+}
 
-  if (!appFile) {
-    fail('appInstanceInvalid_0011');
+export async function retrievePiletData(target: string, app?: string) {
+  const piletJsonPath = await findFile(target, piletJson);
+  const proposedRoot = piletJsonPath ? dirname(piletJsonPath) : target;
+  const root = await findPiletRoot(proposedRoot);
+  const piletPackage = await readJson(root, 'package.json');
+  const piletDefinition: PiletDefinition = piletJsonPath && (await readJson(proposedRoot, piletJson));
+  const appPackages = await findPiralInstances(app && [app], piletPackage, piletDefinition, target);
+  const apps: Array<AppDefinition> = [];
+
+  for (const appPackage of appPackages) {
+    const appFile: string = appPackage?.app;
+    const appRoot: string = appPackage?.root;
+    const appPort = appPackage?.port;
+
+    if (!appFile || !appRoot) {
+      fail('appInstanceInvalid_0011');
+    }
+
+    const emulator = checkAppShellPackage(appPackage);
+    apps.push({
+      appPackage,
+      appFile,
+      appRoot,
+      emulator,
+      appPort,
+    });
   }
 
-  const emulator = checkAppShellPackage(appPackage);
+  const importmap = await readImportmap(root, piletPackage);
 
   return {
     dependencies: piletPackage.dependencies || {},
@@ -548,37 +814,10 @@ export async function retrievePiletData(target: string, app?: string) {
     peerDependencies: piletPackage.peerDependencies || {},
     peerModules: piletPackage.peerModules || [],
     ignored: checkArrayOrUndefined(piletPackage, 'preservedDependencies'),
-    appFile,
+    schema: piletDefinition?.schemaVersion,
+    importmap,
+    apps,
     piletPackage,
-    appPackage,
-    emulator,
     root,
   };
 }
-
-export async function findEntryModule(entryFile: string, target: string) {
-  const entry = basename(entryFile);
-  const files = await getFileNames(target);
-  const preferences = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.esm', '.es', '.es6', '.html'];
-  const results = [];
-  log('generalDebug_0003', `Found ${files.length} potential entry points in "${target}".`);
-
-  for (const file of files) {
-    const ext = extname(file);
-    const fullPath = join(target, file);
-
-    if (file === entry) {
-      return fullPath;
-    } else if (file.replace(ext, '') === entry) {
-      const prefIndex = preferences.indexOf(ext);
-
-      if (prefIndex !== -1) {
-        results[prefIndex] = fullPath;
-      } else {
-        results[preferences.length] = fullPath;
-      }
-    }
-  }
-
-  return results.filter(Boolean).shift() || entryFile;
-}