@travetto/pack 8.0.0-alpha.9 → 8.0.1

package/README.md

@@ -13,7 +13,7 @@ npm install @travetto/pack
 yarn add @travetto/pack
 ```
 
-This module provides the necessary tools to produce deliverable output for [Travetto](https://travetto.dev) based projects.  The main interaction with this module is through the command line interface, and the operations it provides.  Under the covers, the code bundling is performed by [Rollup](https://rollupjs.org/), with specific configuration to support the frameworks runtime expectations. 
+This module provides the necessary tools to produce deliverable output for [Travetto](https://travetto.dev) based projects. The main interaction with this module is through the command line interface, and the operations it provides. Under the covers, the code bundling is performed by [Rollup](https://rollupjs.org/), with specific configuration to support the frameworks runtime expectations. 
 
 There are three primary cli commands for packing your code:
    *  pack
@@ -22,12 +22,18 @@ There are three primary cli commands for packing your code:
 
 ## CLI - pack
 
-**Terminal: Pack usage**
+**Terminal: Help for pack**
 ```bash
 $ trv pack --help
 
 Usage: pack [options] [args...:string]
 
+Description:
+  Build a standard module package artifact.
+
+  This base command produces the default packaged output and serves as the
+  common entry point for module packaging workflows.
+
 Options:
   -b, --buildDir <string>              Workspace for building (default: "/tmp/<temp-folder>")
   --clean, --no-clean                  Clean workspace (default: true)
@@ -46,6 +52,8 @@ Options:
   -np, --npm-package <string>          External NPM Packages (default: [])
   -m, --module <module>                Module to run for
   --help                               display help for command
