@suffolklitlab/alkiln 5.3.0 → 5.4.1-feat-github-server-15

package/.github/workflows/github_server.yml

@@ -0,0 +1,85 @@
+name: GitHub server tests
+
+on:
+  push:
+  # `workflow dispatch` isn't showing up in github because it's not the default branch
+  # See https://stackoverflow.com/a/75250828
+  workflow_dispatch:
+    inputs:
+      tags:
+        required: False
+        description: 'Optional. Use a "tag expression" specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)'
+        # # Only test 2 tests - one uses an env var, the other uses AL.
+        # # They test if env vars get set correctly and depencencies get
+        # # pulled in correctly.
+        # default: '@al1'
+      enable_tmate:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+      # TODO: alkiln_version:
+
+jobs:
+
+  github-server-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    env:
+      # How would a dev make another user/password if they wanted to?
+      SECRET_VAR1: secret-var1-value
+      SECRET_VAR2: secret-var2-value
+      SECRET_FOR_MISSING_FIELD: secret for missing field
+      #_ALKILN_DANGEROUS_DEBUG: true
+      
+    steps:
+      # Place the root directory in this branch
+      - uses: actions/checkout@v3
+
+      # Debugging. Maybe add a long sleep after whatever it is we want to check
+      # to give us time to explore.
+      - name: Setup tmate session
+        if: ${{ inputs.enable_tmate }}
+        uses: mxschmitt/action-tmate@v3
+        with:
+          detached: true
+
+      - name: Start the temporary GitHub server
+        id: github_server
+        uses: ./github_server
+        with:
+          CONFIG_CONTENTS: "${{ secrets.CONFIG_CONTENTS }}"
+      - run: echo "Finished starting the GitHub server"
+
+      # Debugging on failure
+      # Trying to catch that intermittent bug mentioned in ./github_server/action.yml
+      - name: Docker failure tmate session
+        if: ${{ failure() }}
+        uses: mxschmitt/action-tmate@v3
+
+      - name: Env vars from server output
+        run: |
+          echo "USER1_EMAIL=${{ steps.github_server.outputs.DA_ADMIN_EMAIL }}" >> $GITHUB_ENV
+          echo "USER1_PASSWORD=${{ steps.github_server.outputs.DA_ADMIN_PASSWORD }}" >> $GITHUB_ENV
+      #- name: Work with docker
+      #  run: |
+      #    # Authors can use this to do more with the docker container.
+      #    # There may be a better way. Would take research. A docker action?
+      #    container_name=$(docker ps --format '{{.Names}}' | head -n 1)
+      #    echo "container_name is $container_name"
+
+      - name: "Run ALKiln tests"
+        if: ${{ success() }}
+        uses: ./
+        with:
+          SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
+          DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
+          INSTALL_METHOD: "server"
+          # TODO: See what happens if this is an empty string
+          ALKILN_VERSION: "5.4.1-feat-github-server-15"
+          ALKILN_TAG_EXPRESSION: "@al1"
+      - run: echo "Finished running ALKiln tests"
+

package/CHANGELOG.md

@@ -44,6 +44,19 @@ Format:
 -->
 <!-- ## [Unreleased] -->
 
