@suffolklitlab/alkiln 5.15.4 → 5.16.0

package/.github/workflows/da_image_v_sha_7d13853.yml

@@ -0,0 +1,67 @@
+name: Use docassemble image version
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      show_docker_output:
+        required: false
+        default: false
+        type: boolean
+        description: 'Show the docker logs while building the GitHub server container. It will also save the docker log artifact. This might show sensitive config information.'
+      # Experimental
+      enable_tmate:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+jobs:
+
+  github-server-tests:
+    # Avoids running double tests when someone on the team makes a pull request
+    # 1: Trigger job on push or dispatch from this repository
+    # 2: Trigger job on pull request from a fork
+    if: (
+          github.event_name != 'pull_request'
+          && ! github.event.pull_request.head.repo.fork
+        ) || (
+          github.event_name == 'pull_request'
+          && github.event.pull_request.head.repo.fork
+        )
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24.x]
+      
+    steps:
+      # Place the root directory in this branch to access relative paths to
+      # action files
+      - uses: actions/checkout@v4
+
+      - name: "ALKiln - Use a specific docassemble image version to start the isolated temporary docassemble server on GitHub"
+        id: github_server
+        uses: ./action_for_github_server
+        with:
+          SHOW_DOCKER_OUTPUT: "${{ github.event.inputs.show_docker_output }}"
+          DOCASSEMBLE_IMAGE: "ghcr.io/suffolklitlab/docassemble:sha-7d13853"
+      - run: echo "ALKiln finished starting the isolated GitHub docassemble server"
+        shell: bash
+
+      ## Optional debugging to explore things like docker issues
+      #- name: Docker debug tmate session
+      #  #if: ${{ failure() && github.event.inputs.enable_tmate == 'true' }}
+      #  uses: mxschmitt/action-tmate@v3
+
+      - name: "ALKiln - Confirm docassemble packages get installed correctly"
+        if: ${{ success() }}
+        id: alkiln
+        uses: ./
+        with:
+          # Required inputs. See
+          # https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#sandbox-inputs
+          SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
+          DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
+          INSTALL_METHOD: "server"
+          ALKILN_TAG_EXPRESSION: "@e3"  # One very simple test

package/CHANGELOG.md

@@ -43,7 +43,26 @@ Format:
 - 
 -->
 