+
+Examples:
 ```
 
 This command line operation will compile your project, and produce a ready to use workspace as a deliverable. Additionally, you can pass in a file to the `eject-file` flag that will allow for a script to be produced (base on the host operating system). 
@@ -53,7 +61,7 @@ This command line operation will compile your project, and produce a ready to us
 Specific to this CLI command, the `output` field determines where the final folder is written that contains all the compiled source.
 
 ### Entry Point Configuration
-Every application requires an entry point to determine execution flow (and in [Rollup](https://rollupjs.org/)'s case, tree-shaking as well.).  By default the [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") acts as the entry point.  This bypasses the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") intentionally, as the compiler is not available at runtime. 
+Every application requires an entry point to determine execution flow (and in [Rollup](https://rollupjs.org/)'s case, tree-shaking as well.). By default the [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") acts as the entry point. This bypasses the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") intentionally, as the compiler is not available at runtime. 
 
 Within the command line, the `args` are positional arguments that will be passed to the entry point on application run.
 
@@ -77,23 +85,29 @@ And this entry point would be what is executed by [docker](https://www.docker.co
 ### General Packing Operations
 Every [Pack](https://github.com/travetto/travetto/tree/main/module/pack#readme "Code packing utilities") operation extends from the base command, and that provides some consistent operations that run on every packing command.
    *  `clean` - Empties workspace before beginning, controlled by the `--clean` flag, defaults to on
-   *  `writeEnv` - Writes the .env.js files that includes the necessary details to start the application.  This is primarily to identify the location of the manifest file needed to run.
+   *  `writeEnv` - Writes the .env.js files that includes the necessary details to start the application. This is primarily to identify the location of the manifest file needed to run.
    *  `writePackageJson` - Generates the [Package JSON](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) with the appropriate module type ([CommonJS](https://nodejs.org/api/modules.html) or [Ecmascript Module](https://nodejs.org/api/esm.html)) for interpreting plain `.js` files
    *  `writeEntryScript` - Create the entry script based on the `--entry-command`, `args`
    *  `copyResources` - Will pull in local `resources/**` files into the final output
-   *  `primeAppCache` - Runs `trv run` to ensure the appropriate files are generated to allow for running the application.  This only applies if the entry point is equivalent to `trv run`
-   *  `writeManifest` - Produces the `production`-ready manifest that is used at runtime.  Removes all devDependencies from the manifest.json
-   *  `bundle` - Invokes [Rollup](https://rollupjs.org/) with the appropriate file set to produce a single output .js file.  Depending on the module type ([CommonJS](https://nodejs.org/api/modules.html) or [Ecmascript Module](https://nodejs.org/api/esm.html)) the build process differs to handle the dynamic loading that application does at runtime.
+   *  `primeAppCache` - Runs `trv run` to ensure the appropriate files are generated to allow for running the application. This only applies if the entry point is equivalent to `trv run`
+   *  `writeManifest` - Produces the `production`-ready manifest that is used at runtime. Removes all devDependencies from the manifest.json
+   *  `bundle` - Invokes [Rollup](https://rollupjs.org/) with the appropriate file set to produce a single output .js file. Depending on the module type ([CommonJS](https://nodejs.org/api/modules.html) or [Ecmascript Module](https://nodejs.org/api/esm.html)) the build process differs to handle the dynamic loading that application does at runtime.
 
 ## CLI - pack:zip
-This command is nearly identical to the standard `pack` operation, except for the `output` flag.  In this scenario, the `output` flag determines the location and name of the final zip file.
+This command is nearly identical to the standard `pack` operation, except for the `output` flag. In this scenario, the `output` flag determines the location and name of the final zip file.
 
-**Terminal: Pack:zip usage**
+**Terminal: Help for pack:zip**
 ```bash
 $ trv pack:zip --help
 
 Usage: pack:zip [options] [args...:string]
 
+Description:
+  Build a deployable zip artifact using the standard pack pipeline.
+
+  This command runs base packing operations and then compresses the generated
+  output into a single archive file.
+
 Options:
   -b, --buildDir <string>              Workspace for building (default: "/tmp/<temp-folder>")
   --clean, --no-clean                  Clean workspace (default: true)
@@ -112,17 +126,25 @@ Options:
   -np, --npm-package <string>          External NPM Packages (default: [])
   -m, --module <module>                Module to run for
   --help                               display help for command
+
+Examples:
 ```
 
 ## CLI - pack:docker
 This command starts off identical to the standard `pack` operation, but it contains a few additional flags, and ultimately a few additional operations to support creating of the final [docker](https://www.docker.com/community-edition) image.
 
-**Terminal: Pack:docker usage**
+**Terminal: Help for pack:docker**
 ```bash
 $ trv pack:docker --help
 
 Usage: pack:docker [options] [args...:string]
 
+Description:
+  Build container-ready artifacts and optionally publish Docker images.
+
+  Extends the core pack pipeline with Dockerfile generation and image build/
+  push operations, including runtime user and registry customization.
+
 Options:
   -b, --buildDir <string>                Workspace for building (default: "/tmp/<temp-folder>")
   --clean, --no-clean                    Clean workspace (default: true)
@@ -141,7 +163,7 @@ Options:
   -np, --npm-package <string>            External NPM Packages (default: [])
   -m, --module <module>                  Module to run for
   -df, --docker-factory <string>         Docker Factory source (default: "@travetto/pack/support/pack.dockerfile.ts")
-  -di, --docker-image <string>           Docker Image to extend (default: "node:25-alpine")
+  -di, --docker-image <string>           Docker Image to extend (default: "node:26-alpine")
   -dn, --docker-name <string>            Docker Image Name (default: "<module>")
   -ru, --runtime-user <string>           Docker Runtime user
   -rp, --runtime-package <string>        Docker Runtime Packages (default: [])
@@ -152,18 +174,20 @@ Options:
   -db, --docker-build-platform <string>  Docker Build Platform
   -dr, --docker-registry <string>        Docker Registry
   --help                                 display help for command
+
+Examples:
 ```
 
-The additional flags provided are allow for specifying the base image, the final docker image name (and tags), and which registry to push to (if  any).  Additionally, there are flags for exposing which ports the image should expect to open as well.   When using the `--eject-file`  flag, the output script will produce the entire Dockerfile output inline, so that it can be easily modified as needed. 
+The additional flags provided are allow for specifying the base image, the final docker image name (and tags), and which registry to push to (if any). Additionally, there are flags for exposing which ports the image should expect to open as well. When using the `--eject-file` flag, the output script will produce the entire Dockerfile output inline, so that it can be easily modified as needed. 
 
 In addition to the standard operations, this command adds the following steps:
    *  `writeDockerFile` - Generate the docker file contents
    *  `pullDockerBaseImage` - Pull base image, to ensure its available and primed
    *  `buildDockerContainer` - Build final container
-   *  `pushDockerContainer` - Push container with appropriate tags.  Only applies if `--docker-push` is specified
+   *  `pushDockerContainer` - Push container with appropriate tags. Only applies if `--docker-push` is specified
 
 ## Ejected File
-As indicated, any of the pack operations can be ejected, and produce an output that can be run independent of the pack command.  This is helpful when integrating with more complicated build processes.
+As indicated, any of the pack operations can be ejected, and produce an output that can be run independent of the pack command. This is helpful when integrating with more complicated build processes.
 
 **Terminal: Sample Ejected File**
 ```bash
@@ -244,21 +268,21 @@ cd $TRV_OUT
 node $REPO_ROOT/node_modules/.bin/rollup -c $TRV_OUT/node_modules/@travetto/pack/support/rollup/build.js
 cd $ROOT
 
-# Pulling Docker Base Image node:25-alpine 
+# Pulling Docker Base Image node:26-alpine 
 
-echo "Pulling Docker Base Image node:25-alpine"
+echo "Pulling Docker Base Image node:26-alpine"
 
-docker pull node:25-alpine
+docker pull node:26-alpine
 
-# Detected Image OS node:25-alpine as alpine 
+# Detected Image OS node:26-alpine as alpine 
 
-echo "Detected Image OS node:25-alpine as alpine"
+echo "Detected Image OS node:26-alpine as alpine"
 
 # Generating Docker File $DIST/Dockerfile @travetto/pack/support/pack.dockerfile.ts 
 
 echo "Generating Docker File $DIST/Dockerfile @travetto/pack/support/pack.dockerfile.ts"
 
-echo "FROM node:25-alpine" > $DIST/Dockerfile
+echo "FROM node:26-alpine" > $DIST/Dockerfile
 echo "RUN addgroup -g 2000 app && adduser -D -G app -u 2000 app" >> $DIST/Dockerfile
 echo "RUN mkdir /app && chown app:app /app" >> $DIST/Dockerfile
 echo "COPY --chown=\"app:app\" . /app" >> $DIST/Dockerfile

package/__index__.ts

@@ -1,2 +1,2 @@
-export type { CommonPackConfig, DockerPackFactory, DockerPackConfig } from './src/types.ts';
-export { PackConfigUtil } from './src/config-util.ts';
+export { PackConfigUtil } from './src/config-util.ts';
+export type { CommonPackConfig, DockerPackConfig, DockerPackFactory } from './src/types.ts';

package/package.json

@@ -1,41 +1,44 @@
 {
   "name": "@travetto/pack",
-  "version": "8.0.0-alpha.9",
-  "type": "module",
+  "version": "8.0.1",
   "description": "Code packing utilities",
   "keywords": [
-    "travetto",
-    "typescript",
+    "docker",
     "packing",
-    "docker"
+    "travetto",
+    "typescript"
   ],
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/pack"
   },
-  "main": "__index__.ts",
   "files": [
     "__index__.ts",
     "src",
     "support"
   ],
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/pack"
+  "type": "module",
+  "main": "__index__.ts",
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "@travetto/runtime": "^8.0.0-alpha.6",
-    "@travetto/terminal": "^8.0.0-alpha.6",
-    "rollup": "^4.59.0"
+    "@travetto/runtime": "^8.0.1",
+    "@travetto/terminal": "^8.0.1",
+    "rollup": "^4.63.1"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.11"
+    "@travetto/cli": "^8.0.1"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {
@@ -47,8 +50,5 @@
     "roles": [
       "build"
     ]
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/config-util.ts

@@ -18,11 +18,14 @@ export class PackConfigUtil {
     const { os, packages } = config.dockerRuntime;
     if (packages?.length) {
       switch (os) {
-        case 'alpine': return `RUN apk --update add ${packages.join(' ')} && rm -rf /var/cache/apk/*`;
-        case 'debian': return `RUN apt update && apt install -y ${packages.join(' ')} && rm -rf  /var/lib/{apt,dpkg,cache,log}/`;
-        case 'centos': return `RUN yum -y install ${packages.join(' ')} && yum -y clean all && rm -fr /var/cache`;
-        case 'unknown':
-        default: throw new Error('Unable to install packages in an unknown os');
+        case 'alpine':
+          return `RUN apk --update add ${packages.join(' ')} && rm -rf /var/cache/apk/*`;
+        case 'debian':
+          return `RUN apt update && apt install -y ${packages.join(' ')} && rm -rf  /var/lib/{apt,dpkg,cache,log}/`;
+        case 'centos':
+          return `RUN yum -y install ${packages.join(' ')} && yum -y clean all && rm -fr /var/cache`;
+        default:
+          throw new Error('Unable to install packages in an unknown os');
       }
     } else {
       return '';
@@ -38,9 +41,11 @@ export class PackConfigUtil {
       const [name, directive] = item.split(':');
       switch (directive) {
         case 'from-source':
-          out.push(`RUN npm_config_build_from_source=true npm install ${name} --build-from-source`); break;
+          out.push(`RUN npm_config_build_from_source=true npm install ${name} --build-from-source`);
+          break;
         default:
-          out.push(`RUN npm install ${name}`); break;
+          out.push(`RUN npm install ${name}`);
+          break;
       }
     }
     if (out.length) {
@@ -65,11 +70,13 @@ export class PackConfigUtil {
       return '';
     } else {
       switch (os) {
-        case 'alpine': return `RUN addgroup -g ${groupId} ${group} && adduser -D -G ${group} -u ${userId} ${user}`;
+        case 'alpine':
+          return `RUN addgroup -g ${groupId} ${group} && adduser -D -G ${group} -u ${userId} ${user}`;
         case 'debian':
-        case 'centos': return `RUN groupadd --gid ${groupId} ${group} && useradd -u ${userId} -g ${group} ${user}`;
-        case 'unknown':
-        default: throw new Error('Unable to add user/group for an unknown os');
+        case 'centos':
+          return `RUN groupadd --gid ${groupId} ${group} && useradd -u ${userId} -g ${group} ${user}`;
+        default:
+          throw new Error('Unable to add user/group for an unknown os');
       }
     }
   }
@@ -78,9 +85,7 @@ export class PackConfigUtil {
    * Setup Env Vars for NODE_OPTIONS and other standard environment variables
    */
   static dockerEnvVars(config: DockerPackConfig): string {
-    return [
-      `ENV NODE_OPTIONS="${[...(config.sourcemap ? ['--enable-source-maps'] : [])].join(' ')}"`,
-    ].join('\n');
+    return [`ENV NODE_OPTIONS="${[...(config.sourcemap ? ['--enable-source-maps'] : [])].join(' ')}"`].join('\n');
   }
 
   /**
@@ -88,9 +93,7 @@ export class PackConfigUtil {
    */
   static dockerAppFolder(config: DockerPackConfig): string {
     const { folder, user, group } = config.dockerRuntime;
-    return [
-      `RUN mkdir ${folder} && chown ${user}:${group} ${folder}`,
-    ].join('\n');
+    return [`RUN mkdir ${folder} && chown ${user}:${group} ${folder}`].join('\n');
   }
 
   /**
@@ -106,11 +109,7 @@ export class PackConfigUtil {
    */
   static dockerEntrypoint(config: DockerPackConfig): string {
     const { user, folder } = config.dockerRuntime;
-    return [
-      `USER ${user}`,
-      `WORKDIR ${folder}`,
-      `ENTRYPOINT ["${folder}/${config.mainName}.sh"]`,
-    ].join('\n');
+    return [`USER ${user}`, `WORKDIR ${folder}`, `ENTRYPOINT ["${folder}/${config.mainName}.sh"]`].join('\n');
   }
   /**
    * Common docker environment setup
@@ -122,8 +121,10 @@ export class PackConfigUtil {
       this.dockerPackageInstall(config),
       this.dockerAppFolder(config),
       this.dockerAppFiles(config),
-      this.dockerEnvVars(config),
-    ].filter(line => !!line).join('\n');
+      this.dockerEnvVars(config)
+    ]
+      .filter(line => !!line)
+      .join('\n');
   }
 
   /**
@@ -137,4 +138,4 @@ export class PackConfigUtil {
       this.dockerEntrypoint(config)
     ].join('\n');
   }
-}
+}

package/src/types.ts

@@ -1,5 +1,5 @@
-import { type OutputOptions } from 'rollup';
 import type terser from '@rollup/plugin-terser';
+import type { OutputOptions } from 'rollup';
 
 export type CommonPackConfig = {
   buildDirectory: string;
@@ -59,10 +59,10 @@ export type ShellCommandProvider = {
   comment(message: string): string[];
   echo(text: string): string[];
   zip(output: string): string[];
-  script(lines: string[], chdir?: boolean): { ext: string, contents: string[] };
+  script(lines: string[], chdir?: boolean): { ext: string; contents: string[] };
 };
 
-export type DockerPackFactory = (config: DockerPackConfig) => (string | Promise<string>);
+export type DockerPackFactory = (config: DockerPackConfig) => string | Promise<string>;
 export type DockerPackFactoryModule = { factory: DockerPackFactory };
 
 export type CoreRollupConfig = {
@@ -73,4 +73,4 @@ export type CoreRollupConfig = {
   ignore: Set<string>;
   external: string[];
   minify: Parameters<typeof terser>[0];
-};
+};

package/support/bin/docker-operation.ts

@@ -1,46 +1,64 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { JSONUtil, Runtime } from '@travetto/runtime';
 import { cliTpl } from '@travetto/cli';
+import { JSONUtil, Runtime } from '@travetto/runtime';
 
-import { ActiveShellCommand } from './shell.ts';
 import type { DockerPackConfig, DockerPackFactoryModule } from '../../src/types.ts';
 import { PackOperation } from './operation.ts';
+import { ActiveShellCommand } from './shell.ts';
 import { PackUtil } from './util.ts';
 
 export class DockerPackOperation {
-
   static getDockerTags(config: DockerPackConfig): string[] {
-    return (config.dockerTag ?? []).map(tag => config.dockerRegistry ? `${config.dockerRegistry}/${config.dockerName}:${tag}` : `${config.dockerName}:${tag}`);
+    return (config.dockerTag ?? []).map(tag =>
+      config.dockerRegistry ? `${config.dockerRegistry}/${config.dockerName}:${tag}` : `${config.dockerName}:${tag}`
+    );
   }
 
   /**
    * Detect image os
    */