+## [5.4.1] - 2023-10-18
+
+### Internal
+- BREAKS ALKilnInThePlayground v1.2.0 and below (as we discussed) as that project is still exploratory. Can now take the location of the "sources" folder or folders as an argument in the command line. The formats are `npm run cucumber @tags -- --sources=./foo` and `alkiln-run @tags --sources=./foo`.
+
+## [5.4.0] - 2023-10-14
+
+### Added
+
+- New step to compare PDFs!
+    - An example: `I expect the baseline PDF "something-in-sources.pdf" and the new PDF "downloaded.pdf" to be the same`
+    - See [#774](https://github.com/SuffolkLITLab/ALKiln/pull/774) for more details.
+
 ## [5.3.0] - 2023-10-14
 
 ### Added

package/action.yml

@@ -22,6 +22,15 @@ inputs:
     description: "Max amount of time to give the server to reload if it needs to"
     required: false
     # no default to let the custom Scenario timeouts create the reload timeout
+  # INSTALL_LOCATION? Will that get confused with the location passed into the command line?
+  # Maybe `INSTALL_LOCATION` could be "playground", "server", or a custom path and we could handle all those.
+  INSTALL_METHOD:
+    description: "Default is 'playground'. Other option: 'server'. How to install the package onto the server."
+    required: false
+    default: "playground"
+  ALKILN_TAG_EXPRESSION:
+    description: "The tag expression to use to limit which tests to run. Default is no tag expression."
+    required: false
 
 runs:
   using: "composite"
@@ -46,29 +55,43 @@ runs:
         echo -e "\nALKiln version is $ALKILN_VERSION\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nMAX_SECONDS_FOR_SETUP is $MAX_SECONDS_FOR_SETUP\nSERVER_RELOAD_TIMEOUT_SECONDS is $SERVER_RELOAD_TIMEOUT_SECONDS\n"
       shell: bash
 
-    # Install node
+    # Install
     - name: "ALKiln: Install node packages"
       uses: actions/setup-node@v3
       with:
         node-version: "18"
     - name: Install ALKiln directly from npm
       run: |
-        npm install -g @suffolklitlab/alkiln
+        npm install -g @suffolklitlab/alkiln@$ALKILN_VERSION
       shell: bash
 
-    # Run tests
+    # Install on playground
     - name: "ALKiln: Create a Project and pull the package from GitHub"
+      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-setup
       shell: bash
+    - run: echo -e "\n\n====\nALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
+      if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
+      shell: bash
+
+    # Install on server
+    - name: "ALKiln: Install the GitHub package onto the server"
+      if: ${{ inputs.INSTALL_METHOD == 'server' }}
+      run: alkiln-server-install
+      shell: bash
+    - run: echo -e "\n\n====\nALKiln could not install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
+      if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
+      shell: bash
+
+    # run tests
     - name: "ALKiln: Run tests"
       if: ${{ success() }}
-      run: alkiln-run ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
-      shell: bash
-    - run: echo -e "\n\n====ALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
-      if: ${{ failure() }}
+      run: alkiln-run ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       shell: bash
-    - name: "ALKiln: Delete project from docassemble test account"
-      if: ${{ always() }}
+    
+    # on playground, delete project
+    - name: "ALKiln: Try to delete the project from the playground of the docassemble test account."
+      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-takedown
       shell: bash
     
@@ -81,7 +104,7 @@ runs:
         path: ./alkiln-*
 
 # ##################################
-# # A developer's workflow should look similar to the below
+# # A developer's workflow should look similar to the below.
 # # In place of `uses: suffolkLITLab/ALKiln@v5`, they
 # # might use another version.
 #

package/github_server/action.yml

@@ -0,0 +1,165 @@
+name: "ALKiln/github_server: Isolated docassemble tests"
+description: "Download and start up a temporary docassemble server on GitHub's servers, in an isolated environment. Avoids docassemble reload errors and other external factors."
+
+# Bug? Race condition? Exit with 52 when waiting for container to finish starting
+# https://github.com/SuffolkLITLab/ALKiln/actions/runs/5912900256/job/16036751264#step:4:188
+# Had no completion messages, but it exited with an error anyway
+# Took 121 seconds
+# The rerun of the test completed that step just fine, though it took less time
+# Took 120 and was fine: https://github.com/SuffolkLITLab/ALKiln/actions/runs/5913167036/job/16037288791
+# 150 secs with exit code 56:
+# https://github.com/SuffolkLITLab/ALKiln/actions/runs/5914677262/job/16040233419#step:4:196
+# 120 sec with exit code 56:
+# https://github.com/SuffolkLITLab/ALKiln/actions/runs/5914963614/job/16040773624#step:4:206
+
+# If we want to control the version of the docassemble image, we'd have
+# to make our own image:
+# You can build your own image by doing git clone jhpyle/docassemble  and then
+# using git checkout to select a particular version, and then using docker build
+# to build an image. https://docassemble.org/docs/docker.html#downgrading
+# If we just want to use an older version of da (as long as it works with
+# the latest image):
+# If you have an existing container you can use dainstall from the command
+# line to install docassemble.webapp==1.4.68
+
+inputs:
+  CONFIG_CONTENTS:
+    description: "The contents of the config file of the docassemble server"
+    required: false
+  MAX_SECONDS_FOR_DOCKER:
+    description: "Maximum amount of seconds to give the docassemble docker container to serve the site."
+    required: false
+    default: 600  # 10 min
+
+outputs:
+  DOCASSEMBLE_DEVELOPER_API_KEY:
+    description: "Use this inside `with:` for the ALKiln step. Temporary admin api key. It will be destroyed after the tests are done."
+    value: ${{ steps.api_key_output_step.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
+  SERVER_URL:
+    description: "Use this inside `with:` for the ALKiln step. URL of the temporary docassemble server."
+    value: "http://localhost"
+  DA_ADMIN_EMAIL:
+    value: ${{ steps.api_key_output_step.outputs.DA_ADMIN_EMAIL }}
+  DA_ADMIN_PASSWORD:
+    value: ${{ steps.api_key_output_step.outputs.DA_ADMIN_PASSWORD }}
+
+
+runs:
+  using: "composite"
+  steps:
+      - uses: actions/checkout@v3
+
+      - name: "ALKiln github_server: Set environment variables"
+        run: |
+          echo "DA_ADMIN_API_KEY=abcd1234abcd1234abcd5678abdc5678" >> $GITHUB_ENV
+          echo "MAX_SECONDS_FOR_DOCKER=${{ inputs.MAX_SECONDS_FOR_DOCKER }}" >> $GITHUB_ENV
+          echo "DA_ADMIN_EMAIL=admin@example.com" >> $GITHUB_ENV
+          # Login will fail if this is "password"
+          echo "DA_ADMIN_PASSWORD=@123abcdefg" >> $GITHUB_ENV
+        shell: bash
+      - id: api_key_output_step
+        run: |
+          echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DA_ADMIN_API_KEY" >> "$GITHUB_OUTPUT"
+          echo "DA_ADMIN_EMAIL=$DA_ADMIN_EMAIL" >> "$GITHUB_OUTPUT"
+          echo "DA_ADMIN_PASSWORD=$DA_ADMIN_PASSWORD" >> "$GITHUB_OUTPUT"
+        shell: bash
+
+      - name: "ALKiln github_server: Download and start docker"
+        run: |
+          mkdir /tmp/config
+          echo "${{ inputs.CONFIG_CONTENTS }}" > /tmp/config/myconfig.yml
+          docker pull jhpyle/docassemble
+          docker run --env DA_ADMIN_EMAIL="${{ env.DA_ADMIN_EMAIL }}" --env DA_ADMIN_PASSWORD="${{ env.DA_ADMIN_PASSWORD }}" --env DA_ADMIN_API_KEY="${{ env.DA_ADMIN_API_KEY }}" --env DA_CONFIG=/tmp/config/myconfig.yml --volume /tmp/config:/tmp/config --cap-add SYS_PTRACE --memory="4gb" -d -p 80:80 jhpyle/docassemble
+        shell: bash
+      - name: "ALKiln github_server: Wait for server to start"
+        run: |
+          # ALKiln github_server: Wait for server to start
+
+          # Reset the SECONDS variable
+          SECONDS=0
+          # Wait 1 minute before pinging the server constantly
+          sleep 60
+
+          # Use a variable instead of checking $response so we can control to avoid race
+          # conditions from preventing the success log message.
+          ready="false"
+
+          while [[ $ready == "false" ]]; do
+            echo "Time ellapsed: $SECONDS seconds"
+
+            # Check if max seconds till loading has passed
+            if [[ $SECONDS -ge $MAX_SECONDS_FOR_DOCKER ]]; then
+              echo "ALKiln GitHub Server 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."
+              # Exit with failure, or allow this to keep going?
+              break
+            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)
+            echo "response is $response"
+
+            # Check if the string includes the desired text
+            if [[ $response == *"200"* ]]; then
+              echo "Success! The docker container is ready!"
+              ready="true"
+            else
+              echo "The docker container isn't ready yet. Will check again in 30 seconds."
+              sleep 30
+            fi
+
+          done
+        shell: bash
+
+      # Don't rely on the environment's version of python
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - run: pip install docassemblecli
+        shell: bash
+      # Install the current directory onto the docassemble server
+
+      #- name: Setup tmate session
+      #  uses: mxschmitt/action-tmate@v3
+      
+      ## da doesn't need to know the name of the folder
+      ## alkiln does so it can locate the Project or package installed on the server
+      - run: |
+          # if `docassemble` cd `docassemble`
+          #cd docassemble
+          ## Get the name of the package folder
+          #dirs2=(*/)
+          #len=${#dirs2[@]}
+          #if (( $len > 1 ));
+          #then echo There are multiple files in your repo's `docassemble` folder. ALkiln will use the first one;
+          #fi
+          #folder=5
+          #
+          #
+          ## Get back out of the docassemble folder
+          #cd ..
+          ## Install on server
+
+          dainstall . --apiurl http://localhost --apikey $DA_ADMIN_API_KEY
+        shell: bash
+
+      # Upload artifacts that subscribers can download on the Actions summary page
+      - name: "ALKiln github_server: Docker logs"
+        if: ${{ always() }}
+        run: |
+          docker_logs=$(docker logs $(docker ps --filter "ancestor=jhpyle/docassemble" --format {{.ID}}))
+          # Should this name have a date/time attached? The logs themselves have timestamps
+          echo "$docker_logs" > /tmp/alkiln_docker_logs.txt
+        shell: bash
+    
+      # Should this date/time be created at the start of this action?
+      - name: "ALKiln github_server: Get folder name with date and time"
+        if: ${{ always() }}
+        run: |
+          echo "GITHUB_SERVER_ARTIFACT_NAME=alkiln-github-server-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
+        shell: bash
+      - name: "ALKiln github_server: Upload artifacts folder"
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.GITHUB_SERVER_ARTIFACT_NAME }}
+          path: /tmp/alkiln_docker_logs.txt