-<!-- ## [Unreleased] -->
+## [5.16.0] - 2026-05-14
+
+### Added
+
+- Adds a new optional parameter to `action_for_github_server/action.yml`, the full name of the docassemble image. It defaults to `jhpyle/docassemble:latest`, what we previously used, but can also be changed to an earlier version (`jhpyle/docassemble:1.9.8`) or a different fork of docassemble (`ghcr.io/suffolklitlab/docassemble:latest`). Note that old docassemble versions may sometimes get removed.
+
+### Changed
+
+- Changed the default version of docassemblecli to 0.0.25
+- Use `cwd` as the base of file paths. Motivated by ALKiP's upcoming need to change the way it handles its own file paths.
+- Handle curl failures while waiting for docassemble server startup. Wrapped the curl call with set +e / set -e so GitHub Actions does not exit on curl failures. All non-zero curl exit codes are treated as "not ready yet" and retried - this covers transient errors like exit code 56 (connection dropped) and exit code 7 (connection refused) that may come up during startup. Added a comment explaining the permissive approach. Changed response value from "000" to "missing" for clarity in logs. See [#1044](https://github.com/SuffolkLITLab/ALKiln/issues/1044).
+
+### Fixed
+
+- Print error correctly when missing sources paths
+- Changed the default version of docassemblecli to 0.0.25
+
+### Security
+
+- Security: Gave our main action's `npm install` call the arguments ` --ignore-scripts --min-release-age=7` to improve security against malicious `pre-install` and `post-install` scripts. See [#1053](https://github.com/SuffolkLITLab/ALKiln/issues/1053).
 
 ## [5.15.4] - 2025-11-29
 
@@ -1235,4 +1254,4 @@ Note: published on incorrect commit
 - `example.feature` - an example test to get a project started
 - `github/workflows/run_form_tests.yml` - Automated github workflow to run tests when code is pushed and a manual trigger for testing without needing to push
 - `.gitignore` - ignores files that are generated by the tests and shouldn't be added to the repo
-- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run
+- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run

package/action.yml

@@ -120,7 +120,9 @@ runs:
       run: |
         log="💡 ALK0026 INFO: Install ALKiln directly from npm"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"
+        npm install --ignore-scripts --min-release-age=7 -g "@suffolklitlab/alkiln@$ALKILN_VERSION"
+        npm rebuild -g puppeteer --update-binary
+
 
     # Files prep
     - shell: bash

package/action_for_github_server/action.yml

@@ -23,10 +23,14 @@ inputs:
     description: "Default is 600 seconds. Maximum amount of seconds to give the docassemble docker container to serve the site."
     required: false
     default: 600  # 10 min
+  DOCASSEMBLE_IMAGE:
+    description: "The specific docassemble image to use."
+    required: false
+    default: jhpyle/docassemble
   DOCASSEMBLECLI_VERSION:
     description: "The version of docassemblecli to install."
     required: false
-    default: "0.0.17"
+    default: "0.0.25"
 
 outputs:
   DOCASSEMBLE_DEVELOPER_API_KEY:
@@ -155,35 +159,37 @@ runs:
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         env:
           CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
+          DOCASSEMBLE_IMAGE: "${{ inputs.DOCASSEMBLE_IMAGE }}"
         shell: bash
         run: |
           log="💡 ALK0009 INFO: Download and start docker silently"
           echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
-          docker pull jhpyle/docassemble > /dev/null 2>&1
+          docker pull "$DOCASSEMBLE_IMAGE" > /dev/null 2>&1
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
                      --env DA_ADMIN_PASSWORD="$DA_ADMIN_PASSWORD" \
                      --env DA_ADMIN_API_KEY="$DA_ADMIN_API_KEY" \
                      $CONFIG_ARGS \
                      --cap-add SYS_PTRACE \
-                     --memory="4gb" -d -p 80:80 jhpyle/docassemble > /dev/null 2>&1
+                     --memory="4gb" -d -p 80:80 "$DOCASSEMBLE_IMAGE" > /dev/null 2>&1
       # With output
       - name: "💡 ALK0010 INFO: Download and start docker"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
         env:
           CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
+          DOCASSEMBLE_IMAGE: "${{ inputs.DOCASSEMBLE_IMAGE }}"
         shell: bash
         run: |
           log="💡 ALK0010 INFO: Download and start docker"
           echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
-          docker pull jhpyle/docassemble
+          docker pull "$DOCASSEMBLE_IMAGE"
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
                      --env DA_ADMIN_PASSWORD="$DA_ADMIN_PASSWORD" \
                      --env DA_ADMIN_API_KEY="$DA_ADMIN_API_KEY" \
                      $CONFIG_ARGS \
                      --cap-add SYS_PTRACE \
-                     --memory="4gb" -d -p 80:80 jhpyle/docassemble
+                     --memory="4gb" -d -p 80:80 "$DOCASSEMBLE_IMAGE"
 
       # Section for showing the time it takes to start the server.
 
@@ -213,14 +219,25 @@ runs:
 
             # Check if max seconds till loading has passed
             if [[ $SECONDS -ge $MAX_SECONDS_FOR_DOCKER ]]; then
-              log3="🤕 ALK0014 ERROR: Timed out waiting for docker container to serve the site. If you want to give your docker container more timem to install, set the MAX_SECONDS_FOR_DOCKER input for this action."
+              log3="🤕 ALK0014 ERROR: Timed out waiting for docker container to serve the site. If you want to give your docker container more time to install, set the MAX_SECONDS_FOR_DOCKER input for this action."
               echo -e "\n$log3" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log3"
               exit 1
             fi
 
             # Set the variable to a new string value in each iteration
-            response=$(curl -o /dev/null -s -w "%{http_code}\n" http://localhost:80/health_check?ready=1)
-            log4="💡 ALK0015 INFO: Response is $response"
+            # We intentionally skip all non-zero curl exit codes here instead of handling specific ones.
+            # During server startup there are several transient errors that can come up and since we already log  the exit code and have a timeout,
+            # retrying on all of them is safer than trying to maintain a list of specific codes to handle.
+            set +e
+            response=$(curl -o /dev/null -s -w "%{http_code}" http://localhost:80/health_check?ready=1)
+            status=$?
+            set -e
+            
+            if [[ $status -ne 0 ]]; then
+              response="missing"
+            fi
+
+            log4="💡 ALK0015 INFO: Response is $response (curl exit code: $status)"
             echo -e "\n$log4" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log4"
 
             # Check if the string includes the desired text
@@ -228,7 +245,7 @@ runs:
               log5="💡 ALK0016 SUCCESS: Success! The docker container is ready!"
               echo -e "\n$log5" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log5"
             else
-              log6="💡 ALK0017 INFO: The docker container is not ready yet. Will check again in 30 seconds."
+              log6="💡 ALK0017 INFO: The docker container is not ready yet (HTTP=$response, curl exit code=$status). Will check again in 30 seconds."
               echo -e "\n$log6" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log6"
               sleep 30
             fi

package/docs/016_root_path_2026_04_09.md

@@ -0,0 +1,17 @@
+# Root path
+
+This code assumes the current working directory (cwd) will contain the necessary files and folders to get files like `.feature` files and the test run runtime config file.
+
+When you run ALKiln on the command line, run the tests in the root directory of the docassemble package with the tests. There are other ways to tell processes where the root directory is. For example, ALKiP, a docassemble package that uses ALKiln inside an author's server, runs `subprocess.run()` or `subprocess.Popen()` with `cwd=`. In ALKiP the `cwd` is most likely `/tmp`.
+
+Files that make this root path assumption:
+
+- lib/utils/set_sources_paths.js
+- lib/utils/files.js
+- lib/utils/session_vars.js
+
+ALKiln makes assumptions about specific folder names inside the root directory. See `lib/utils/set_sources_paths.js` and `validate.js` for where it looks for `.feature` files.
+
+## Anti-goals
+
+It is possible for us to make the root path configurable in a few ways (env vars, command line args, etc.), but we are avoiding adding that maintenance cost until we see a need.

package/lib/scope.js

@@ -2768,7 +2768,7 @@ module.exports = {
         pic_name = `pic_on-${ short_id }-${ timestamp }`;
       }
 
-      await scope.take_a_screenshot( scope, { path: `./${ scope.paths.scenario }/${ pic_name }.jpg` });
+      await scope.take_a_screenshot( scope, { path: `${ scope.paths.scenario }/${ pic_name }.jpg` });
 
       await scope.afterStep( scope );
     },  // Ends scope.steps.screenshot()

package/lib/setup/artifacts.js

@@ -2,19 +2,19 @@
 
 const session_vars = require(`../utils/session_vars`);
 const files = require(`../utils/files`);
-const Log = require(`../setup/artifacts.js`);
+const Log = require(`../utils/Log.js`);
 
-/** Reset and refresh artifacts path name */
+/**
+ * Reset and refresh artifacts path name. Use this at the start of every test
+ * run for that run's unique results.
+ * */
 
 session_vars.delete_artifacts_path_name();
 
-// process.argv is a list of strings of commands and args.
-// If using `npm run cucumber` (as opposed to the bin commands),
-// use `--` before `--sources=./foo`
-const argv = require(`minimist`)( process.argv.slice(2) );
-const artifacts_path = files.make_artifacts_folder( argv.path );
-
+const artifacts_path = files.make_artifacts_folder();
 session_vars.save_artifacts_path_name( artifacts_path );
 
-// Leave the config Project name value as it is. Local developers find it
-//    useful to re-use that value.
+const log = new Log({ path: artifacts_path, context: `artifacts` });
+log.info({ code: `ALK0278`, context: `artifacts`,},
+  `Created the artifacts folder at "${ artifacts_path }"`
+);

package/lib/utils/Log.js

@@ -228,6 +228,7 @@ class Log {
       }
 
       if ( !fs.existsSync( dir )) {
+        process.stdout.write(`Making artifacts folder in Log at ${ dir }`)
         files.make_artifacts_folder( dir );
       }
 

package/lib/utils/files.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const safe_filename = require('sanitize-filename');
+const path = require(`path`);
 
 let files = {};
 
@@ -21,27 +22,30 @@ files.readable_date = function() {
   return fancy_str;
 };  // Ends files.readable_date()
 
-files.make_artifacts_folder = function (path) {
+files.make_artifacts_folder = function ( file_path ) {
   /** Makes a folder in the root of the project if it doesn't
    *  already exist, either with the given name or with a default name.
    *
    * Works for local development as well, without action.yml or workflow files.
    * */
-  if (path) {
-    let name_parts = path.split(`/`);
+  if (file_path) {
+    let name_parts = file_path.split(`/`);
     let safe_parts = [];
     for ( let part of name_parts ) {
       safe_parts.push(safe_filename( part ));
     }
-    path = safe_parts.join(`/`);
+    file_path = path.join( ...safe_parts );
   } else {
-    path = `alkiln-${ files.readable_date() }`
+    file_path = `alkiln-${ files.readable_date() }`
   }
 
+  const root = process.cwd();
+  root_path = path.join( root, file_path );
+
   // `recursive` avoids errors if folder already exists
   // https://nodejs.org/docs/latest-v18.x/api/fs.html#fspromisesmkdirpath-options
-  fs.mkdirSync( path, { recursive: true });
-  return path;
+  fs.mkdirSync( root_path, { recursive: true });
+  return root_path;
 };  // Ends files.make_artifacts_folder()
 
 module.exports = files;

package/lib/utils/session_vars.js

@@ -52,6 +52,10 @@ session_vars.get_origin = function () {
 };
 session_vars.get_user_project_name = function () { return process.env._PROJECT_NAME || null; };
 session_vars.get_user_id = function () { return process.env._USER_ID || null; };
+session_vars.get_runtime_config_path = function () {
+  const root = process.cwd();  // absolute path just to be sure
+  return path.join( root, `runtime_config.json` );
+}
 
 // More complex logic
 session_vars.get_server_reload_timeout = function () {
@@ -133,7 +137,6 @@ session_vars.get_languages = function () {
 };  // Ends session_vars.get_languages()
 
 
-const runtime_config_path = `runtime_config.json`;
 const project_name_key = `da_project_name`;
 session_vars.save_project_name = function ( project_name ) {
   /* Saves the name of the project to a json obj so deletion can use it later.
@@ -142,6 +145,7 @@ session_vars.save_project_name = function ( project_name ) {
   *    Should we try to prevent someone overwriting a previous project name?
   * 
   * @param project_name { string } - purely alphanumeric string */
+  const runtime_config_path = session_vars.get_runtime_config_path();
 
   // Warn local developers if file already exists
   if ( fs.existsSync( runtime_config_path ) ) {
@@ -172,6 +176,8 @@ session_vars.get_project_name = function () {
   if ( session_vars.get_origin() === 'playground' ) {
     return session_vars.get_user_project_name();
   }
+
+  const runtime_config_path = session_vars.get_runtime_config_path();
   let json = JSON.parse( fs.readFileSync( runtime_config_path ));
   let project_name = json[ project_name_key ] || null;
   if ( session_vars.get_debug() ) { console.debug( `🐛 ALK0037 DEBUG: Project name from file is "${ project_name }".` ); }
@@ -180,6 +186,7 @@ session_vars.get_project_name = function () {
 
 session_vars.delete_project_name = function () {
   /* Empty the key storing the name of the docassemble Project */
+  const runtime_config_path = session_vars.get_runtime_config_path();
   try {
     // Get the json, changing it, and re-write the file from scratch
     let json = JSON.parse( fs.readFileSync( runtime_config_path ));
@@ -252,6 +259,7 @@ session_vars.save_runtime_config_var = function ({ key, value }) {
   * 
   * @returns {binary?} file Runtime config file
   */
+  const runtime_config_path = session_vars.get_runtime_config_path();
 
   // Ensure runtime config file exists
   if ( !fs.existsSync( runtime_config_path ) ) {
@@ -277,6 +285,7 @@ session_vars.get_runtime_config_var = function ( key ) {
    * 
    * @returns {any} - Value of given key in runtime config file or null
    */
+  const runtime_config_path = session_vars.get_runtime_config_path();
   try {
     let json = JSON.parse( fs.readFileSync( runtime_config_path ));
     let value = json[ key ];
@@ -300,6 +309,7 @@ session_vars.delete_runtime_config_var = function ({ key }) {
    * 
    * @returns {null}
    * */
+  const runtime_config_path = session_vars.get_runtime_config_path();
   try {
     if ( !fs.existsSync( runtime_config_path )) { return null; }
     

package/lib/utils/set_sources_paths.js

@@ -1,4 +1,5 @@
 const fast_glob = require(`fast-glob`);
+const path = require(`path`);
 
 const session_vars = require(`./session_vars`);
 
@@ -18,7 +19,7 @@ module.exports = function set_sources_paths({ log }) {
   let maybe_paths = get_potential_paths();
 
   let sources_paths = get_sources_paths({ maybe_paths });
-  if ( sources_paths === 0 ) {
+  if ( sources_paths.length === 0 ) {
     // If we don't throw, it'll be more confusing when no tests run
     log.throw({ code: `ALK0050`, context: `sources`,
       error: new ReferenceError(
@@ -45,6 +46,7 @@ function get_potential_paths() {
   // `project` is the name in the server docassemble "Project" page
   let project = session_vars.get_user_project_name();
   let id = session_vars.get_user_id();
+  let root = process.cwd();  // Assumes correct root. See docs about root path.
 
   // process.argv is a list of strings of commands and args.
   // Internal note: If using `npm run cucumber`, use `--` before
@@ -53,8 +55,8 @@ function get_potential_paths() {
     default: {
       sources: [
         `./docassemble/*/data/sources`,  // In GitHub folder
-        `/usr/share/docassemble/files/playgroundsources/${id}/${project}/*.feature`, // From playground without S3
-        `/tmp/playgroundsources/${id}/${project}/*.feature` // From playground with S3
+        `/usr/share/docassemble/files/playgroundsources/${id}/${project}`, // From playground without S3
+        path.join( root, `/playgroundsources/${id}/${project}`), // From playground with S3
       ],
     }
   });
@@ -81,16 +83,16 @@ function get_sources_paths({ maybe_paths }) {
   // Check every path, tracking which exist and which are missing
   let existing_paths = [];
   let missing_paths = [];
-  for ( let path of maybe_paths ) {
+  for ( let maybe_path of maybe_paths ) {
     let dirs = fast_glob.sync(
-      [ path ],
+      [ maybe_path ],
       { onlyFiles: false, suppressErrors: true }
     );
 
     if ( dirs.length > 0 ) {
       existing_paths.push( ...dirs );
     } else {
-      missing_paths.push( path );
+      missing_paths.push( maybe_path );
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.15.4",
+  "version": "5.16.0",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {