@adonisjs/assembler 6.1.3-1 → 6.1.3-11

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2023 AdonisJS Framework
+Copyright (c) 2023 Harminder Virk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -2,7 +2,7 @@
 
 <br />
 
-[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![synk-image]][synk-url]
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![snyk-image]][snyk-url]
 
 ## Introduction
 Assembler exports the API for starting the **AdonisJS development server**, **building project for production** and **running tests** in watch mode. Assembler must be used during development only.
@@ -32,5 +32,5 @@ AdonisJS Assembler is open-sourced software licensed under the [MIT license](LIC
 [license-url]: LICENSE.md
 [license-image]: https://img.shields.io/github/license/adonisjs/ace?style=for-the-badge
 
-[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/assembler?label=Synk%20Vulnerabilities&style=for-the-badge
-[synk-url]: https://snyk.io/test/github/adonisjs/assembler?targetFile=package.json "synk"
+[snyk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/assembler?label=snyk%20Vulnerabilities&style=for-the-badge
+[snyk-url]: https://snyk.io/test/github/adonisjs/assembler?targetFile=package.json "snyk"

package/build/index.d.ts

@@ -1,2 +1,3 @@
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
+export { TestRunner } from './src/test_runner.js';

package/build/index.js

@@ -1,2 +1,11 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
+export { TestRunner } from './src/test_runner.js';

package/build/src/assets_dev_server.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" resolution-mode="require"/>
+import { type Logger } from '@poppinss/cliui';
+import type { AssetsBundlerOptions } from './types.js';
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
+export declare class AssetsDevServer {
+    #private;
+    constructor(cwd: URL, options?: AssetsBundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
+    setLogger(logger: Logger): this;
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
+    start(): void;
+    /**
+     * Stop the dev server
+     */
+    stop(): void;
+}

package/build/src/assets_dev_server.js

@@ -0,0 +1,158 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { cliui } from '@poppinss/cliui';
+import { run } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
+const ui = cliui();
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
+export class AssetsDevServer {
+    #cwd;
+    #logger = ui.logger;
+    #options;
+    #devServer;
+    /**
+     * Getting reference to colors library from logger
+     */
+    get #colors() {
+        return this.#logger.getColors();
+    }
+    constructor(cwd, options) {
+        this.#cwd = cwd;
+        this.#options = options;
+    }
+    /**
+     * Logs messages from vite dev server stdout and stderr
+     */
+    #logViteDevServerMessage(data) {
+        const dataString = data.toString();
+        const lines = dataString.split('\n');
+        /**
+         * Logging VITE ready in message with proper
+         * spaces and newlines
+         */
+        if (dataString.includes('ready in')) {
+            console.log('');
+            console.log(dataString.trim());
+            return;
+        }
+        /**
+         * Put a wrapper around vite network address log
+         */
+        if (dataString.includes('Local') && dataString.includes('Network')) {
+            const sticker = ui.sticker().useColors(this.#colors).useRenderer(this.#logger.getRenderer());
+            lines.forEach((line) => {
+                if (line.trim()) {
+                    sticker.add(line);
+                }
+            });
+            sticker.render();
+            return;
+        }
+        /**
+         * Log rest of the lines
+         */
+        lines.forEach((line) => {
+            if (line.trim()) {
+                console.log(line);
+            }
+        });
+    }
+    /**
+     * Logs messages from assets dev server stdout and stderr
+     */
+    #logAssetsDevServerMessage(data) {
+        const dataString = data.toString();
+        const lines = dataString.split('\n');
+        lines.forEach((line) => {
+            if (line.trim()) {
+                console.log(line);
+            }
+        });
+    }
+    /**
+     * Set a custom CLI UI logger
+     */
+    setLogger(logger) {
+        this.#logger = logger;
+        return this;
+    }
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
+    start() {
+        if (!this.#options?.serve) {
+            return;
+        }
+        this.#logger.info(`starting "${this.#options.driver}" dev server...`);
+        /**
+         * Create child process
+         */
+        this.#devServer = run(this.#cwd, {
+            script: this.#options.cmd,
+            /**
+             * We do not inherit the stdio for vite and encore, because in
+             * inherit mode they own the stdin and interrupts the
+             * `Ctrl + C` command.
+             */
+            stdio: 'pipe',
+            scriptArgs: this.#options.args,
+        });
+        /**
+         * Log child process messages
+         */
+        this.#devServer.stdout?.on('data', (data) => {
+            if (this.#options.driver === 'vite') {
+                this.#logViteDevServerMessage(data);
+            }
+            else {
+                this.#logAssetsDevServerMessage(data);
+            }
+        });
+        this.#devServer.stderr?.on('data', (data) => {
+            if (this.#options.driver === 'vite') {
+                this.#logViteDevServerMessage(data);
+            }
+            else {
+                this.#logAssetsDevServerMessage(data);
+            }
+        });
+        this.#devServer
+            .then((result) => {
+            this.#logger.warning(`"${this.#options.driver}" dev server closed with status code "${result.exitCode}"`);
+        })
+            .catch((error) => {
+            this.#logger.warning(`unable to connect to "${this.#options.driver}" dev server`);
+            this.#logger.fatal(error);
+        });
+    }
+    /**
+     * Stop the dev server
+     */
+    stop() {
+        if (this.#devServer) {
+            this.#devServer.removeAllListeners();
+            this.#devServer.kill('SIGKILL');
+            this.#devServer = undefined;
+        }
+    }
+}

