@suffolklitlab/alkiln 5.13.2 → 5.13.3-feat-random-2

package/action_for_github_server/action.yml

@@ -47,12 +47,33 @@ runs:
       # Place the root directory in this branch
       - uses: actions/checkout@v4
 
+      - shell: bash
+        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_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_logs_path"
+
+          echo "DEBUG_LOGS_PATH=$debug_logs_path" >> $GITHUB_ENV
+          echo "GITHUB_SERVER_ARTIFACT_NAME=$artifact_folder" >> $GITHUB_ENV
+
       - shell: bash
         env:
           MAX_SECONDS_FOR_DOCKER: ${{ inputs.MAX_SECONDS_FOR_DOCKER }}
           DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
         run: |
-          # 💡ALK0001 INFO: Set environment variables
+          log="💡 ALK0001 INFO: Set environment variables"
+          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
           echo "DA_ADMIN_API_KEY=abcd1234abcd1234abcd5678abdc5678" >> $GITHUB_ENV
@@ -63,7 +84,8 @@ runs:
         id: api_key_output_step
         shell: bash
         run: |
-          # 💡 ALK0002 INFO: Create GitHub step output variables
+          log="💡 ALK0002 INFO: Create GitHub step output variables"
+          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"
@@ -73,16 +95,20 @@ runs:
           CONFIG: ${{ inputs.CONFIG_CONTENTS }}
         shell: bash
         run: |
-          # 💡 ALK0003 INFO: Get config
+          log="💡 ALK0003 INFO: Get config"
+          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
-            echo "💡 ALK0004 INFO: The developer did provide a custom docassemble config file as an input into this action."
+            log2="💡 ALK0004 INFO: The developer did provide a custom docassemble config file as an input into this action."
+            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
-            echo "💡 ALK0005 INFO: The developer did NOT provide a custom docassemble config file as an input into this action. Docassemble will use its default config."
+            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_LOGS_PATH }}" echo "$log3"
             echo "CONFIG_ARGS=" >> $GITHUB_ENV
           fi
 
@@ -97,11 +123,14 @@ runs:
           SHOW_DOCKER_OUTPUT: ${{ inputs.SHOW_DOCKER_OUTPUT }}
         shell: bash
         run: |
-          # 💡 ALK0006 INFO: Determine docker logs visibility
+          log="💡 ALK0006 INFO: Determine docker logs visibility"
+          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_LOGS_PATH }}"
           else
             echo "OUTPUT_DOCKER=false" >> $GITHUB_ENV
+            echo -e "\nfalse" >> "${{ env.DEBUG_LOGS_PATH }}"
           fi
 
       # Messages about output
@@ -110,13 +139,15 @@ runs:
         shell: bash
         run: |
           # 💡 ALK0007 INFO: ALKiln will now hide docker output
-          echo -e '===\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==='
+          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_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
-          echo -e '===\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==='
+          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_LOGS_PATH }}" && echo -e "$log"
 
       # TODO: Reduce these to 1 block by putting ` > /dev/null 2>&1` into an env var
       # No docker output
@@ -126,7 +157,8 @@ runs:
           CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
         shell: bash
         run: |
-          # 💡 ALK0009 INFO: Download and start docker silently
+          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 run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
@@ -142,7 +174,8 @@ runs:
           CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
         shell: bash
         run: |
-          # 💡 ALK0010 INFO: Download and start docker
+          log="💡 ALK0010 INFO: Download and start docker"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
           docker pull jhpyle/docassemble
           docker run --name docassemble_container \
                      --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
@@ -159,12 +192,14 @@ runs:
         shell: bash
         run: |
           # 💡 ALK0011 INFO: The following messages are not docker output
-          echo "💡 ALK0011 INFO: The following messages are not docker output, just ALKiln waiting for the server to start"
+          log="💡 ALK0011 INFO: The following messages are NOT docker output, just ALKiln waiting for the server to start"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
 
       - name: "💡 ALK0012 INFO: Waiting for server to start"
         shell: bash
         run: |
