piral-cli 1.0.0-pre.2217 → 1.0.0

package/src/common/clients/rush.ts

@@ -0,0 +1,118 @@
+import { dirname, relative, resolve } from 'path';
+import { log } from '../log';
+import { findFile, readText, writeText } from '../io';
+import { jju } from '../../external';
+import { runCommand } from '../scripts';
+import { MemoryStream } from '../MemoryStream';
+
+// Helpers:
+const rushJson = 'rush.json';
+
+function runRushProcess(args: Array<string>, target: string, output?: NodeJS.WritableStream) {
+  log('generalDebug_0003', 'Starting the Rush process ...');
+  const cwd = resolve(process.cwd(), target);
+  return runCommand('rush', args, cwd, output);
+}
+
+function convert(flags: Array<string>) {
+  return flags.map((flag) => {
+    switch (flag) {
+      case '--save-exact':
+        // discard as this may lead to problems
+        return '';
+      case '--save-dev':
+        return '--dev';
+      case '--no-save':
+        // unfortunately no
+        return '';
+      default:
+        return flag;
+    }
+  });
+}
+
+// Client interface functions:
+
+export async function installDependencies(target = '.', ...flags: Array<string>) {
+  const ms = new MemoryStream();
+  await runRushProcess(['update', ...convert(flags)], target, ms);
+  log('generalDebug_0003', `Rush install dependencies result: ${ms.value}`);
+  return ms.value;
+}
+
+export async function uninstallPackage(packageRef: string, target = '.', ...flags: Array<string>) {
+  const ms = new MemoryStream();
+  await runRushProcess(['remove', packageRef, ...convert(flags)], target, ms);
+  log('generalDebug_0003', `Rush remove package result: ${ms.value}`);
+  return ms.value;
+}
+
+export async function installPackage(packageRef: string, target = '.', ...flags: Array<string>) {
+  const ms = new MemoryStream();
+  await runRushProcess(['add', '--package', packageRef, ...convert(flags)], target, ms);
+  log('generalDebug_0003', `Rush add package result: ${ms.value}`);
+  return ms.value;
+}
+
+export async function detectClient(root: string, stopDir = resolve(root, '/')) {
+  return !!(await findFile(root, rushJson, stopDir));
+}
+
+export async function initProject(packageName: string, target: string) {
+  const rushPath = await findFile(target, rushJson);
+
+  if (!rushPath) {
+    throw new Error(
+      `Could not find the "${rushJson}" from "${target}". Sure you want to create the project in the right directory?`,
+    );
+  }
+
+  const rushDir = dirname(rushPath);
+  const rushContent = await readText(rushDir, rushJson);
+  const rushData = jju.parse(rushContent);
+  const projectFolder = relative(rushDir, target);
+
+  if (!Array.isArray(rushData.projects)) {
+    rushData.projects = [];
+  }
+
+  rushData.projects.push({
+    packageName,
+    projectFolder,
+  });
+
+  await writeText(
+    rushDir,
+    rushJson,
+    jju.update(rushContent, rushData, {
+      mode: 'cjson',
+      indent: 2,
+    }),
+  );
+}
+
+export async function isProject(root: string, packageRef: string) {
+  const details = await listProjects(root);
+
+  if (typeof details === 'object' && Array.isArray(details?.projects)) {
+    return details?.projects?.some((p) => p.name === packageRef) ?? false;
+  }
+
+  return false;
+}
+
+// Functions to exclusively use from rush client:
+
+export async function listProjects(target: string) {
+  const ms = new MemoryStream();
+
+  try {
+    await runRushProcess(['list', '--json'], target, ms);
+  } catch (e) {
+    log('generalDebug_0003', `rush list error: ${e}`);
+    return {};
+  }
+
+  log('generalDebug_0003', `rush list project result: ${ms.value}`);
+  return JSON.parse(ms.value);
+}

package/src/common/clients/yarn.ts

@@ -1,10 +1,13 @@
 import { resolve } from 'path';
 import { log } from '../log';
