@travetto/pack 3.0.0-rc.8 → 3.0.0

package/README.md

@@ -1,267 +1,232 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/pack/doc.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/pack/DOC.ts and execute "npx trv doc" to rebuild -->
 # Pack
 ## Code packing utilities
 
 **Install: @travetto/pack**
 ```bash
 npm install @travetto/pack
+
+# or
+
+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.
+
+There are three primary cli commands for packing your code:
+   
+   *  pack
+   *  pack:zip
+   *  pack:docker
+
 ## CLI - pack 
 
 **Terminal: Pack usage**
 ```bash
 $ trv pack --help
 
-Usage:  pack [options] [mode]
+Usage:  pack [options] [args...]
 
 Options:
-  -w, --workspace <workspace>  Working directory
-  -h, --help                   display help for command
-
-Available Pack Modes:
-  * default [support/pack.config.ts]
-  * rest/docker [@travetto/rest/support/pack.docker.ts]
-  * rest-aws-lambda/main [@travetto/rest-aws-lambda/support/pack.aws-lambda.ts]
+  -w, --workspace <workspace>           Workspace for building
+  -c, --no-clean                        Disables: Clean workspace
+  -o, --output <output>                 Output Location
+  -e, --entry-point <entry-point>       Entry point (default: "node_modules/@travetto/cli/support/cli.js")
+  -ec, --entry-command <entry-command>  Entry command
+  -m, --no-minify                       Disables: Minify output
+  -sm, --sourcemap                      Bundle source maps
+  -is, --include-sources                Include source with source maps
+  -x, --eject-file <eject-file>         Eject commands to file
+  -h, --help                            display help for command
 ```
 
-This command line operation will compile your project, and produce a ready to use workspace as a deliverable. The pack operation is actually a wrapper around multiple sub-operations that are run in series to produce the desired final structure for deployment.  The currently support operations are:
+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).
 
-   
-   *  assemble
-   *  zip
-   *  docker
+Specific to this CLI command, the `output` field determines where the final folder is written that contains all the compiled source. 
 
-### CLI - pack:assemble
+### 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.
 
-Assemble is the operation that stages the project's code for deployment.  The assembly process goes through the following operations:
+Within the command line, the `args` are positional arguments that will be passed to the entry point on application run. 
 
-   
-   1. Cleaning Workspace - Cleans workspace to start with an empty workspace
-   1. Copying Dependencies - Computes the prod dependencies and copies them into the new workspace
-   1. Copying App Content - Copies over application content (src/, resources/, support/, bin/)
-   1. Excluding Pre-Compile Files - Any files that should be excluded pre-compilation, are removed
-   1. Compiling - Compiles the code in the new workspace, isolating it from your local development
-   1. Excluding Post-Compile Files - Removes any files that should be excluded, post compilation
-   1. Copying Added Content - Adds in any additional content that is not in the standard locations
-   1. Removing Empty Folders - Purge all empty folders, recursively
-   1. Writing Env.js - Write out the .env.js file with computed any env vars that should be set for the deployed app
-   1. Remove Source Maps - If keep source is false, all source maps are purged from your app's code
-   1. Emptying .ts Files - If keep source is false, all .ts files are emptied, as compilation will not occur at runtime
-
-**Code: Assemble Default Config**
+**Code: Packing an application run**
 ```typescript