-          # 💡 ALK0012 INFO: Waiting for server to start
+          log="💡 ALK0012 INFO: Waiting for server to start"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}"
 
           # Reset the SECONDS variable
           SECONDS=0
@@ -173,23 +208,28 @@ runs:
 
           response="start"
           while [[ $response != *"200"* ]]; do
-            echo "💡 ALK0013 INFO: Time elapsed: $SECONDS seconds"
+            log2="💡 ALK0013 INFO: Time elapsed: $SECONDS seconds"
+            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
-              echo "🤕 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 timem 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)
-            echo "💡 ALK0015 INFO: Response is $response"
+            log4="💡 ALK0015 INFO: Response is $response"
+            echo -e "\n$log4" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log4"
 
             # Check if the string includes the desired text
             if [[ $response == *"200"* ]]; then
-              echo "🌈 ALK0016 SUCCESS: Success! The docker container is ready!"
+              log5="💡 ALK0016 SUCCESS: Success! The docker container is ready!"
+              echo -e "\n$log5" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log5"
             else
-              echo "💡 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. Will check again in 30 seconds."
+              echo -e "\n$log6" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log6"
               sleep 30
             fi
 
@@ -219,32 +259,28 @@ runs:
 
       # Upload artifacts that devs can download on the Actions summary page
       # Only if the developer wants to get that info, though
-      - name: "💡 ALK0018 INFO: Get path names with date and time"
-        if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
-        shell: bash
-        run: |
-          # 💡 ALK0018 INFO: Get path names with date and time
-          echo "GITHUB_SERVER_LOG_FILE_NAME=/tmp/alkiln_docker_logs-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC.txt" >> $GITHUB_ENV
-          echo "GITHUB_SERVER_ARTIFACT_NAME=alkiln_github_server-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
       - name: "💡 ALK0019 INFO: Create docker artifact data"
         if: ${{ always() && env.OUTPUT_DOCKER == 'true' }}
         shell: bash
         run: |
-          # 💡 ALK0019 INFO: Create docker artifact data
-          echo "$(docker output docassemble_container)" > "${{ env.GITHUB_SERVER_LOG_FILE_NAME }}"
+          log="💡 ALK0019 INFO: Create docker artifact data"
+          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.GITHUB_SERVER_LOG_FILE_NAME }}
+          path: ${{ env.DEBUG_LOGS_PATH }}
 
       - shell: bash
         if: ${{ success() }}
         run: |
-          echo "🌈 ALK0021 SUCCESS: ALKiln created the docker container and started the server!"
+          log="💡 ALK0021 SUCCESS: ALKiln created the docker container and started the server!"
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"
 
       - shell: bash
         if: ${{ failure() }}
         run: |
-          echo "🤕 ALK0022 ERROR: Something went wrong. See above for more details."
+          log="🤕 ALK0022 ERROR: Something went wrong. See above for more details."
+          echo -e "\n$log" >> "${{ env.DEBUG_LOGS_PATH }}" && echo -e "$log"

package/docs/4_environments.md