+import { findFile } from '../io';
 import { runCommand } from '../scripts';
 import { MemoryStream } from '../MemoryStream';
 
+// Helpers:
+
 function runYarnProcess(args: Array<string>, target: string, output?: NodeJS.WritableStream) {
-  log('generalDebug_0003', 'Starting the Yarn process ...');
+  log('generalDebug_0003', 'Starting the Yarn Classic process ...');
   const cwd = resolve(process.cwd(), target);
   return runCommand('yarn', args, cwd, output);
 }
@@ -12,6 +15,8 @@ function runYarnProcess(args: Array<string>, target: string, output?: NodeJS.Wri
 function convert(flags: Array<string>) {
   return flags.map((flag) => {
     switch (flag) {
+      case '--save-exact':
+        return '--exact';
       case '--save-dev':
         return '--dev';
       case '--no-save':
@@ -23,16 +28,57 @@ function convert(flags: Array<string>) {
   });
 }
 
+// Client interface functions:
+
 export async function installDependencies(target = '.', ...flags: Array<string>) {
   const ms = new MemoryStream();
   await runYarnProcess(['install', ...convert(flags)], target, ms);
-  log('generalDebug_0003', `Yarn install dependencies result: ${ms.value}`);
+  log('generalDebug_0003', `Yarn Classic install dependencies result: ${ms.value}`);
+  return ms.value;
+}
+
+export async function uninstallPackage(packageRef: string, target = '.', ...flags: Array<string>) {
+  const ms = new MemoryStream();
+  await runYarnProcess(['remove', packageRef, ...convert(flags)], target, ms);
+  log('generalDebug_0003', `Yarn Classic remove package result: ${ms.value}`);
   return ms.value;
 }
 
 export async function installPackage(packageRef: string, target = '.', ...flags: Array<string>) {
   const ms = new MemoryStream();
   await runYarnProcess(['add', packageRef, ...convert(flags)], target, ms);
-  log('generalDebug_0003', `Yarn install package result: ${ms.value}`);
+  log('generalDebug_0003', `Yarn Classic add package result: ${ms.value}`);
   return ms.value;
 }
+
+export async function detectClient(root: string, stopDir = resolve(root, '/')) {
+  return !!(await findFile(root, 'yarn.lock', stopDir));
+}
+
+export async function initProject(projectName: string, target: string) {}
+
+export async function isProject(root: string, packageRef: string) {
+  const details = await listProjects(root);
+
+  if (typeof details === 'object') {
+    return typeof details?.[packageRef]?.location === 'string';
+  }
+
+  return false;
+}
+
+// Functions to exclusively use from yarn client:
+
+export async function listProjects(target: string) {
+  const ms = new MemoryStream();
+
+  try {
+    await runYarnProcess(['workspaces', 'info'], target, ms);
+  } catch (e) {
+    log('generalDebug_0003', `yarn workspaces error: ${e}`);
+    return {};
+  }
+
+  log('generalDebug_0003', `yarn workspaces result: ${ms.value}`);
+  return JSON.parse(ms.value);
+}

package/src/common/compatibility.ts

@@ -1,9 +1,16 @@
 import { findCompatVersion, compatVersion, cliVersion } from './info';
 import { findPackageVersion } from './package';
+import { frameworkLibs } from './constants';
 import { log } from './log';
 
 export function checkAppShellCompatibility(piralVersion: string) {
   log('generalDebug_0003', `Checking compatibility ...`);
+
+  if (!piralVersion) {
+    log('appShellMaybeIncompatible_0102', cliVersion);
+    return false;
+  }
+
   const compatible = findCompatVersion(piralVersion);
   log('generalDebug_0003', `Used versions: "${compatible}" and "${compatVersion}".`);
 
@@ -17,7 +24,7 @@ export function checkAppShellCompatibility(piralVersion: string) {
 
 export async function checkCliCompatibility(root: string) {
   log('generalDebug_0003', `Checking compatibility ...`);
-  const piralVersion = await findPackageVersion(root, 'piral-base');
+  const piralVersion = await findPackageVersion(root, frameworkLibs);
   const compatible = findCompatVersion(piralVersion);
   log('generalDebug_0003', `Used versions: "${compatible}" and "${compatVersion}".`);
 

package/src/common/config.ts

@@ -1,51 +1,86 @@
+import { defaultRegistry } from './constants';
 import { rc } from '../external';
-import { NpmClientType } from '../types';
+import { SourceLanguage, NpmClientType, PiletSchemaVersion } from '../types';
 
 export interface PiralCliConfig {
-  apiKey?: string;
-  apiKeys?: Record<string, string>;
-  url?: string;
-  cert?: string;
-  npmClient?: NpmClientType;
-  bundler?: string;
-  piletApi?: string;
-  validators?: Record<string, any>;
-}
-
-export const config: PiralCliConfig = rc('piral', {
   /**
    * Key to be used for all servers in case there is
    * no specialized key in apiKeys specified.
    */
-  apiKey: undefined,
+  apiKey?: string;
   /**
-   * Hostname to API key specifications.
+   * Feed URL to API key specifications.
    */
-  apiKeys: {},
+  apiKeys?: Record<string, string>;
   /**
    * URL to be used for publishing a pilet in case
    * there is no specialized key in url specified.
    */
-  url: undefined,
+  url?: string;
   /**
    * Path to a custom certificate file.
    */
-  cert: undefined,
+  cert?: string;
   /**
    * Selects the default npm client to use.
    */
-  npmClient: 'npm',
+  npmClient?: NpmClientType;
   /**
    * Selects the default bundler to use, if
    * none given and found.
    */
-  bundler: 'webpack',
+  bundler?: string;
   /**
    * Selects the default pilet API path to use.
    */
-  piletApi: '/$pilet-api',
+  piletApi?: string;
   /**
    * Sets the validators configuration for a Piral instance.
    */
-  validators: {},
-});
+  validators?: Record<string, any>;
+  /**
+   * Sets the schema version to be used for pilets.
+   */
+  schemaVersion?: PiletSchemaVersion;
+  /**
+   * Automatically open the browser.
+   */
+  openBrowser?: boolean;
+  /**
+   * Port number.
+   */
+  port?: number;
+  /**
+   * Template language.
+   */
+  language?: SourceLanguage;
+  /**
+   * Host name.
+   */
+  host?: string;
+  /**
+   * Npm registry.
+   */
+  registry?: string;
+}
+
+export const config: PiralCliConfig = rc(
+  'piral',
+  {
+    apiKey: undefined,
+    apiKeys: {},
+    url: undefined,
+    cert: undefined,
+    npmClient: 'npm' as const,
+    bundler: 'webpack5' as const,
+    piletApi: '/$pilet-api',
+    validators: {},
+    schemaVersion: 'v2' as const,
+    openBrowser: false,
+    port: 1234,
+    language: 'ts' as const,
+    host: 'localhost',
+    registry: defaultRegistry,
+  },
+  {},
+);

package/src/common/constants.ts

@@ -1,10 +1,28 @@
 export const defaultRegistry = 'https://registry.npmjs.org/';
 export const filesTar = 'files';
+export const packageJson = 'package.json';
+export const piralJson = 'piral.json';
+export const piletJson = 'pilet.json';
 export const filesOnceTar = 'files_once';
-export const piralBaseRoot = 'piral-base/lib/types';
+export const piralBaseRoot = 'piral-base/package.json';
+export const defaultSchemaVersion = 'v2';
+export const frameworkLibs = ['piral' as const, 'piral-core' as const, 'piral-base' as const];
+export const piletJsonSchemaUrl = 'https://docs.piral.io/schemas/pilet-v0.json';
+export const piralJsonSchemaUrl = 'https://docs.piral.io/schemas/piral-v0.json';
 export const entryModuleExtensions = ['.ts', '.tsx', '.js', '.jsx'];
-export const declarationEntryExtensions = ['.html', ...entryModuleExtensions];
-export const coreExternals = [
+export const bundlerNames = [
+  'esbuild' as const,
+  'parcel' as const,
+  'parcel2' as const,
+  'rollup' as const,
+  'rspack' as const,
+  'webpack' as const,
+  'webpack5' as const,
+  'vite' as const,
+  'xbuild' as const,
+];
+export const declarationEntryExtensions = ['.html', '.pug', ...entryModuleExtensions];
+export const legacyCoreExternals = [
   '@dbeining/react-atom',
   '@libre/atom',
   'history',

package/src/common/declaration.ts

@@ -1,28 +1,61 @@
-import { generateDeclaration } from 'dets';
+import { DeclOptions, generateDeclaration, createExcludePlugin, Logger } from 'dets';
 import { dirname, basename, resolve, extname } from 'path';
 import { progress, log, logWarn, logVerbose, logInfo } from './log';
-import { makeExternals } from './npm';
 import { ForceOverwrite } from './enums';
-import { retrievePiralRoot, retrievePiletsInfo } from './package';
+import { retrievePiralRoot, retrievePiletsInfo, flattenExternals, validateSharedDependencies } from './package';
 import { entryModuleExtensions, piralBaseRoot } from './constants';
 import { readText, getEntryFiles, matchFiles, createFileIfNotExists } from './io';
+import { getModulePath } from '../external';
 import { LogLevels } from '../types';
 
-function findPiralBaseApi(root: string) {
+function findPiralBaseRoot(root: string, framework: string) {
+  const piralJson = `${framework}/package.json`;
+
+  if (piralJson !== piralBaseRoot) {
+    try {
+      const packageJsonPath = getModulePath(root, piralJson);
+      return dirname(packageJsonPath);
+    } catch {}
+  }
+
+  return root;
+}
+
+function findPiralBaseApi(root: string, framework: string) {
+  // for some package managers, e.g., pnpm we need to first go into
+  // some specifics before being able to retrieve "piral-base"
+  const baseRoot = findPiralBaseRoot(root, framework);
+
   try {
-    return require
-      .resolve(piralBaseRoot, {
-        paths: [root],
-      })
-      ?.replace(/\.js$/, '.d.ts');
-  } catch {
-    return undefined;
+    const packageJsonPath = getModulePath(baseRoot, piralBaseRoot);
+    const projectDir = dirname(packageJsonPath);
+    const project = require(packageJsonPath);
+    // By default support for piral-base < 0.15
+    const { piletApiTypings = 'lib/types.d.ts' } = project;
+
+    return [
+      {
+        file: resolve(projectDir, piletApiTypings),
+        name: 'PiletApi',
+      },
+    ];
+  } catch (err) {
+    log('generalError_0002', `Could not find the root API of "piral-base" from "${root}": ${err}`);
+    return [];
   }
 }
 
 function findDeclaredTypings(root: string) {
   try {
-    const { typings } = require(resolve(root, 'package.json'));
+    const { typings, extraTypes } = require(resolve(root, 'package.json'));
+
+    if (extraTypes) {
+      if (typeof extraTypes === 'string') {
+        return [resolve(root, extraTypes)];
+      } else if (Array.isArray(extraTypes)) {
+        return extraTypes.filter((types) => typeof types === 'string').map((types) => resolve(root, types));
+      }
+    }
 
     if (typings) {
       return [resolve(root, typings)];
@@ -54,7 +87,68 @@ async function getEntryModules(entryFiles: string) {
   return [entryFiles];
 }
 
-export async function createDeclaration(
+function createLogger(): Logger {
+  return {
+    error(message) {
+      throw new Error(message);
+    },
+    info(message) {
+      logInfo(message);
+    },
+    verbose(message) {
+      logVerbose(message);
+    },
+    warn(message) {
+      logWarn(message);
+    },
+  };
+}
+
+async function createDeclarationFile(
+  options: DeclOptions,
+  source: string,
+  target: string,
+  forceOverwrite: ForceOverwrite,
+) {
+  progress('Bundling declaration file ...');
+
+  try {
+    const result = generateDeclaration(options);
+
+    progress('Writing declaration file ...');
+    await createFileIfNotExists(target, 'index.d.ts', result, forceOverwrite);
+  } catch (ex) {
+    log('declarationCouldNotBeGenerated_0076', source, ex);
+  }
+}
+
+export async function createPiletDeclaration(
+  name: string,
+  root: string,
+  entry: string,
+  allowedImports: Array<string>,
+  target: string,
+  forceOverwrite: ForceOverwrite,
+  logLevel: LogLevels,
+) {
+  const files = await getAllFiles([entry]);
+  const types = findDeclaredTypings(root);
+  const options: DeclOptions = {
+    name,
+    root,
+    files,
+    types: [...types, ...files],
+    plugins: [createExcludePlugin([name])],
+    apis: [],
+    noModuleDeclaration: true,
+    imports: allowedImports,
+    logLevel,
+    logger: createLogger(),
+  };
+  return await createDeclarationFile(options, root, target, forceOverwrite);
+}
+
+export async function createPiralDeclaration(
   baseDir: string,
   entry: string,
   target: string,
@@ -63,46 +157,26 @@ export async function createDeclaration(
 ) {
   progress('Reading configuration ...');
   const entryFiles = await retrievePiralRoot(baseDir, entry);
-  const { name, root, externals } = await retrievePiletsInfo(entryFiles);
-  const allowedImports = makeExternals(externals);
+  const { name, root, externals, framework } = await retrievePiletsInfo(entryFiles);
   const entryModules = await getEntryModules(entryFiles);
   const files = await getAllFiles(entryModules);
+  const options: DeclOptions = {
+    name,
+    root,
+    files,
+    types: findDeclaredTypings(root),
+    apis: findPiralBaseApi(root, framework),
+    noModuleDeclaration: true,
+    imports: flattenExternals(externals),
+    logLevel,
+    logger: createLogger(),
+  };
 
-  progress('Bundling declaration file ...');
-
-  try {
-    const result = generateDeclaration({
-      name,
-      root,
-      files,
-      types: findDeclaredTypings(root),
-      apis: [
-        {
-          file: findPiralBaseApi(root),
-          name: 'PiletApi',
-        },
-      ],
-      imports: allowedImports,
-      logLevel,
-      logger: {
-        error(message) {
-          throw new Error(message);
-        },
-        info(message) {
-          logInfo(message);
-        },
-        verbose(message) {
-          logVerbose(message);
-        },
-        warn(message) {
-          logWarn(message);
-        },
-      },
-    });
+  validateSharedDependencies(externals);
 
-    progress('Writing declaration file ...');
-    await createFileIfNotExists(target, 'index.d.ts', result, forceOverwrite);
-  } catch (ex) {
-    log('declarationCouldNotBeGenerated_0076', baseDir, ex);
+  if (options.apis.length) {
+    return await createDeclarationFile(options, baseDir, target, forceOverwrite);
   }
+
+  log('declarationCouldNotBeGenerated_0076', baseDir, 'The main Pilet API interface could not be found.');
 }

package/src/common/emoji.ts

@@ -2,5 +2,14 @@ import { isWindows } from './info';
 
 const supportsEmoji = !isWindows || process.env.TERM === 'xterm-256color';
 
+// see https://unicode.org/emoji/charts/full-emoji-list.html
 export const liveIcon = supportsEmoji ? '🚀 ' : '>';
 export const settingsIcon = supportsEmoji ? '🔧 ' : '>';
+export const cactusIcon = supportsEmoji ? '👻 ' : '>';
+export const clapIcon = supportsEmoji ? '👏 ' : '^';
+export const sparklesIcon = supportsEmoji ? '✨ ' : '>';
+export const unicornIcon = supportsEmoji ? '🦄 ' : '>';
+export const caterpillerIcon = supportsEmoji ? '🐛 ' : '+';
+export const butterflyIcon = supportsEmoji ? '🦋 ' : '+';
+export const zapIcon = supportsEmoji ? '⚡ ' : '>';
+export const rainbowIcon = supportsEmoji ? '🌈 ' : '~';