@suffolklitlab/alkiln 5.14.0 → 5.15.0-deps-2

package/.github/workflows/github_server.yml

@@ -160,7 +160,7 @@ jobs:
           #### Developer note: You can probably leave the rest out
           #### To learn more, see https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
-          # ALKILN_VERSION: "5.13.4-feat-textarea-1"
+          # ALKILN_VERSION: 
 
       #### Developer note: Example of making an issue when tests fail
       #### that includes the text of the failure output file

package/.github/workflows/playground.yml

@@ -76,9 +76,10 @@ jobs:
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ env.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           #### Developer note: See https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           #### You can probably leave this out
+          ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO: 10
           # Internal: docassemble changes sometimes break @a11y tests. That is
           # a da problem, not ours. We will trigger these tests manually when we
           # want to check up on this.
           ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
           #### Developer note: You can probably leave this out
-          # ALKILN_VERSION: "5.13.4-feat-textarea-1"
+          # ALKILN_VERSION: 

package/CHANGELOG.md

@@ -45,6 +45,35 @@ Format:
 
 <!-- ## [Unreleased] -->
 
+## [5.15.0] - 2025-05-22
+
+### Added
+
+- Add the `constrained random answers` Step. You must put the Step in a "constrained random test template" Scenario which goes in a "constrained random test template" file - a `.feature` file that starts with "alkiln_random". The file **MUST have ONLY 1 Scenario per template file** at the moment. The Step is pretty strict. If there are irregularities, it will probably fail, but it will fail quickly. It is flexible about number of tests, though, and will default to 1. Closes [#962](https://github.com/SuffolkLITLab/ALKiln/issues/962).
+- Add `ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO` optional environment variable for the above `constrained random answers` Step. Default value is `40` until we hear otherwise.
+- Regular tests that have incorrect syntax will fail more quickly now - very near the start. So will invalid "constrained random test template" files. This will be a little slower for GitHub Sandbox tests right now, but still faster than it has been in the past. Closes [#972](https://github.com/SuffolkLITLab/ALKiln/issues/972).
+
+### Changed
+
+- Improve report indentation and tweak styling.
+- Clarify some logs, including addressing bite-sized issues like [#981](https://github.com/SuffolkLITLab/ALKiln/issues/981).
+- The report now shows the name of every Step that gets run in a test.
+
+### Internal
+
+- Added: `lib/globals.js` file to hold some shared constant values across the framework. It should NOT manage state. We may want to change the name to `constants.js` or `global_contants.js`. Let's see how it serves us.
+- Added: executable scripts for more setup steps - managing the artifacts path (at the start of a run) and validating and generating files.
+- Changed: `Log` now prioritizes what folder it stores files in in this order:
+    1. Use the argument to use an existing folder and save that to runtime_config.json at root.
+    2. Use the argument to make a new folder with that name and save that to runtime_config.json at root.
+    3. Use the alread-existing folder name value in runtime_config.json at root
+    4. Create a new folder and save that to runtime_config.json at root
+- Changed: Add `.error()` to `Log` for visual clarity when storing an error to throw later. We need to discuss this behavior and its return value. To make that work Logs can now get the `error` prop without throwing an error.
+- Changed: the Story Table step now accepts multiple ids and stops at whatever id it reaches first. I highly recommend that only ALKiln generated tests use this feature. We may avoid documenting it unless authors ask for it.
+- Changed: `.gitignore` and `.npmignore` more things
+- Fixed: log codes checker obob.
+- Fixed: updated `actions/upload-artifact@v3` to `actions/upload-artifact@v4`
+
 ## [5.14.0] - 2025-05-15
 
 ### Added

package/action.yml

@@ -33,6 +33,10 @@ inputs:
     description: "The version of docassemblecli to install."
     required: false
     default: "0.0.17"
+  ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO:
+    description: "The maximum number of tests ALKiln will generate for every Scenario that can generate tests."
+    required: false
+    # Default will be internal to avoid duplication of data
 
 outputs:
   PATH_TO_ARTIFACTS:
@@ -68,6 +72,7 @@ runs:
         MAX_SECONDS_FOR_SETUP: ${{ inputs.MAX_SECONDS_FOR_SETUP }}
         SERVER_RELOAD_TIMEOUT_SECONDS: ${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}
         DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
+        ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO: ${{ inputs.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}
       shell: bash
       run: |
         log="💡 ALK0023 INFO: Set environment variables and create artifacts folder"
@@ -91,6 +96,7 @@ runs:
         echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DOCASSEMBLE_DEVELOPER_API_KEY" >> $GITHUB_ENV
         echo "ALKILN_VERSION=$ALKILN_VERSION" >> $GITHUB_ENV
         echo "MAX_SECONDS_FOR_SETUP=$MAX_SECONDS_FOR_SETUP" >> $GITHUB_ENV
+        echo "ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO=$ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO" >> $GITHUB_ENV
         echo "SERVER_RELOAD_TIMEOUT_SECONDS=$SERVER_RELOAD_TIMEOUT_SECONDS" >> $GITHUB_ENV
         echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
         # Hard-coded internal ALKiln vars
@@ -100,10 +106,10 @@ runs:
       run: |
         log="💡 ALK0024 INFO: Confirm environment variables"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        vars_log="\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"
+        vars_log='\nALKiln version is ${{ env.ALKILN_VERSION }}\nRepo is "${{ env.REPO_URL }}"\nBranch ref is "${{ env.BRANCH_PATH }}"\nCustom MAX_SECONDS_FOR_SETUP is "${{ env.MAX_SECONDS_FOR_SETUP }}"\nCustom SERVER_RELOAD_TIMEOUT_SECONDS is "${{ env.SERVER_RELOAD_TIMEOUT_SECONDS }}"\nCustom ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO is "${{ env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}"\n'
         echo -e "$vars_log" >> "${{ env.DEBUG_PATH }}" && echo -e "$vars_log"
 
-    # Install
+    # Install ALKiln during GitHub workflow
     - name: "💡 ALK0025 INFO: Set up node"
       uses: actions/setup-node@v4
       with:
@@ -115,8 +121,18 @@ runs:
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
         npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"
 
-    # Install on playground
+    # Files prep
+    - shell: bash
+      env:
+        ARTIFACT_FOLDER: ${{ env.ARTIFACT_FOLDER }}
+      run: |
+        log="💡 ALK0275 INFO: Prepare repository test files"
+        echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+        alkiln-artifacts --path="${{ env.ARTIFACT_FOLDER }}"
+        alkiln-validate
+        alkiln-generate
 
+    # Install package on playground
     # Don't rely on the environment's version of python
     - uses: actions/setup-python@v5
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
@@ -129,7 +145,7 @@ runs:
         log="💡 ALK0027 INFO: Create a Project and install the package from GitHub"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
         pip install "docassemblecli==$DOCASSEMBLECLI_VERSION"
-        alkiln-setup --path="${{ env.ARTIFACT_FOLDER }}"
+        alkiln-setup
     - name: "🤕 ALK0028 ERROR: Unable to create a Project"
       if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
       shell: bash
@@ -138,15 +154,15 @@ runs:
         long_log="\n\n―――\n🤕 ALK0028 ERROR: Unable to create a Project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
         echo -e "$long_log" >> "${{ env.DEBUG_PATH }}" && echo -e "$long_log"
 
-    # Server installations - find folders and save session vars
-    - name: "💡 ALK0029 INFO: Install the GitHub package onto the server"
+    # Server installation
+    - name: "💡 ALK0029 INFO: Try to install the GitHub package onto the GitHub sandbox server"
       if: ${{ inputs.INSTALL_METHOD == 'server' }}
       shell: bash
       run: |
         log="💡 ALK0029 INFO: Install the GitHub package onto the server"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        alkiln-server-install --path="${{ env.ARTIFACT_FOLDER }}"
-    - name: "🤕 ALK0030 ERROR: Unable to install the package"
+        alkiln-server-install
+    - name: "🤕 ALK0030 ERROR: Unable to install the package on the GitHub sandbox server"
       if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
       shell: bash
       run: |
@@ -162,7 +178,7 @@ runs:
       run: |
         log="💡 ALK0031 INFO: Run tests"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        alkiln-run "$ALKILN_TAG_EXPRESSION" --path="${{ env.ARTIFACT_FOLDER }}"
+        alkiln-run "$ALKILN_TAG_EXPRESSION"
     
     # on playground, delete project
     - name: "💡 ALK0032 INFO: Delete the Project from the Playground"
@@ -171,7 +187,7 @@ runs:
       run: |
         log="💡 ALK0032 INFO: Delete the Project from the Playground"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        alkiln-takedown --path="${{ env.ARTIFACT_FOLDER }}"
+        alkiln-takedown
     
     # Upload artifacts that subscribers can download on the Actions summary page
     - name: "💡 ALK0033 INFO: Upload artifacts folder"

package/action_for_github_server/action.yml

@@ -51,15 +51,19 @@ runs:
         run: |
           log="💡 ALK0018 INFO: Get path names with date and time"
           timestamp="$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)"
+          # Where to get the contents for the artifact
           debug_dir="/tmp"
-          debug_path="$debug_dir/alkiln_docker_logs-${timestamp}UTC.txt"
+          debug_logs_path="$debug_dir/alkiln_docker_logs-${timestamp}UTC.txt"
+          # Where to put the artifact
           artifact_folder="alkiln_github_server-${timestamp}UTC"
+          echo "debug_logs_path: $debug_logs_path"
+          echo "artifact_folder: $artifact_folder"
 
           mkdir -p "$debug_dir"
           mkdir -p "$artifact_folder"
-          echo -e "$log" >> "$debug_path"
+          echo -e "$log" >> "$debug_logs_path"
 
-          echo "DEBUG_PATH=$debug_path" >> $GITHUB_ENV
+          echo "DEBUG_LOGS_PATH=$debug_logs_path" >> $GITHUB_ENV
           echo "GITHUB_SERVER_ARTIFACT_NAME=$artifact_folder" >> $GITHUB_ENV
 
       - shell: bash
@@ -68,7 +72,7 @@ runs:
           DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
         run: |
           log="💡 ALK0001 INFO: Set environment variables"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
 
           echo "MAX_SECONDS_FOR_DOCKER=$MAX_SECONDS_FOR_DOCKER" >> $GITHUB_ENV
           echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
@@ -81,7 +85,7 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0002 INFO: Create GitHub step output variables"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
           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"
@@ -92,19 +96,19 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0003 INFO: Get config"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
 
           mkdir /tmp/config
           # Worth making this silent by defining a variable with > /dev/null...?
           if [ -n "$CONFIG" ]
           then
             log2="💡 ALK0004 INFO: The developer did provide a custom docassemble config file as an input into this action."
-            echo -e "\n$log2" >> "${{ env.DEBUG_PATH }}" echo "$log2"
+            echo -e "\n$log2" >> "${{ env.DEBUG_LOGS_PATH }}" echo "$log2"
             echo "$CONFIG" > /tmp/config/myconfig.yml
             echo "CONFIG_ARGS=--env DA_CONFIG=/tmp/config/myconfig.yml --volume /tmp/config:/tmp/config " >> $GITHUB_ENV
           else
             log3="💡 ALK0005 INFO: The developer did NOT provide a custom docassemble config file as an input into this action. Docassemble will use its default config."
-            echo -e "\n$log3" >> "${{ env.DEBUG_PATH }}" echo "$log3"
+            echo -e "\n$log3" >> "${{ env.DEBUG_LOGS_PATH }}" echo "$log3"
             echo "CONFIG_ARGS=" >> $GITHUB_ENV
           fi
 
@@ -120,13 +124,13 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0006 INFO: Determine docker logs visibility"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
             echo "OUTPUT_DOCKER=$SHOW_DOCKER_OUTPUT" >> $GITHUB_ENV
-            echo -e "\n$SHOW_DOCKER_OUTPUT" >> "${{ env.DEBUG_PATH }}"
+            echo -e "\n$SHOW_DOCKER_OUTPUT" >> "${{ env.DEBUG_LOGS_PATH }}"
           else
             echo "OUTPUT_DOCKER=false" >> $GITHUB_ENV
-            echo -e "\nfalse" >> "${{ env.DEBUG_PATH }}"
+            echo -e "\nfalse" >> "${{ env.DEBUG_LOGS_PATH }}"
           fi
 
       # Messages about output
@@ -136,14 +140,14 @@ runs:
         run: |
           # 💡 ALK0007 INFO: ALKiln will now hide docker output
           log="===\n💡 ALK0007 INFO: ALKiln will now hide docker output to avoid possibly showing details about your config. If you want to get output to see more of what is going on, use \"with:\" and set the input \"SHOW_DOCKER_OUTPUT\" to \"true\". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==="
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
       - name: "💡 ALK0008 INFO: ALKiln will show docker output"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
         shell: bash
         run: |
           # 💡 ALK0008 INFO: ALKiln will show docker output
           log="===\n💡 ALK0008 INFO: ALKiln will show docker output. ALKiln cannot control this output. If you want to prevent output, use \"with:\" and set the input \"SHOW_DOCKER_OUTPUT\" to \"false\". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==="
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
 
       # TODO: Reduce these to 1 block by putting ` > /dev/null 2>&1` into an env var
       # No docker output
@@ -154,7 +158,7 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0009 INFO: Download and start docker silently"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
           docker pull jhpyle/docassemble > /dev/null 2>&1
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
@@ -171,7 +175,7 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0010 INFO: Download and start docker"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
           docker pull jhpyle/docassemble
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
@@ -189,13 +193,13 @@ runs:
         run: |
           # 💡 ALK0011 INFO: The following messages are not docker output
           log="💡 ALK0011 INFO: The following messages are NOT docker output, just ALKiln waiting for the server to start"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
 
       - name: "💡 ALK0012 INFO: Waiting for server to start"
         shell: bash
         run: |
           log="💡 ALK0012 INFO: Waiting for server to start"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
 
           # Reset the SECONDS variable
           SECONDS=0
@@ -205,27 +209,27 @@ runs:
           response="start"
           while [[ $response != *"200"* ]]; do
             log2="💡 ALK0013 INFO: Time elapsed: $SECONDS seconds"
-            echo -e "\n$log2" >> "${{ env.DEBUG_PATH }}" && echo -e "$log2"
+            echo -e "\n$log2" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log2"
 
             # 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."
-              echo -e "\n$log3" >> "${{ env.DEBUG_PATH }}" && echo -e "$log3"
+              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"
-            echo -e "\n$log4" >> "${{ env.DEBUG_PATH }}" && echo -e "$log4"
+            echo -e "\n$log4" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log4"
 
             # Check if the string includes the desired text
             if [[ $response == *"200"* ]]; then
               log5="💡 ALK0016 SUCCESS: Success! The docker container is ready!"
-              echo -e "\n$log5" >> "${{ env.DEBUG_PATH }}" && echo -e "$log5"
+              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."
-              echo -e "\n$log6" >> "${{ env.DEBUG_PATH }}" && echo -e "$log6"
+              echo -e "\n$log6" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log6"
               sleep 30
             fi
 
@@ -260,23 +264,23 @@ runs:
         shell: bash
         run: |
           log="💡 ALK0019 INFO: Create docker artifact data"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-          echo "$(docker output docassemble_container)" >> "${{ env.DEBUG_PATH }}"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
+          echo "$(docker output docassemble_container)" >> "${{ env.DEBUG_LOGS_PATH }}"
       - name: "💡 ALK0020 INFO: Upload artifacts folder"
         if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
         uses: actions/upload-artifact@v4
         with:
           name: ${{ env.GITHUB_SERVER_ARTIFACT_NAME }}
-          path: ${{ env.DEBUG_PATH }}
+          path: ${{ env.DEBUG_LOGS_PATH }}
 
       - shell: bash
         if: ${{ success() }}
         run: |
           log="💡 ALK0021 SUCCESS: ALKiln created the docker container and started the server!"
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
 
       - shell: bash
         if: ${{ failure() }}
         run: |
           log="🤕 ALK0022 ERROR: Something went wrong. See above for more details."
-          echo -e "\n$log" >> "${{ env.DEBUG_PATH }}" && echo -e "$log"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"

package/docs/4_environments.md

@@ -223,7 +223,7 @@ This design is working within systems that limit how we can do what we need to d
 
 Alternative: Get rid of our support for some of these environments. The temporary GitHub docassemble server environment hasn't been used by a lot of authors. Other than that, the other environments have gotten a lot of use. Even though authors have not yet used the temporary GitHub environment much, they say they want that functionality. The trouble there seems to be complexity with initial set up.
 
-Alternative: Instead of dealing with separate runtimes, have one command and script that wraps all these currently separate processes in one runtime and handles which ones to trigger under what circumstances. If we included `./action_for_github/action.yml` in that command, we would prevent authors from customizing the temporary GitHub docassemble server. That would not be acceptable. To avoid closing off access to server customization, we can only partially integrate these different processes. Also, GitHub actions in general will still have to deal with some core business sometimes. For example, they have to create the artifacts folder name so they can use it later to upload the artifacts. This combined runtime also feels more coupled/entangled and therefore harder to maintain. The need for more command line arguments could make local development more complicated. It is still worth considering.
+Alternative: Instead of dealing with separate runtimes, have one command and script that wraps all these currently separate processes in one runtime and handles which ones to trigger under what circumstances. If we included `./action_for_github/action.yml` in that command, we would prevent authors from customizing the temporary GitHub docassemble server. That would not be acceptable. To avoid closing off access to server customization, we can only partially integrate these different processes. Also, GitHub actions in general will still sometimes have to deal with some core business. For example, they have to create the artifacts folder name so they can use it later to upload the artifacts. This combined runtime also feels more coupled/entangled and therefore harder to maintain. The need for more command line arguments could make local development more complicated. It is still worth considering.
 
 <!-- Discuss: How to articulate the entanglement with more specifics and examples. -->
 
@@ -234,7 +234,7 @@ Alternative script names: `install_package`, `save_server`, `delete_package`.
 _Security, privacy, observability, etc._
 
 - Some tests need to use sensitive information. For example, some tests need a logged-in user and thus ALKiln needs the login info for a user. Different environments store this information differently and there is documentation about how to use sensitive information securely and privately.
-- Core ALKiln code[^2] ends up needing to handle some of the complexity of the 4 environments. Example - the `Log` class `path` takes an optional initial argument to set the artifacts path at the beginning of that runtime process. Other parts of the process have to assume that this path already exists. We have tried to abstract environment complexity out to `run_cucumber.js`, the script that wraps the core code, but there is still logic that the core code handles.
+- Core ALKiln code[^2] ends up needing to handle some of the complexity of the 4 environments. Example - the `Log` class `path` takes an optional initial argument to set the artifacts path before the core code runs. The process in the core code (and elsewhere) have to assume that this path already exists and use config values. We have tried to abstract environment complexity out to `run_cucumber.js`, the script that wraps the core code, but there is still logic that the core code handles.
 
 ---
 

package/docs/artifacts_folder_name.md

@@ -21,115 +21,165 @@ Our 4 environments can be condensed into 3 environments for the purpose of manag
 - ALKilnInThePlayground
 - The command line for internal development
 
-The GitHub action creates an artifact folder name and sends it to various scripts that use an instance of the `Log` class to create the folder and save the name. In other environments, an instance of the `Log` class both creates the name, creates the folder, and saves the name. The instance of the `Log` saves the name in `runtime_config.json`. That instance of `Log` and other ALKiln code uses that name to create and store files in that artifacts folder.
+Every environment runs npm commands. Those commands are sometimes run separately and thus trigger separate processes. We must find a way to persist information, like the name of the artifacts folder, across these processes.
 
-The artifact folder name generation code is in 2 places - the GitHub action and ALKiln's core code[^1]. In future, we may reduce that to just one location - the core code.
+The GitHub action creates an artifact folder name and sends it to a script that use an instance of the `Log` class to create the folder and save the name. In other environments, an instance of the `Log` class is what creates the name.
 
-<!-- More complex description that I don't think we need now, but want to double check:
-The scripts that GitHub action uses need to store its output in the same artifacts folder. The GitHub action therefore builds the name of the artifact folder and passes that around to the different scripts. The scripts pass the folder name to the `Log` class every time, which saves the folder name in `runtime_config.json`. After that, the core code uses that `json` value to put other artifacts in the same folder. We also have folder-naming code in the core code which we use for other purposes. The GitHub action duplicates that folder-naming code, which is unfortunate.
+The instance of the `Log` saves the name in `runtime_config.json`. That instance of `Log` and other ALKiln code uses that name to create and store files in that artifacts folder.
 
-At the same time, tests that run in ALKilnInThePlayground don't have GitHub to manage the artifact folder name. It only uses the `run_cucumber` script, not any of the others...
+The artifact folder name generation code is in 2 places - the GitHub action and ALKiln's core code[^1]. In future, we may be able to reduce that to just one location - the core code.
 
-Adding to that confusion, when people (like internal ALKiln developers) run tests from their command line, they do use the `setup` script once at first, but then run test suites repeatedly...
+Below are more detailed descriptions of how each environment interacts with the folder name. Where the folder name is created, gets passed, gets saved, and gets used. These descriptions still gloss over many details.
 
-Neither of the last 2 can depend on the `runtime_config.json` folder name that `setup` creates. If they did, all their multiple test runs would save to that first folder. Since both those environments use `run_cucumber.js` alone repeatedly, and since we don't want to duplicate folder-naming behavior between even more scripts, we decided that those non-GitHub environments should be able to let `Log` create a folder name from scratch every time. The `Log` constructor has to be able to accept a `path` argument with a folder name and also to accept an undefined `path` argument.
--->
+The diagrams highlight `Log` to help visualize a common point in all the flows.
 
-A future goal is to remove the need to store the name in the runtime configuration file to reduce that complexity a bit. These flows are up for discussion.
 
-Below are more detailed descriptions of the different paths the folder name takes in the different environments. Where the folder name is created, gets passed, gets saved, and gets used. Note that there's a little glossing over the details. For example, everything saves to `runtime_config.json`, but only the core code[^1] ever uses the value there.
+### Shared behavior
+
+For each environment, the start and end of how they manage the artifacts folder name is different. In the middle, though - once the artifacts folder name is already stored in the `runtime_config` file - the flow is the same.
+
+Npm commands that come in the middle have this flow to save logs:
+
+```mermaid
+flowchart LR
+
+    environment --triggers--> commands["middle</br>commands"]
+    commands --trigger--> scripts["package</br>code"]
+    scripts --make--> log2["#96;Log#96;"]:::log
+    log2 --"gets name</br>from"--> runtime2["runtime config</br>file"]
+    log2 --"adds to"--> folder2[folder</br>& files]
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+The core code also needs to use the artifacts folder name in order to save both logs and other artifacts:
+
+```mermaid
+flowchart LR
+
+    core["core</br>code"] --"makes"--> log4["#96;Log#96;"]:::log
+    core --"adds to"--> folder3[folder</br>& files]
+    core --"gets name</br>from"--> runtime3["runtime config</br>file"]
+    log4 --"gets name</br>from"--> runtime3
+    log4 --"adds to"--> folder3
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+Those are the shared flows. Each environment, though, has its own way to store the name at the start and each environment has its own way to give the author the final artifacts.
 
-The diagrams highlight `Log` to help visualize a common point in all the flows.
 
 ### GitHub action
 
-1. GitHub action creates a new folder name, passes that name to `setup`, which passes that name to `Log`, which creates the artifacts folder and saves the name in `runtime_config.json`. The setup `Log` uses the name to store logs in the folder. The setup uses its `Log`.
-2. GitHub action uses the same folder name, passes that same name to `run_cucumber`, which passes that same name to `Log`. The `runtime_cucumber` process uses that `Log`. The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
-3. GitHub action creates the folder name, passes that same name to `takedown`, which passes that same name when instantiating its `Log`. The takedown `Log` uses the name to store logs in the folder.
+The GitHub action starts off with an empty `runtime_config` file. The action creates a new folder name and passes that name to the `artifacts` script, which passes that name to a `Log`. The `Log` creates the artifacts folder and saves the name in `runtime_config.json`.
 
 ```mermaid
-%% "pass name too" has 2 o's at the end because mermaid makes one of them disappear
+flowchart LR
+
+    action["GitHub action"] --creates--> name["artifacts</br>folder name"]
+    action --"passes</br>name "--> command["'artifacts'</br>command"]
+    command --"passes</br>name"--> artifacts["artifacts.js"]
+    artifacts --"passes</br>name"--> log1["#96;Log#96;"]:::log
+    log1 --"stores name in</br>& uses"--> runtime1["runtime config</br>file"]
+    log1 --"creates</br>with name"--> folder1["folder</br>& files"]
+    log1 --"adds to"--> folder1
 
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+Finally, the action uses the name in the action context to download the artifacts folder so the user can have access to it after the action is done.
+
+```mermaid
 flowchart LR
-    action[action part 1] --create/pass name too--> setup
-    setup["setup"] --pass name too--> log1["#96;Log#96;"]:::log
-    log1 --store name in/ignore--> runtime1["runtime config file"]
-    log1 --create with name--> folder1[folder]
-
-    action2[action part 2] --pass name too--> run["run"]
-    run --pass name too--> log2["#96;Log#96;"]:::log
-    log2 --store name in/ignore--> runtime2["runtime config file"]
-    log2 --use with name--> folder2[folder]
-    run --> core["core code"]
-    core --pass name too--> log3["#96;Log#96;"]:::log
-    core --use with name--> folder2
-    core --get name from--> runtime2
-    log3 --use with name--> folder2
-    log3 --store name in/ignore--> runtime2
-
-    action3[action part 3] --pass name too--> takedown["takedown"]
-    takedown --pass name too--> log4["#96;Log#96;"]:::log
-    log4 --store name in/ignore--> runtime3["runtime config file"]
-    log4 --create with name--> folder5[folder]
+
+    action["GitHub action"] --previously created--> name["artifacts folder name"]
+    action --uses name to get--> folder["folder & files"]
 
 classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
 ```
 
+
 ### ALKilnInThePlayground
 
-1. ALKilnInThePlayground triggers `run_cucumber` without a folder name which triggers `Log` without a folder name. `Log` creates a new folder name and saves it in `runtime_config.json`. It also creates the artifacts folder. The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
+_Note: This should be implemented by the time anyone actually reads this. Here's hoping._
+
+ALKilnInThePlayground starts off with an empty `runtime_config` file. ALKilnInThePlayground triggers the `artifacts` command, but without a folder name. The code still creates a `Log` (also without a folder name). The `Log` itself creates the name.
 
 ```mermaid
 flowchart LR
-    ALKilnInThePlayground --> run["run"]
-    run --> log2["#96;Log#96;"]:::log
-    log2 --store name in/ignore--> runtime2["runtime config file"]
-    log2 --create with name--> folder2[folder]
-    run --> core["core code"]
-    core --> log3["#96;Log#96;"]:::log
-    core --use with name--> folder2
-    core --get name from--> runtime2
-    log3 --use with name--> folder2
-    log3 --store name in/ignore--> runtime2
+
+    ALKilnInThePlayground --> command["'artifacts'</br>command"]
+    command --> artifacts["artifacts.js"]
+    artifacts --> log1["#96;Log#96;"]:::log
+    log1 --creates--> name["artifacts</br>folder name"]
+    log1 --stores name--> runtime1["runtime config file"]
+    log1 --"gets name</br>from"--> runtime1["runtime config</br>file"]
+    log1 --creates</br>with name--> folder1["folder</br>& files"]
 
 classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
 ```
 
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+Finally, ALKilnInThePlayground itself uses the runtime config file to get the name so it can give the artifacts to the user.
+
+```mermaid
+flowchart LR
+
+    ALKilnInThePlayground --"gets name from"--> runtime1["runtime config file"]
+    ALKilnInThePlayground --"uses name to get"--> folder["folder & files"]
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+
 ### Command line
 
-1. The developer uses the command line to trigger setup without a folder name which triggers `Log` without a folder name. `Log` creates a name and creates the artifacts folder, then stores files in that folder.
-2. The developer uses the command line to trigger `run_cucumber` without a folder name which triggers `Log` without a folder name. `Log` creates and saves a new folder name in `runtime_config.json`, and creates the artifacts folder.  The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
-3. The developer uses the command line to trigger `takedown` without a folder name which triggers `Log` without a folder name. `Log` creates a name and the artifacts folder, then stores files in that folder.
+The command line flow is similar to ALKilnInThePlayground, but has to deal with a pre-existing runtime config file[^2]. The command line flow overwrites the artifacts folder name on each run.
+
+An internal developer uses the command line to trigger the `artifacts` command, but without a folder name. The code still creates a `Log` (also without a folder name). The `Log` itself creates a name and overwrites the current name in the runtime config file.
 
 ```mermaid
 flowchart LR
-    cmd1[command line] --> setup
-    setup["setup"] --> log1["#96;Log#96;"]:::log
-    log1 --store name in/ignore--> runtime1["runtime config file"]
-    log1 --create with/use with name--> folder1[folder]
-
-    cmd2[command line] --> run["run"]
-    run --> log2["#96;Log#96;"]:::log
-    log2 --store name in/ignore--> runtime2["runtime config file"]
-    log2 --create with name--> folder2[folder]
-    run --> core["core code"]
-    core --> log3["#96;Log#96;"]:::log
-    core --use with name--> folder2
-    core --get name from--> runtime2
-    log3 --use with name--> folder2
-    log3 --store name in/ignore--> runtime2
-
-    cmd3[command line] --> takedown["takedown"]
-    takedown --> log4["#96;Log#96;"]:::log
-    log4 --store name in/ignore--> runtime3["runtime config file"]
-    log4 --create with name--> folder5[folder]
+
+    dev --> command["'artifacts'</br>command"]
+    command --> artifacts["artifacts.js"]
+    artifacts --> log1["#96;Log#96;"]:::log
+    log1 --creates--> name["artifacts</br>folder name"]
+    log1 --"overwrites</br>previous name"--> runtime1["runtime config file"]
+    log1 --"gets name</br>from"--> runtime1["runtime config</br>file"]
+    log1 --creates</br>with name--> folder1["folder</br>& files"]
 
 classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
 ```
 
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+ALKiln stores the artifacts folder in the root of the local repository folder. The developer has direct access to the file system and can see every new artifacts folder. In fact, they can also see any previous artifacts folders. We avoid adding those artifacts folders to the repo by including the folder name pattern in the `.gitignore` and `.npmignore` files.
+
+```mermaid
+flowchart LR
+
+    git --🙈--> folder["folders & files"]
+    dev --👁️--> folder
+    npm --🙉--> folder
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+
 ## Alternatives considered
 
-- One script for creating the artifacts folder name: Make a script that saves the folder name to the ALKiln `runtime_config.json`. Then all the other code, including instances of `Log`, would always use `runtime_config.json`. We would want `package.json` scripts for the command line environment that would include getting the name of the folder. That potentially complicates the code and process for internal development. We will see how our current design behaves first.
-- Use `Log`'s path name instead of the one in `runtime_config.json`. We thought we would want to save in previous artifacts folders, but it now seems potentially unnecessary. This seems the most viable option for the future, but it is unclear how we can integrate `Log` with all the other files. I wouldn't consider PDFs and screenshots to be logs.
+- Each originator (GitHub, ALKilnInThePlayground, the dev) could always create the name from the outside. This would duplicate work, but would give more fine-grained control.
+- Have `Log` make a different folder name each time and, at the very end, combine the contents of those folders into one folder. Hey, all ideas are welcome here.
+
+For name creation:
+
+- Avoid GitHub actions creating names. That is, create names only in `artifacts.js` and pass that out again. Needs research.
+
 
 [^1]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.
+
+[^2] Keeping the `runtime_config` file around helps greatly improves the local development experience. You can read more in the document that talks about the 4 environments ALKiln supports.