package/build/src/bundler.d.ts

@@ -2,9 +2,18 @@
 import type tsStatic from 'typescript';
 import { type Logger } from '@poppinss/cliui';
 import type { BundlerOptions } from './types.js';
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export declare class Bundler {
     #private;
     constructor(cwd: URL, ts: typeof tsStatic, options: BundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Bundles the application to be run in production
+     */
     bundle(stopOnError?: boolean, client?: 'npm' | 'yarn' | 'pnpm'): Promise<boolean>;
 }

package/build/src/bundler.js

@@ -1,18 +1,34 @@
-import fs from 'fs-extra';
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import slash from 'slash';
 import copyfiles from 'cpy';
+import fs from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { join, relative } from 'node:path';
 import { cliui } from '@poppinss/cliui';
-import { run } from './run.js';
-import { parseConfig } from './parse_config.js';
+import { run, parseConfig } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
 const ui = cliui();
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export class Bundler {
     #cwd;
     #cwdPath;
     #ts;
     #logger = ui.logger;
     #options;
+    /**
+     * Getting reference to colors library from logger
+     */
     get #colors() {
         return this.#logger.getColors();
     }
@@ -25,9 +41,15 @@ export class Bundler {
     #getRelativeName(filePath) {
         return slash(relative(this.#cwdPath, filePath));
     }
+    /**
+     * Cleans up the build directory
+     */
     async #cleanupBuildDirectory(outDir) {
-        await fs.remove(outDir);
+        await fs.rm(outDir, { recursive: true, force: true, maxRetries: 5 });
     }
+    /**
+     * Runs assets bundler command to build assets.
+     */
     async #buildAssets() {
         const assetsBundler = this.#options.assets;
         if (!assetsBundler?.serve) {
@@ -46,6 +68,9 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Runs tsc command to build the source.
+     */
     async #runTsc(outDir) {
         try {
             await run(this.#cwd, {
@@ -59,9 +84,12 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Copy files to destination directory
+     */
     async #copyFiles(files, outDir) {
         try {
-            await copyfiles(files, outDir, { cwd: this.#cwdPath });
+            await copyfiles(files, outDir, { parents: true, cwd: this.#cwdPath });
         }
         catch (error) {
             if (!error.message.includes("the file doesn't exist")) {
@@ -69,20 +97,30 @@ export class Bundler {
             }
         }
     }
+    /**
+     * Copy meta files to the output directory
+     */
     async #copyMetaFiles(outDir, additionalFilesToCopy) {
         const metaFiles = (this.#options.metaFiles || [])
             .map((file) => file.pattern)
             .concat(additionalFilesToCopy);
         await this.#copyFiles(metaFiles, outDir);
     }
+    /**
+     * Copies .adonisrc.json file to the destination
+     */
     async #copyAdonisRcFile(outDir) {
-        const existingContents = await fs.readJSON(join(this.#cwdPath, '.adonisrc.json'));
+        const existingContents = JSON.parse(await fs.readFile(join(this.#cwdPath, '.adonisrc.json'), 'utf-8'));
         const compiledContents = Object.assign({}, existingContents, {
             typescript: false,
             lastCompiledAt: new Date().toISOString(),
         });
-        await fs.outputJSON(join(outDir, '.adonisrc.json'), compiledContents, { spaces: 2 });
+        await fs.mkdir(outDir, { recursive: true });
+        await fs.writeFile(join(outDir, '.adonisrc.json'), JSON.stringify(compiledContents, null, 2) + '\n');
     }
+    /**
+     * Returns the lock file name for a given packages client
+     */
     #getClientLockFile(client) {
         switch (client) {
             case 'npm':
@@ -93,6 +131,9 @@ export class Bundler {
                 return 'pnpm-lock.yaml';
         }
     }
+    /**
+     * Returns the installation command for a given packages client
+     */
     #getClientInstallCommand(client) {
         switch (client) {
             case 'npm':
@@ -103,24 +144,46 @@ export class Bundler {
                 return 'pnpm i --prod';
         }
     }
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger) {
         this.#logger = logger;
         return this;
     }
+    /**
+     * Bundles the application to be run in production
+     */
     async bundle(stopOnError = true, client = 'npm') {
+        /**
+         * Step 1: Parse config file to get the build output directory
+         */
         const config = parseConfig(this.#cwd, this.#ts);
         if (!config) {
             return false;
         }
+        /**
+         * Step 2: Cleanup existing build directory (if any)
+         */
         const outDir = config.options.outDir || fileURLToPath(new URL('build/', this.#cwd));
         this.#logger.info('cleaning up output directory', { suffix: this.#getRelativeName(outDir) });
         await this.#cleanupBuildDirectory(outDir);
+        /**
+         * Step 3: Build frontend assets
+         */
         if (!(await this.#buildAssets())) {
             return false;
         }
+        /**
+         * Step 4: Build typescript source code
+         */
         this.#logger.info('compiling typescript source', { suffix: 'tsc' });
         const buildCompleted = await this.#runTsc(outDir);
         await this.#copyFiles(['ace.js'], outDir);
+        /**
+         * Remove incomplete build directory when tsc build
+         * failed and stopOnError is set to true.
+         */
         if (!buildCompleted && stopOnError) {
             await this.#cleanupBuildDirectory(outDir);
             const instructions = ui
@@ -132,13 +195,22 @@ export class Bundler {
             this.#logger.logError(instructions.prepare());
             return false;
         }
+        /**
+         * Step 5: Copy meta files to the build directory
+         */
         const pkgFiles = ['package.json', this.#getClientLockFile(client)];
         this.#logger.info('copying meta files to the output directory');
         await this.#copyMetaFiles(outDir, pkgFiles);
+        /**
+         * Step 6: Copy .adonisrc.json file to the build directory
+         */
         this.#logger.info('copying .adonisrc.json file to the output directory');
         await this.#copyAdonisRcFile(outDir);
         this.#logger.success('build completed');
         this.#logger.log('');
+        /**
+         * Next steps
+         */
         ui.instructions()
             .useRenderer(this.#logger.getRenderer())
             .heading('Run the following commands to start the server in production')

package/build/src/dev_server.d.ts

@@ -2,13 +2,45 @@
 import type tsStatic from 'typescript';
 import { type Logger } from '@poppinss/cliui';
 import type { DevServerOptions } from './types.js';
+/**
+ * Exposes the API to start the development. Optionally, the watch API can be
+ * used to watch for file changes and restart the development server.
+ *
+ * The Dev server performs the following actions
+ *
+ * - Assigns a random PORT, when PORT inside .env file is in use
+ * - Uses tsconfig.json file to collect a list of files to watch.
+ * - Uses metaFiles from .adonisrc.json file to collect a list of files to watch.
+ * - Restart HTTP server on every file change.
+ */
 export declare class DevServer {
     #private;
     constructor(cwd: URL, options: DevServerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Add listener to get notified when dev server is
+     * closed
+     */
     onClose(callback: (exitCode: number) => any): this;
+    /**
+     * Add listener to get notified when dev server exists
+     * with an error
+     */
     onError(callback: (error: any) => any): this;
+    /**
+     * Close watchers and running child processes
+     */
+    close(): Promise<void>;
+    /**
+     * Start the development server
+     */
     start(): Promise<void>;
+    /**
+     * Start the development server in watch mode
+     */
     startAndWatch(ts: typeof tsStatic, options?: {
         poll: boolean;
     }): Promise<void>;