-assemble: {
-    active: true,
-    cacheDir: 'cache',
-    keepSource: true,
-    readonly: true,
-    env: {
-      TRV_DYNAMIC: '0'
-    },
-    add: [
-      { [mod('@travetto/cli/bin/trv.js')]: mod('.bin/trv') },
-      { [mod('lodash/lodash.min.js')]: mod('lodash/lodash.js') },
-    ],
-    excludeCompile: [
-      mod('@travetto/*/doc/'),
-      mod('@travetto/*/e2e/'),
-      mod('@travetto/*/test/'),
-    ],
-    exclude: [
-      'bower.json',
-      'LICENSE',
-      'LICENCE',
-      '*.map',
-      '*.md',
-      '*.lock',
-      '*.html',
-      '*.mjs',
-      mod('**/*.ts'),
-      '*.d.ts',
+$ npx trv pack run myapp
 ```
 
-**Terminal: Assemble Usage**
-```bash
-$ trv pack:assemble --help
-
-Usage:  pack:assemble [options] [mode]
+Would then produce an executable script, in the output folder, that would look like:
 
-Options:
-  -w, --workspace <workspace>  Working directory
-  -k, --keep-source            Should source be preserved
-  -r, --readonly               Build a readonly deployable
-  -h, --help                   display help for command
-
-Available Pack Modes:
-  * default [support/pack.config.ts]
-  * rest/docker [@travetto/rest/support/pack.docker.ts]
-  * rest-aws-lambda/main [@travetto/rest-aws-lambda/support/pack.aws-lambda.ts]
+**Code: Entry script for Packed application**
+```typescript
+#!/bin/sh
+cd $(dirname "$0")
+node cli run myapp
 ```
 
-### CLI - pack:zip
+And this entry point would be what is executed by [docker](https://www.docker.com/community-edition), or whatever deployment mechanism is being used.
 
-Zip is an optional step, that can run post assembly.  The only configuration it currently provides is the ability to specify the output location for the zip file.
+### 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.
 
-**Code: Zip Default Config**
-```typescript
-zip: {
-    active: false,
-    output: 'output.zip'
-  },
-```
+   
+   *  `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.
+   *  `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 `prod`-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
 
-**Terminal: Zip Usage**
+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**
 ```bash
 $ trv pack:zip --help
 
-Usage:  pack:zip [options] [mode]
+Usage:  pack:zip [options] [args...]
 
 Options:
-  -w, --workspace <workspace>  Working directory
-  -o, --output <output>        Output File
-  -h, --help                   display help for command
-
-Available Pack Modes:
-  * default [support/pack.config.ts]
-  * rest/docker [@travetto/rest/support/pack.docker.ts]
-  * rest-aws-lambda/main [@travetto/rest-aws-lambda/support/pack.aws-lambda.ts]
+  -w, --workspace <workspace>           Workspace for building
+  -c, --no-clean                        Disables: Clean workspace
+  -o, --output <output>                 Output Location (default: "travetto_pack.zip")
+  -e, --entry-point <entry-point>       Entry point (default: "node_modules/@travetto/cli/support/cli.js")
+  -ec, --entry-command <entry-command>  Entry command
+  -m, --no-minify                       Disables: Minify output
+  -sm, --sourcemap                      Bundle source maps
+  -is, --include-sources                Include source with source maps
+  -x, --eject-file <eject-file>         Eject commands to file
+  -h, --help                            display help for command
 ```
 
-### CLI - pack:docker
-
-Docker support is an optional step, that can run post assembly.  This allows for building a docker image, and currently only supports the base images as the only configuration options.
+## CLI - pack:docker
 
-**Code: Docker Default Config**
-```typescript
-docker: {
-    active: false,
-    image: 'node:16-alpine'
-  }
-```
+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: Docker Usage**
+**Terminal: Pack:docker usage**
 ```bash
 $ trv pack:docker --help
 
-Usage:  pack:docker [options] [mode]
+Usage:  pack:docker [options] [args...]
 
 Options:
-  -w, --workspace <workspace>  Working directory
-  -i, --image <image>          Docker Image to extend
-  -n, --name <name>            Image Name
-  -t, --tag <tag>              Image Tag (default: [])
-  -p, --port <port>            Image Port (default: [])
-  -x, --push                   Push Tags
-  -r, --registry <registry>    Registry
-  -h, --help                   display help for command
-
-Available Pack Modes:
-  * default [support/pack.config.ts]
-  * rest/docker [@travetto/rest/support/pack.docker.ts]
-  * rest-aws-lambda/main [@travetto/rest-aws-lambda/support/pack.aws-lambda.ts]
+  -w, --workspace <workspace>               Workspace for building
+  -c, --no-clean                            Disables: Clean workspace
+  -o, --output <output>                     Output Location
+  -e, --entry-point <entry-point>           Entry point (default: "node_modules/@travetto/cli/support/cli.js")
+  -ec, --entry-command <entry-command>      Entry command
+  -m, --no-minify                           Disables: Minify output
+  -sm, --sourcemap                          Bundle source maps
+  -is, --include-sources                    Include source with source maps
+  -x, --eject-file <eject-file>             Eject commands to file
+  -df, --docker-factory <docker-factory>    Docker Factory source (default: "@travetto/pack/support/pack.dockerfile")
+  -di, --docker-image <docker-image>        Docker Image to extend (default: "node:18-alpine3.16")
+  -dn, --docker-name <docker-name>          Docker Image Name (default: "travetto_pack")
+  -dt, --docker-tag <docker-tag>            Docker Image Tag (default: ["latest"])
+  -dp, --docker-port <docker-port>          Docker Image Port (default: [])
+  -dx, --docker-push                        Docker Push Tags
+  -dr, --docker-registry <docker-registry>  Docker Registry
+  -h, --help                                display help for command
 ```
 
-### Modes
-Various modules may provide customizations to the default `pack.config.ts` to allow for easy integration with the packing process.  A simple example of this is via the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module, for how to publish lambda packages.
+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.
 
-**Code: Rest, pack.lambda.ts**
-```typescript
-import * as fs from 'fs/promises';
-
-import { PathUtil } from '@travetto/boot';
-import type { AllConfigPartial } from '@travetto/pack';
-
-export const config: AllConfigPartial = {
-  name: 'rest-aws-lambda/main',
-  assemble: {
-    active: true,
-    keepSource: false,
-    exclude: [
-      'node_modules/node-forge'
-    ],
-    env: {
-      NO_COLOR: '1'
-    },
-    postProcess: [{
-      ['Lambda Entrypoint']: cfg =>
-        fs.copyFile(
-          PathUtil.resolveUnix(__dirname, 'aws-lambda.handler.js'),
-          PathUtil.resolveUnix(cfg.workspace, 'index.js')
-        )
-    }],
-  },
-  zip: {
-    active: true,
-    output: 'dist/lambda.zip'
-  }
-};
-```
+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
+
+## 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.
 
-**Terminal: Invoking Pack with Mode**
+**Terminal: Sample Ejected File**
 ```bash
-npx trv pack <mode>
-```
+$ trv pack:docker -x /dev/stdout run rest
 
-## Configuration
+#!/bin/sh
+export DIST=/tmp/_home_tim_Code_travetto_related_todo-app
+export TRV_OUT=<workspace-root>/.trv_output
+export ROOT=<workspace-root>/related/todo-app
+export MOD=@travetto/todo-app
 
-By default, the configuration consists of two components.
-   
-   *  The default config in `support/pack.config.ts` and
-   *  The config selected to execute from the cli
+# Cleaning Output $DIST 
 
-These two configurations will be loaded and layered, with the selected config taking precedence.
+rm -rf $DIST
+mkdir -p $DIST
 
-**Code: Example pack.config.ts**
-```typescript
-import type { AllConfigPartial } from '@travetto/pack';
-
-export const config: AllConfigPartial = {
-  workspace: 'dist/alt',
-  assemble: {
-    active: true,
-    add: [
-      { assets: 'assets' },
-      { '/secret/location/key.pem': 'resources/key.pem' }
-    ]
-  },
-  zip: {
-    active: true,
-    output: 'dist/build.zip'
-  }
-};
-```
+# Writing .env.js 
 
-### Environment Override
+echo "process.env.TRV_MANIFEST = 'node_modules/$MOD';" > $DIST/.env.js
+echo "process.env.TRV_CLI_IPC = '';" >> $DIST/.env.js
 
-When working with sub operations, passing command-line flags is challenging.  To support a more natural usage, the sub operations 
-allow their key parameters to be overridden via environment variables.
+# Writing package.json 
 
-**Code: Assemble Overrides**
-```typescript
-overrides: {
-    keepSource: CliUtil.toBool(process.env.PACK_ASSEMBLE_KEEP_SOURCE),
-    readonly: CliUtil.toBool(process.env.PACK_ASSEMBLE_READONLY)
-  },
-```
+echo "{\"type\":\"commonjs\"}" > $DIST/package.json
 
-**Code: Docker Overrides**
-```typescript
-overrides: {
-    image: process.env.PACK_DOCKER_IMAGE || undefined,
-    name: process.env.PACK_DOCKER_NAME || undefined,
-    app: process.env.PACK_DOCKER_APP || undefined,
-    port: process.env.PACK_DOCKER_PORT ? [process.env.PACK_DOCKER_PORT] : undefined,
-    registry: process.env.PACK_DOCKER_REGISTRY || undefined,
-    push: CliUtil.toBool(process.env.PACK_DOCKER_PUSH),
-    tag: process.env.PACK_DOCKER_TAG ? [process.env.PACK_DOCKER_TAG] : undefined
-  },
-```
+# Writing entry scripts cli.sh args=(run rest) 
 
-**Code: Zip Overrides**
-```typescript
-overrides: {
-    output: process.env.PACK_ZIP_OUTPUT || undefined
-  },
+echo "#!/bin/sh" > $DIST/cli.sh
+echo "cd \$(dirname \"\$0\")" >> $DIST/cli.sh
+echo "node cli run rest \$@" >> $DIST/cli.sh
+chmod 755 $DIST/cli.sh
+
+# Writing entry scripts cli.cmd args=(run rest) 
+
+echo "" > $DIST/cli.cmd
+echo "cd %~p0" >> $DIST/cli.cmd
+echo "node cli run rest %*" >> $DIST/cli.cmd
+chmod 755 $DIST/cli.cmd
+
+# Copying over resources 
+
+mkdir -p $DIST/node_modules/$MOD
+cp $TRV_OUT/node_modules/$MOD/package.json $DIST/node_modules/$MOD/package.json
+mkdir -p $DIST/node_modules/@travetto/manifest
+cp $TRV_OUT/node_modules/@travetto/manifest/package.json $DIST/node_modules/@travetto/manifest/package.json
+cp -r -p $ROOT/resources $DIST/resources
+
+# Generating App Cache node_modules/$MOD/trv-app-cache.json 
+
+mkdir -p $DIST/node_modules/$MOD
+DEBUG=0 TRV_MODULE=$MOD npx trv main @travetto/app/support/bin/list > $DIST/node_modules/$MOD/trv-app-cache.json
+
+# Writing Manifest node_modules/$MOD 
+
+TRV_MODULE=$MOD npx trv manifest $DIST/node_modules/$MOD prod
+
+# Bundling Output minify=true sourcemap= entryPoint=node_modules/@travetto/cli/support/cli.js 
+
+export BUNDLE_ENTRY=node_modules/@travetto/cli/support/cli.js
+export BUNDLE_ENTRY_NAME=cli
+export BUNDLE_COMPRESS=true
+export BUNDLE_OUTPUT=$DIST
+export BUNDLE_FORMAT=commonjs
+export TRV_MANIFEST=$TRV_OUT/node_modules/$MOD
+cd $TRV_OUT
+npx rollup -c node_modules/@travetto/pack/support/bin/rollup.js
+cd $ROOT
+
+# Generating Docker File $DIST/Dockerfile @travetto/pack/support/pack.dockerfile 
+
+echo "FROM node:18-alpine3.16" > $DIST/Dockerfile
+echo "WORKDIR /app" >> $DIST/Dockerfile
+echo "COPY . ." >> $DIST/Dockerfile
+echo "" >> $DIST/Dockerfile
+echo "ENTRYPOINT [\"/app/cli.sh\"]" >> $DIST/Dockerfile
+
+# Pulling Docker Base Image node:18-alpine3.16 
+
+docker pull node:18-alpine3.16
+
+# Building Docker Container latest 
+
+cd $DIST
+docker build -t travetto_todo-app:latest .
+cd $ROOT
 ```

package/__index__.ts

@@ -1 +1 @@
-export type { CommonPackConfig } from './support/bin/types';
+export type { CommonPackConfig, DockerPackFactory, DockerPackConfig } from './support/bin/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/pack",
-  "version": "3.0.0-rc.8",
+  "version": "3.0.0",
   "description": "Code packing utilities",
   "keywords": [
     "travetto",
@@ -14,6 +14,7 @@
     "email": "travetto.framework@gmail.com",
     "name": "Travetto Framework"
   },
+  "main": "__index__.ts",
   "files": [
     "__index__.ts",
     "support"
@@ -25,14 +26,14 @@
   "dependencies": {
     "@rollup/plugin-commonjs": "^24.0.1",
     "@rollup/plugin-json": "^6.0.0",
-    "@rollup/plugin-terser": "^0.4.0",
     "@rollup/plugin-node-resolve": "^15.0.1",
-    "@travetto/base": "^3.0.0-rc.8",
-    "rollup": "^3.12.1",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@travetto/base": "^3.0.0",
+    "rollup": "^3.17.2",
     "rollup-plugin-sourcemaps": "^0.6.3"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.0.0-rc.9"
+    "@travetto/cli": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/support/bin/docker-operation.ts

@@ -1,11 +1,11 @@
 import fs from 'fs/promises';
 
-import { path } from '@travetto/manifest';
+import { path, RootIndex } from '@travetto/manifest';
 import { ExecUtil } from '@travetto/base';
 import { cliTpl } from '@travetto/cli';
 
 import { ActiveShellCommand } from './shell';
-import { DockerPackConfig } from './types';
+import { DockerPackConfig, DockerPackFactoryModule } from './types';
 
 export class DockerPackOperation {
 
@@ -18,14 +18,14 @@ export class DockerPackOperation {
    */
   static async* writeDockerFile(cfg: DockerPackConfig): AsyncIterable<string[]> {
     const dockerFile = path.resolve(cfg.workspace, 'Dockerfile');
-    const title = cliTpl`${{ title: 'Generating Docker File' }} ${{ path: dockerFile }}`;
-    const content = `
-FROM ${cfg.dockerImage}
-WORKDIR /app
-COPY . .
-${(cfg.dockerPort ?? []).map(x => `EXPOSE ${x}`).join('\n')}
-ENTRYPOINT ["/app/${cfg.entryCommand}.sh"]
-`;
+    const title = cliTpl`${{ title: 'Generating Docker File' }} ${{ path: dockerFile }} ${{ param: cfg.dockerFactory }}`;
+    const factory = RootIndex.getFromImport(cfg.dockerFactory);
+    if (!factory) {
+      throw new Error(`Unable to resolve docker factory at ${cfg.dockerFactory}`);
+    }
+    const mod: DockerPackFactoryModule = await import(factory.import);
+    const content = (await mod.factory(cfg)).trim();
+
     if (cfg.ejectFile) {
       yield ActiveShellCommand.comment(title);
       yield* ActiveShellCommand.createFile(dockerFile, content.split(/\n/));
@@ -79,14 +79,18 @@ ENTRYPOINT ["/app/${cfg.entryCommand}.sh"]
     }
     const tags = DockerPackOperation.getDockerTags(cfg);
     const title = cliTpl`${{ title: 'Push Container to registry' }} ${{ param: cfg.dockerRegistry }}`;
-    const cmd = ['docker', 'image', 'push', ...tags];
+    const cmd = ['docker', 'image', 'push'];
 
     if (cfg.ejectFile) {
       yield ActiveShellCommand.comment(title);
-      yield cmd;
+      for (const tag of tags) {
+        yield [...cmd, tag];
+      }
     } else {
       yield [title];
-      await ExecUtil.spawn(cmd[0], cmd.slice(1), { stdio: [0, 'pipe', 2] }).result;
+      for (const tag of tags) {
+        await ExecUtil.spawn(cmd[0], [...cmd.slice(1), tag], { stdio: [0, 'pipe', 2] }).result;
+      }
     }
   }
 }

package/support/bin/operation.ts

@@ -14,6 +14,9 @@ async function writeRawFile(file: string, contents: string, mode?: string): Prom
 
 export class PackOperation {
 
+  /**
+   * Clean out pack workspace, removing all content
+   */
   static async * clean(cfg: CommonPackConfig): AsyncIterable<string[]> {
     if (!cfg.clean) {
       return;
@@ -38,6 +41,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Invoke bundler (rollup) to produce output in workspace folder
+   */
   static async * bundle(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const cwd = RootIndex.outputRoot;
 
@@ -76,6 +82,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Write out package.json, to help define how output .js file should be interpreted
+   */
   static async * writePackageJson(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const file = 'package.json';
     const title = cliTpl`${{ title: 'Writing' }} ${{ path: file }}`;
@@ -96,6 +105,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Define .env.js file to control manifest location
+   */
   static async * writeEnv(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const file = '.env.js';
     const title = cliTpl`${{ title: 'Writing' }} ${{ path: file }}`;
@@ -119,10 +131,13 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Create launcher scripts (.sh, .cmd) to run output
+   */
   static async * writeEntryScript(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const title = 'Writing entry scripts';
 
-    const files = ([['posix', 'sh'], ['win32', 'bat']] as const)
+    const files = ([['posix', 'sh'], ['win32', 'cmd']] as const)
       .map(([type, ext]) => ({
         fileTitle: cliTpl`${{ title }} ${{ path: `${cfg.entryCommand}.${ext}` }} args=(${{ param: cfg.entryArguments.join(' ') }})`,
         file: `${cfg.entryCommand}.${ext}`,
@@ -146,6 +161,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Copy over /resources folder into workspace, will get packaged into final output
+   */
   static async * copyResources(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const resources = {
       count: RootIndex.mainModule.files.resources?.length ?? 0,
@@ -188,9 +206,12 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Generate the trv-app-cache.json for @travetto/app, which is needed for 'running' programs
+   */
   static async * primeAppCache(cfg: CommonPackConfig): AsyncIterable<string[]> {
-    const isCli = cfg.entryCommand === 'cli';
-    if (!isCli || !RootIndex.hasModule('@travetto/app')) {
+    const isRun = cfg.entryCommand === 'cli' && cfg.entryArguments.filter(x => !x.startsWith('-'))[0] === 'run';
+    if (!isRun) {
       return;
     }
 
@@ -214,6 +235,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Produce the output manifest, only including prod dependencies
+   */
   static async * writeManifest(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const out = path.resolve(cfg.workspace, 'node_modules', cfg.module);
     const cmd = ['npx', 'trv', 'manifest', out, 'prod'];
@@ -229,6 +253,9 @@ export class PackOperation {
     }
   }
 
+  /**
+   * Generate ZIP file for workspace
+   */
   static async * compress(cfg: CommonPackConfig): AsyncIterable<string[]> {
     const title = cliTpl`${{ title: 'Compressing' }} ${{ path: cfg.output }}`;
 
@@ -243,13 +270,4 @@ export class PackOperation {
       await ExecUtil.spawn(cmd, args, { cwd: cfg.workspace }).result;
     }
   }
-
-
-  static async * runOperations<S>(cfg: S, operations: ((config: S) => AsyncIterable<string[]>)[]): AsyncIterable<string> {
-    for (const op of operations) {
-      for await (const msg of op(cfg)) {
-        yield msg.join(' ');
-      }
-    }
-  }
 }

package/support/bin/rollup.ts

@@ -10,6 +10,8 @@ import { RootIndex } from '@travetto/manifest';
 import { getEntry, getOutput, getTerserConfig, getFiles } from './config';
 import { travettoImportPlugin } from './rollup-esm-dynamic-import';
 
+const NEVER_INCLUDE = new Set(['node-forge', '@parcel/watcher']);
+
 export default function buildConfig(): RollupOptions {
   const output = getOutput();
   const entry = getEntry();
@@ -18,10 +20,10 @@ export default function buildConfig(): RollupOptions {
   return {
     input: [entry],
     output,
-    external: ['node-forge', '@parcel/watcher'],
     plugins: [
       jsonImport(),
       commonjsRequire({
+        ignore: id => NEVER_INCLUDE.has(id),
         dynamicRequireRoot: RootIndex.manifest.workspacePath,
         dynamicRequireTargets: (output.format === 'commonjs' ? files : [])
       }),

package/support/bin/types.ts

@@ -31,6 +31,7 @@ export type CommonPackOptions = {
 };
 
 export type DockerPackConfig = {
+  dockerFactory: string;
   dockerImage: string;
   dockerName: string;
   dockerTag: string[];
@@ -40,6 +41,7 @@ export type DockerPackConfig = {
 } & CommonPackConfig;
 
 export type DockerPackOptions = {
+  dockerFactory: OptionConfig<string>;
   dockerImage: OptionConfig<string>;
   dockerName: OptionConfig<string>;
   dockerTag: ListOptionConfig<string>;
@@ -62,4 +64,7 @@ export type ShellCommandImpl = {
   chdir(dest: string): string[];
   comment(message: string): string[];
   zip(output: string): string[];
-};
+};
+
+export type DockerPackFactory = (cfg: DockerPackConfig) => (string | Promise<string>);
+export type DockerPackFactoryModule = { factory: DockerPackFactory };

package/support/cli.pack_docker.ts

@@ -1,3 +1,5 @@
+import { path, RootIndex } from '@travetto/manifest';
+
 import { DockerPackConfig, DockerPackOptions } from './bin/types';
 import { DockerPackOperation } from './bin/docker-operation';
 import { BasePackCommand, PackOperationShape } from './pack.base';
@@ -14,6 +16,7 @@ export class PackDockerCommand extends BasePackCommand<DockerPackOptions, Docker
     const opts = this.getCommonOptions();
     return {
       ...opts,
+      dockerFactory: this.option({ short: 'df', desc: 'Docker Factory source', def: '@travetto/pack/support/pack.dockerfile' }),
       dockerImage: this.option({ short: 'di', desc: 'Docker Image to extend', def: 'node:18-alpine3.16' }),
       dockerName: this.option({ short: 'dn', desc: 'Docker Image Name', def: this.monoRoot ? '<module>' : this.getSimpleModuleName() }),
       dockerTag: this.listOption({ short: 'dt', desc: 'Docker Image Tag', def: ['latest'] }),
@@ -23,6 +26,16 @@ export class PackDockerCommand extends BasePackCommand<DockerPackOptions, Docker
     };
   }
 
+  async buildConfig(): Promise<DockerPackConfig> {
+    const cfg = await super.buildConfig();
+    if (cfg.dockerFactory.startsWith('.')) {
+      cfg.dockerFactory = RootIndex.getFromSource(path.resolve(cfg.dockerFactory))?.import ?? cfg.dockerFactory;
+    }
+    cfg.dockerPort ??= [];
+    cfg.dockerTag ??= [];
+    return cfg;
+  }
+
   getOperations(): PackOperationShape<DockerPackConfig>[] {
     return [
       ...super.getOperations(),

package/support/pack.base.ts

@@ -11,6 +11,17 @@ import { PackUtil } from './bin/util';
 
 export type PackOperationShape<T extends CommonPackConfig> = ((config: T) => AsyncIterable<string[]>);
 
+const BASIC_OP_SET = [
+  PackOperation.clean,
+  PackOperation.writeEnv,
+  PackOperation.writePackageJson,
+  PackOperation.writeEntryScript,
+  PackOperation.copyResources,
+  PackOperation.primeAppCache,
+  PackOperation.writeManifest,
+  PackOperation.bundle,
+];
+
 export abstract class BasePackCommand<T extends CommonPackOptions, S extends CommonPackConfig> extends CliCommand<{}> {
 
   get monoRoot(): boolean {
@@ -48,25 +59,21 @@ export abstract class BasePackCommand<T extends CommonPackOptions, S extends Com
   }
 
   getOperations(): PackOperationShape<S>[] {
-    const ops: ((config: S) => AsyncIterable<string[]>)[] = [];
+    return BASIC_OP_SET.slice(0);
+  }
 
-    if (this.cmd.clean) {
-      ops.push(PackOperation.clean);
+  /**
+   * Run all operations
+   */
+  async * runOperations(cfg: S): AsyncIterable<string> {
+    for (const op of this.getOperations()) {
+      for await (const msg of op(cfg)) {
+        yield msg.join(' ');
+      }
     }
-
-    ops.push(
-      PackOperation.writeEnv,
-      PackOperation.writePackageJson,
-      PackOperation.writeEntryScript,
-      PackOperation.copyResources,
-      PackOperation.primeAppCache,
-      PackOperation.writeManifest,
-      PackOperation.bundle,
-    );
-
-    return ops;
   }
 
+
   getModule(moduleName: string): string {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     let module = this.monoRoot ? moduleName : RootIndex.mainModule.name;
@@ -88,21 +95,27 @@ export abstract class BasePackCommand<T extends CommonPackOptions, S extends Com
   }
 
   async action(module: string, args: string[]): Promise<void> {
+    if (Array.isArray(module)) {
+      args = module;
+      module = RootIndex.mainModule.name;
+    }
     const start = Date.now();
     if (!module && this.monoRoot) {
-      this.showHelp(new Error('The module needs to specified when running from a monorepo root'));
+      return this.showHelp(new Error('The module needs to specified when running from a monorepo root'));
     }
 
     module = this.getModule(module);
 
     const cfg = await this.buildConfig();
-    cfg.entryArguments = args;
+    cfg.entryArguments = Array.isArray(args) ? args : [];
 
     for (const k in this.cmd) {
-      const v = this.cmd[k];
-      if (typeof v === 'string' && /<module>/.test(v)) {
-        // @ts-expect-error
-        this.cmd[k] = v.replace(/<module>/g, this.getSimpleModuleName());
+      if (Object.hasOwn(this.cmd, k)) {
+        const v = this.cmd[k];
+        if (typeof v === 'string' && /<module>/.test(v)) {
+          // @ts-expect-error
+          this.cmd[k] = v.replace(/<module>/g, this.getSimpleModuleName());
+        }
       }
     }
 
@@ -115,7 +128,7 @@ export abstract class BasePackCommand<T extends CommonPackOptions, S extends Com
     }
     this.cmd.workspace = path.resolve(this.cmd.workspace);
 
-    const stream = PackOperation.runOperations(cfg, this.getOperations());
+    const stream = this.runOperations(cfg);
 
     // Eject to file
     if (this.cmd.ejectFile) {
@@ -125,7 +138,13 @@ export abstract class BasePackCommand<T extends CommonPackOptions, S extends Com
       }
       await PackUtil.writeEjectOutput(this.cmd.workspace, cfg.module, output, this.cmd.ejectFile);
     } else {
-      await GlobalTerminal.streamLinesWithWaiting(stream, { initialDelay: 0, cycleDelay: 100, end: true });
+      await GlobalTerminal.streamLinesWithWaiting(stream, {
+        initialDelay: 0,
+        cycleDelay: 100,
+        end: false,
+        position: 'inline',
+        committedPrefix: String.fromCharCode(171)
+      });
       let msg = cliTpl`${{ success: 'Success' }} (${{ identifier: TimeUtil.prettyDeltaSinceTime(start) }}) ${{ subtitle: 'module' }}=${{ param: this.cmd.module }}`;
       if (this.cmd.output) {
         msg = cliTpl`${msg} ${{ subtitle: 'output' }}=${{ path: this.cmd.output }}`;

package/support/pack.dockerfile.ts

@@ -0,0 +1,9 @@
+import { DockerPackFactory } from './bin/types';
+
+export const factory: DockerPackFactory = cfg => `
+FROM ${cfg.dockerImage}
+WORKDIR /app
+COPY . .
+${cfg.dockerPort.map(port => `EXPOSE ${port}`).join('\n')}
+ENTRYPOINT ["/app/${cfg.entryCommand}.sh"]
+`;