@@ -0,0 +1,243 @@
+# Designing for the complexity of the 4 environments in which ALKiln can run
+
+## Context and scope
+
+Authors have different testing needs. For example, sometimes authors need to run individual tests more quickly as they are developing code and sometimes authors need to run a whole test suite on a weekly schedule to make sure their online forms keep working over time. To run individual tests more quickly, an author can run the tests directly on their development server. To run scheduled tests, an author can run tests on GitHub. Those are very different environments.
+
+Internal ALKiln developers need to run tests in more environments as well.
+
+To help with all these, ALKiln can work in 4 different environments. We have to design ALKiln's architecture with that in mind.
+
+## Goals
+
+- Help authors to test in the environments that best help them develop.
+- Help internal ALKiln developers develop the framework comfortably enough.
+- Keep openings where authors can interact directly with the systems we're using so they can customize behavior that we can't account for.
+
+## Non/anti-goals
+
+- Be an intermediary between the author and all the possible customization they need for their tests.
+
+## The actual design
+
+This design involves:
+
+- The 4 environments, the ALKiln flow for each, and the advantages each environment has.
+- The 4 separate command line commands.
+- Passing information between different runtime processes.
+- The 2 composite action scripts.
+
+<!-- Maybe the flows below should each be shown in the relevant individual sections for each environment. -->
+
+The flow for each environment is different.
+
+The temporary GitHub docasseble server action:
+
+1. Author workflow file > `./action_for_github/action.yml` > author workflow file > `./action.yml` > `alkiln-server-install` > `alkiln-run` > author workflow file
+
+<!-- Not sure how to represent this relationship. Trying to show what processes have access to what parts of the process. I'm not sure showing how `./action.yml` threads in and out is actually useful. I'm trying to show that the author's workflow has access in between `./action_for_github/action.yml` and `./action.yml` where they can do things so when someone reads about it later, they can understand.
+
+Author workflow
+  `./action_for_github/action.yml`
+Author workflow
+  `./action.yml`
+    `alkiln-server-install`
+  `./action.yml`
+    `alkiln-run`
+  `./action.yml`
+Author workflow
+
+Author workflow
+  `./action_for_github/action.yml`
+Author workflow
+  `./action.yml`
+    `alkiln-server-install`
+    `alkiln-run`
+Author workflow
+-->
+
+A GitHub action that installs tests in an author's account on their own docasseble server:
+
+1. Author workflow file > `./action.yml` > `alkiln-setup` > `alkiln-run` > `alkiln-takedown` > author workflow file
+
+<!-- Not sure how to represent this relationship
+Author workflow
+  `./action.yml`
+    `alkiln-setup`
+    `alkiln-run`
+    `alkiln-takedown`
+Author workflow
+-->
+
+ALKilnInThePlayground:
+
+1. `alkiln-run`
+
+A local developer might customize these steps in various ways in their console. If they are using the default workflow, this is what it looks like functionally when they develop a feature:
+
+1. Command line > `alkiln-setup` once
+2. Command line > `alkiln-run` many times
+3. Command line > `alkiln-takedown` once
+
+### 4 environments we need to account for
+
+#### 2 GitHub options
+
+Authors or admins use GitHub workflows to run our GitHub composite actions if they:
+
+- Want to run tests every time an author commits code.
+- Want to run tests based on other triggers, like a schedule or manually triggering the workflow.
+- They want to require that all tests pass before they merge a branch.
+- Use other CI pipelines.
+
+**Run on a temporary GitHub server**
+
+1. Author: commits code to GitHub.
+2. ALKiln: Creates a docassemble server, installs the docassemble package globally on the server, run the test suite once, and destroys the server.
+
+Authors use this if they:
+
+- Want less flake.
+- Want to test with latest version of da.
+- Don't mind extra setup time each test suite takes.
+- Know how to use bash to work with a Docker container (if needed).
+
+**Run from GitHub, but on their own server**
+
+1. Author: commits code to GitHub.
+2. ALKiln: Installs the docassemble package in the author's account on their own docassemble server, runs the test suite once, and deletes the docassemble package.
+
+Authors use this if they:
+
+- Want to Use data from SS3 and other remote databases.
+- Want to test with their own version of docassemble.
+- Don't want to have to be so careful with all their dependencies (like having to put all dependencies on pypi) because they have installed them on their server themselves.
+
+#### Running directly on docassemble server
+
+A docassemble server doesn't just serve forms to end users. It also lets authors develop the code of their forms[^1]. That is why it is useful to install and use ALKiln on an author's docassemble server. They do this by using the AlKilnInThePlayground package.
+
+An author installs AlKilnInThePlayground package on their server. They run the online form that package has. That lets them install ALKiln on their server. The package can tell who the user is and offers the user a choice of which of their Playground development Projects to test, and they run the tests right their on their server.
+
+1. Author: Installs the package they want to test into their account on the docassemble 1. server, edits their package, triggers the test run.
+2. ALKiln: Runs tests.
+3. Author: Edits, tests, and repeats. Finally, the author deletes the package in their account on the docassemble server.
+
+Authors use this if they:
+
+- Want to run tests faster than the GitHub test flow allows (a faster iteration cycle).
+- Want to avoid server reloads (in the case of a package with python modules).
+- Feel uncomfortable with failures on GitHub - they can get tests passing before pushing to GitHub.
+- Have the right version of nodejs on their docassemble server, which is based on what Docker image they have installed.
+
+#### Command line
+
+<!-- Do we mention that internal devs don't always use the bins? They use the package.json scripts? Seems like an unnecessary complication. -->
+
+1. Internal developer with ALKiln's help or with their own command line arguments: Installs the package on a specified docassemble server (local or remote).
+2. Internal developer with ALKiln's help: runs the tests as many times as they need while they develop the framework code.
+3. Internal developer with ALKiln's help or with their own command line arguments: deletes the package from the docassemble server.
+
+Internal developers do this if they:
+
+- Have to edit ALKiln's own code.
+- Want to run tests faster than the GitHub test flow allows (a faster iteration cycle).
+- Want to run tests on a local server.
+- See ALKiln's behavior live and with more detail.
+
+### 4 node command line commands
+
+`package.json` has 4 command-line commands. They are broken up by the different needs of the 4 different environments - installing packages on a server, saving temporary server information, running the core framework code[^2], deleting packages on a server. As this document describes. Some environments need only one of the commands.
+
+Read the API section for more details.
+
+Looking only at the command line commands does miss a crucial 1st part of the temporary GitHub docassemble server workflow - creating the docassemble server. That is done completely through `./action_for_github/action.yml`. See the section on GitHub composite actions for details.
+
+### Passing information between different processes.
+
+ALKiln needs to pass information between its different processes to do things like go to the right interview urls and store artifacts (like reports, debug logs, and screenshots) in the right folder.
+
+**`runtime_config.json`**
+
+Since different runtime processes can't pass information between them any other way, we create and modify `runtime_config.json` as each process runs to store information that other processes need. Different environments need to save different information or to save information differently.
+
+For example, `alkiln-setup` needs to create a Project on an author's Playground[^1] to store the code of the online forms and show the forms online. Later, `alkiln-run` needs to know how to find the URL for that specific Project on the server so it can interact with the forms.
+
+The name of the artifacts folder is an example of using `runtime_config.json` and how the complexity of these 4 environments invades ALKiln's core code. See the doc about the artifacts folder name.
+
+<!-- Do we need to list the specific possible values here? These aren't recorded anywhere else, so it's worth considering, but it doesn't feel like the right place. This is incomplete. Holding off until we decide where it goes.
+Everything uses these:
+
+- `artifacts_path`
+
+Temp GitHub docassemble server install uses these:
+
+`da_install_method` - `server` or `playground`
+`da_repo_folder_name` - For example, EvictionDefense in the docassemble-EvictionDefense repo. (see session_vars.js)
+
+Installation in an author's account on their own docassemble server and command line uses these:
+
+Does ALKilnInThePlayground also use the below?
+
+- `da_project_name` - The name of the docassemble project. Helps get the url of the interview. In local internal development, this lets developers keep using the same Project over and over so they don't need to make a new Project, and upload the package code, every time they run a test.
+-->
+
+**Env vars**
+
+ALKiln and test authors use environment variables to pass information to different processes. GitHub workflows and actions store them in their `.yml` files. ALKilnInThePlayground uses the server's configuration file. Local developers use their `.env` file. This is also the way authors and internal developers pass sensitive information to ALKiln. On GitHub, authors store sensitive information in GitHub secrets and then use them as environment variables.
+
+### 2 GitHub composite actions
+
+Authors use our GitHub composite actions in their GitHub workflow files.
+
+- `./action_for_github/action.yml` - Creates the temporary GitHub docassemble server. This action is a crucial part of the flow for temporary GitHub docassemble servers. The fact that it is a separate action gives authors the information and environment they need to change and customize the temporary server themselves in more ways than we can account for. For example, authors might need to make user accounts so they can test what a logged-in user sees. Right now, it cannot help them access remote databases like S3.
+- `./action.yml` - Installs packages on servers in the ways we've described, runs the tests, deletes packages on servers, and gives authors information from the test run, like reports and screenshots.
+
+The rest of the details and API are in the files themselves and in the author-facing documentation about GitHub workflow files at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#workflows.
+
+## APIs
+
+### Command-line API
+
+ALKiln's `package.json` offers 4 command-line commands:
+
+1. `alkiln-server-install` - Stores `runtime_config.json` variables of a temporary GitHub docassemble server for the core framework code[^2].
+2. `alkiln-setup` - Installs the docassemble package on the author's account and stores `runtime_config.json` variables for core framework code.
+3. `alkiln-run` - Wraps and then runs the framework's core code to run the tests.
+4. `alkiln-takedown` - Deletes the package there.
+
+### GitHub composite actions API
+
+The general description of the composite actions is in the composite action section. The details of composite action API is in the author-facing documentation about GitHub workflow files at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#workflows.
+
+## Degree of constraint
+
+This design is working within systems that limit how we can do what we need to do.
+
+- GitHub's action and workflow API and environment. For example, interacting with the temporary GitHub docassemble server vs. interacting with an author's server. Also, the ways in which we need to store and use environment variables.
+- docassemble's API and environment. It wasn't designed to be automated and used this way. For example, it stores package files very differently than the way GitHub arranges them and very differently depending on where we install the package, it has different memory constraints for installing the packages globally vs. in an individual developer's account, etc.
+- cucumberjs's inability to pass non-primitives to core framework code[^2].
+- 3rd party database storage systems, like S3, are hard to integrate into GitHub temporary server tests. We have excluded this feature at the moment. Authors would need to write their own workflow or composite action to access remote databases.
+
+## Alternatives considered
+
+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.
+
+<!-- Discuss: How to articulate the entanglement with more specifics and examples. -->
+
+Alternative script names: `install_package`, `save_server`, `delete_package`.
+
+## Cross-cutting concerns
+
+_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.
+
+---
+
+[^1]: A docassemble server can have multiple purposes. One is to contain the packages for online forms which end users then use. Those packages are stored in a special place on the server and admins configure the server to give end users a list of those forms. Another purpose of the docassemble server is to be a development environment in which to create the forms. An author/developer of the forms has a developer account on the server. That account can store multiple packages and versions of packages. It also has an IDE that authors can use to work on those packages. They can push those files to GitHub from that IDE. They can also pull those packages from GitHub using that IDE.
+
+[^2]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.

package/docs/artifacts_folder_name.md

@@ -0,0 +1,135 @@
+# Creating and using the name of the artifacts folder
+
+## Context and scope
+
+The artifacts folder is where an author can see the results of their tests, like the reports, screenshots, and downloaded documents.
+
+The name of this folder has a specific format to make it as short as possible while it still stays recognizable to users and that it is unique. To help keep it unique it includes a timestamp. (The human readable date/time is not as precise and also longer than the timestamp).
+
+Because of the 4 environments ALKiln can run in (see the docs about the 4 environments), we have different ways to make sure we use one unique artifacts folder name for each test run.
+
+## Goals
+
+- Minimize code duplication
+- In each of the 4 ALKiln environments, be able to track one unique folder name for each test suite run
+
+## The actual design
+
+Our 4 environments can be condensed into 3 environments for the purpose of managing the artifacts folder name:
+
+- GitHub action (`./action.yml`)
+- 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.
+
+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.
+
+<!-- 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.
+
+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...
+
+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...
+
+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.
+-->
+
+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.
+
+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.
+
+```mermaid
+%% "pass name too" has 2 o's at the end because mermaid makes one of them disappear
+
+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]
+
+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.
+
+```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
+
+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.
+
+```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]
+
+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.
+
+[^1]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.