package/lib/docassemble/docassemble_api_REST.js

@@ -79,13 +79,21 @@ da.pull = async function ( timeout ) {
 };  // Ends da.pull()
 
 
+da.has_playground_task_finished = async function ( task_id, timeout ) {
+  return await da.has_task_finished( "/api/restart_status", task_id, timeout);
+}
+
+da.has_package_task_finished = async function ( task_id, timeout ) {
+  return await da.has_task_finished( "/api/package_update_status", task_id, timeout);
+}
+
 // node -e 'require("./lib/docassemble/docassemble_api_REST.js").has_task_finished()'
-da.has_task_finished = async function ( task_id, timeout ) {
+da.has_task_finished = async function ( api_endpoint, task_id, timeout ) {
   /* Check task status based on `task_id`. */
   let options = {
     method: 'GET',
     headers: {'X-API-Key': session_vars.get_dev_api_key()},
-    url: `${ session_vars.get_da_server_url() }/api/restart_status`,
+    url: `${ session_vars.get_da_server_url() }${ api_endpoint }`,
     params: {
       task_id: task_id,
     },

package/lib/docassemble/docassemble_api_interface.js

@@ -329,9 +329,8 @@ da_i.pull = async function ( pull_options ) {
   }
 };  // Ends da_i.pull()
 
-
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").has_task_finished()'
-da_i.has_task_finished = async function ( task_id, options ) {
+da_i.has_task_finished = async function ( api_endpoint, task_id, options ) {
   /** Check task status if it exists. If not, return true as task did
   *    not require a server restart. See da_i.pull().
   *    See https://docassemble.org/docs/api.html#restart_status. */
@@ -342,7 +341,7 @@ da_i.has_task_finished = async function ( task_id, options ) {
   try {
 
     // If server did need to restart, check if it's done.
-    let response = await _da_REST.has_task_finished( task_id, timeout );
+    let response = await _da_REST.has_task_finished( api_endpoint, task_id, timeout );
     log.debug({ pre: `Task status: ${ response.status }. Docassemble status text: ${ response.data.status }. Task id: ${ task_id }` });
     
     if ( response.data.status === 'completed' ) {
@@ -353,16 +352,15 @@ da_i.has_task_finished = async function ( task_id, options ) {
       return false;
 
     } else if ( response.data.status === 'unknown' ) {
-      // Server is working, but status 'unknown'? We shouldn't even
-      // get here according to the API docs, but it feels weird to have
-      // no default behavior. What to return? Throw?
+      // Server is working, but status 'unknown'? Bad design, but this
+      // does get returned when install packages, so return true
       log.info({
         pre: `\`task_id\` "${ task_id }" has expired. If it's been `
           + `less than 1 hour since the task started, the task is `
           + `complete. See https://docassemble.org/docs/api.html#restart_status.`,
-        data: response,
+        data: response.data,
       });
-      return null;
+      return true;
     }  // ends status type
 
   } catch ( error ) {
@@ -378,8 +376,15 @@ da_i.has_task_finished = async function ( task_id, options ) {
 
 };  // Ends da_i.has_task_finished()
 
+da_i.wait_for_playground_to_restart = async ( task_id, options ) => {
+  return await da_i.wait_for_server_to_restart( "/api/restart_status", task_id, options );
+};
+
+da_i.wait_for_package_to_restart = async ( task_id, options ) => {
+  return await da_i.wait_for_server_to_restart( "/api/package_update_status", task_id, options );
+};
 
-da_i.wait_for_server_to_restart = async ( task_id, options ) => {
+da_i.wait_for_server_to_restart = async ( api_endpoint, task_id, options ) => {
   /** Wait for the server to finish restarting in case a module needs to load.
   *     This is a polling function because things may be returned
   *     that aren't equivalent to the server being done with a task. */
@@ -410,7 +415,7 @@ da_i.wait_for_server_to_restart = async ( task_id, options ) => {
   while ( !done_restarting && num_tries <= max_loops ) {
     num_tries++;
     // Wait only a short time for the task to finish, not the full default timeout
-    done_restarting = await da_i.has_task_finished( task_id, { timeout: wait_for_response } );
+    done_restarting = await da_i.has_task_finished( api_endpoint, task_id, { timeout: wait_for_response } );
     if ( !done_restarting ) {
       if ( num_tries < max_loops ) {
         // Show a slightly different message after a number of tries to reassure

package/lib/docassemble/get_base_interview_url.js

@@ -10,10 +10,20 @@ let get_base_interview_url = async function () {
   *    When finishing a test, we go to the sign out page (which is supposed to help even
   *    when the user is not logged in.) We can't use `reset=2` because it caused an
   *    'Unable to locate interview session' error. */
+
   let server_url = session_vars.get_da_server_url();
-  let dev_id = await docassemble_api_interface.get_dev_id();
-  let project_name = session_vars.get_project_name();
-  return `${ server_url }/interview?new_session=1&i=docassemble.playground${ dev_id }${ project_name }%3A`;
+
+  if (session_vars.get_install_type() === `server`) {
+
+    return `${ server_url }/interview?new_session=1&i=docassemble.${session_vars.get_repo_folder_name()}%3Adata/questions/`;
+
+  } else {
+
+    let dev_id = await docassemble_api_interface.get_dev_id();
+    let project_name = session_vars.get_project_name();
+    return `${ server_url }/interview?new_session=1&i=docassemble.playground${ dev_id }${ project_name }%3A`;
+
+  }
 };
 
 module.exports = get_base_interview_url;

package/lib/docassemble/server_install.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+const session_vars = require('../utils/session_vars');
+const log = require('../utils/log');
+// const path = require('path');
+// const fs = require('fs');
+const fg = require('fast-glob');
+
+const server_install = async () => {
+  session_vars.save_install_type(`server`);
+
+  let current_dir = process.cwd();
+  let path = `${ current_dir }/docassemble/*`;
+  let dirs = fg.sync(
+    [ path ],
+    {
+      suppressErrors: true,
+      onlyDirectories: true
+    }
+  );
+  console.log(`\n===========\n${dirs}\n===========\n`);
+
+  let chosen_dir = dirs[0];
+  if ( dirs.length === 0 ) {
+    let msg = `There are 0 folders at ${path}. Tests won't run.`;
+    log.error({ type: `setup`, data: msg })
+    throw new ReferenceError( msg );
+  }
+
+  if ( dirs.length > 1 ) {
+    log.warn({
+      type: `setup`,
+      data: `There are ${dirs.length} folders at ${path}: "${dirs.join('", ')}". ALKiln chose to use the folder "${chosen_dir}".`
+    })
+  }
+
+  session_vars.set_repo_folder_name( chosen_dir );
+};  // Ends server_install();
+
+server_install();

package/lib/docassemble/setup.js

@@ -39,7 +39,7 @@ const setup = async () => {
   let task_id = await da_i.pull();
   // Task id will be null if server did not need to restart
   if ( task_id ) {
-    await da_i.wait_for_server_to_restart( task_id );
+    await da_i.wait_for_playground_to_restart( task_id );
   }
 
   // Finish

package/lib/run_cucumber.js

@@ -6,64 +6,97 @@ const session_vars = require('./utils/session_vars');
 
 const cucumber_api = require('@cucumber/cucumber/api');
 
-(async function main() {
-  let argv = process.argv;
-
-  const environment = { cwd: process.cwd() };
-  console.log("alkiln-run: environment: %o", environment);
-  const provided_config = {
-    "publishQuiet": true,
-    "require": "./lib/index.js",
-    "format": ["progress", "summary:cucumber-report.txt"],
-    "paths": ["docassemble/*/data/sources/*.feature"],
-    "retry": 1,
-  }
-
-
-  // If they're running it from an interview on their server instead of from GitHub
-  if ( session_vars.get_origin() === `playground` ) {
-    provided_config.paths.push(`/usr/share/docassemble/files/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
-    // For S3
-    provided_config.paths.push(`/tmp/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
+function build_config( command_args ) {
+  // Turn all the paths to the sources folders into paths to the feature files
+  let sources_paths = session_vars.get_sources_paths();
+  let feature_paths = [];
+  for ( let source of sources_paths ) {
+    feature_paths.push( `${ source }/*.feature` );
   }
 
-  let tags = argv.slice(2);
-  if ( session_vars.get_origin() === `playground` ) {
-    tags = session_vars.get_tags();
+  const config = {
+    publishQuiet: true,
+    require: `./lib/index.js`,
+    format: [`progress`, `summary:cucumber-report.txt`],
+    paths: feature_paths,
+    retry: 1,
   }
 
+  // Normalize tag expressions, if there are any
+  let tags = command_args[`_`];
   if (tags.length > 0) {
     let joined_tags = '';
     // Cucumber expects tags in boolean expressions, like (@a0 or @a1) and @random.
     // If we get a list of only tags, then "or" them all together
-    if (tags.every((val) => val.startsWith("@"))) {
-      joined_tags = tags.join(' or ');
+    if (tags.every((val) => val.startsWith(`@`))) {
+      joined_tags = tags.join(` or `);
     }
     // If we get a list of seemingly no tags, assume they meant to use tags
-    else if (tags.every((val) => !val.startsWith("@"))) {
-      joined_tags = tags.map((val) => "@" + val).join(' or ');
+    else if (tags.every((val) => !val.startsWith(`@`))) {
+      joined_tags = tags.map((val) => `@` + val).join(` or `);
     }
     // If it's a mix of tags and no tags, it's probably a boolean expression!
     else {
-      joined_tags = tags.join(' ');
+      joined_tags = tags.join(` `);
     }
 
-    provided_config.tags = joined_tags;
-  }  // end if there are tags
+    config.tags = joined_tags;
+  }
+
+  return config;
+};  // Ends build_config()
+
+
+(async function main() {
+  /** Create the cucumber config, run the tests, create and
+  *   manipluate the output. */
+  const environment = { cwd: process.cwd() };
+  console.log("alkiln-run: environment: %o", environment);
+
+  // We'll use the user info to construct the possible paths to /sources
+  let id = session_vars.get_user_id();
+  // `project` is the name in the server docassemble "Project" page
+  let project = session_vars.get_user_project_name();
+
+  // process.argv is a list of strings of commands and args.
+  // If using `npm run cucumber`, use `--` before `--sources=./foo`
+  let argv = require(`minimist`)( process.argv.slice(2), {
+    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
+      ],
+    }
+  });
+  
+  // Make sure `sources` is always a list
+  let sources_list = argv.sources;
+  if ( typeof argv.sources === `string` ) {
+    sources_list = [ argv.sources ];
+  }
 
+  let one_dir_exists = session_vars.set_sources_paths( sources_list );
+  if ( !one_dir_exists ) {
+    // If we don't throw, it'll be more confusing when no tests run
+    throw new ReferenceError( `ALKiln ERROR: ALKiln can't find your "sources" folder(s). See above for details.`);
+  }
+  
   const { runConfiguration } = await cucumber_api.loadConfiguration({
-    provided: provided_config
+    provided: build_config( argv ),
   }, environment);
+
   console.log("alkiln-run: runConfiguration: %o", runConfiguration);
+
   var path = require('path');
   var codeDir = path.dirname(require.main.filename);
+  console.log("alkiln-run: working directory: %o", codeDir);
   const support = await cucumber_api.loadSupport({ support: {
-    requireModules: [`${ codeDir }/index.js`],
-    requirePaths: [ `${ codeDir }/index.js`],
+    requireModules: [ `${ codeDir }/index.js` ],
+    requirePaths: [ `${ codeDir }/index.js` ],
     importPaths: [],
   }, sources: {paths: []}}, environment);
 
-  console.log("alkiln-run: working directory: %o", codeDir);
   console.log(`\n\n`);
 
   const { success } = await cucumber_api.runCucumber({...runConfiguration, support});
@@ -86,6 +119,6 @@ const cucumber_api = require('@cucumber/cucumber/api');
 
     // Put it in the correct file in the correct folder
     let artifacts_path = session_vars.get_artifacts_path_name();
-    fs.appendFileSync( `${ artifacts_path}/${ log.debug_log_file }`, data);
+    fs.appendFileSync( `${ artifacts_path }/${ log.debug_log_file }`, data);
   });
 })();