-  static async* detectDockerImageOs(config: DockerPackConfig): AsyncIterable<string[]> {
+  static async *detectDockerImageOs(config: DockerPackConfig): AsyncIterable<string[]> {
     // Read os before writing
-    config.dockerRuntime.os = await PackUtil.runCommand(
-      ['docker', 'run', '--rm', '--entrypoint', '/bin/sh', config.dockerImage, '-c', 'cat /etc/*release*']
-    ).then(out => {
+    config.dockerRuntime.os = await PackUtil.runCommand([
+      'docker',
+      'run',
+      '--rm',
+      '--entrypoint',
+      '/bin/sh',
+      config.dockerImage,
+      '-c',
+      'cat /etc/*release*'
+    ]).then(out => {
       const found = out.toLowerCase().match(/\b(?:debian|alpine|centos)\b/)?.[0];
       switch (found) {
-        case 'debian': case 'alpine': case 'centos': return found;
-        default: return 'unknown';
+        case 'debian':
+        case 'alpine':
+        case 'centos':
+          return found;
+        default:
+          return 'unknown';
       }
     });
-    yield* PackOperation.title(config, cliTpl`${{ title: 'Detected Image OS' }} ${{ param: config.dockerImage }} as ${{ param: config.dockerRuntime.os }}`);
+    yield* PackOperation.title(
+      config,
+      cliTpl`${{ title: 'Detected Image OS' }} ${{ param: config.dockerImage }} as ${{ param: config.dockerRuntime.os }}`
+    );
   }
 
   /**
    * Write Docker File
    */
-  static async* writeDockerFile(config: DockerPackConfig): AsyncIterable<string[]> {
+  static async *writeDockerFile(config: DockerPackConfig): AsyncIterable<string[]> {
     const dockerFile = path.resolve(config.buildDirectory, 'Dockerfile');
     const { factory } = await Runtime.importFrom<DockerPackFactoryModule>(config.dockerFactory);
     const content = (await factory(config)).trim();
 
-    yield* PackOperation.title(config, cliTpl`${{ title: 'Generating Docker File' }} ${{ path: dockerFile }} ${{ param: config.dockerFactory }}`);
+    yield* PackOperation.title(
+      config,
+      cliTpl`${{ title: 'Generating Docker File' }} ${{ path: dockerFile }} ${{ param: config.dockerFactory }}`
+    );
 
     if (config.ejectFile) {
       yield* ActiveShellCommand.createFile(dockerFile, content.split(/\n/));
@@ -52,7 +70,7 @@ export class DockerPackOperation {
   /**
    * Pull Docker Base Image
    */
-  static async* pullDockerBaseImage(config: DockerPackConfig): AsyncIterable<string[]> {
+  static async *pullDockerBaseImage(config: DockerPackConfig): AsyncIterable<string[]> {
     const command = ['docker', 'pull', config.dockerImage];
 
     yield* PackOperation.title(config, cliTpl`${{ title: 'Pulling Docker Base Image' }} ${{ param: config.dockerImage }}`);
@@ -67,11 +85,13 @@ export class DockerPackOperation {
   /**
    * Building Docker Container
    */
-  static async* buildDockerContainer(config: DockerPackConfig): AsyncIterable<string[]> {
+  static async *buildDockerContainer(config: DockerPackConfig): AsyncIterable<string[]> {
     const cmd = [
-      'docker', 'build',
+      'docker',
+      'build',
       ...(config.dockerBuildPlatform ? ['--platform', config.dockerBuildPlatform] : []),
-      ...DockerPackOperation.getDockerTags(config).flatMap(tag => ['-t', tag]), '.'
+      ...DockerPackOperation.getDockerTags(config).flatMap(tag => ['-t', tag]),
+      '.'
     ];
 
     yield* PackOperation.title(config, cliTpl`${{ title: 'Building Docker Container' }} ${{ param: config.dockerTag?.join(',') }}`);
@@ -90,7 +110,7 @@ export class DockerPackOperation {
   /**
    * Push Docker Container
    */
-  static async* pushDockerContainer(config: DockerPackConfig): AsyncIterable<string[]> {
+  static async *pushDockerContainer(config: DockerPackConfig): AsyncIterable<string[]> {
     if (!config.dockerPush) {
       return;
     }
@@ -109,4 +129,4 @@ export class DockerPackOperation {
       }
     }
   }
-}
+}