@suffolklitlab/alkiln 5.13.0 → 5.13.1

package/.env.example

@@ -0,0 +1,29 @@
+# Setup
+DOCASSEMBLE_DEVELOPER_API_KEY=<ask @niharikasingh>
+SERVER_URL=https://apps-dev.suffolklitlab.org
+REPO_URL=https://github.com/SuffolkLITLab/alkiln
+SERVER_RELOAD_TIMEOUT_SECONDS=
+MAX_SECONDS_FOR_SETUP=
+
+# Set DEBUG to 1 to run in non-headless mode and see the test run live
+DEBUG=
+# If you edit interview files (.yml files), you should push to a new
+# branch and update BRANCH_PATH to that branch name
+
+# Custom variables for our tests
+
+BRANCH_PATH=v5
+USER1_EMAIL=<ask @niharikasingh>
+USER1_PASSWORD=<ask @niharikasingh>
+NORMAL_USER_EMAIL=<tbd>
+NORMAL_USER_PASSWORD=<tbd>
+NORMAL_USER_API_KEY=<tbd>
+WRONG_EMAIL=wrong_email@example.com
+WRONG_PASSWORD=wrong_password
+INVALID_API_KEY=invalidAPIkey
+SECRET_VAR1=secret-var1-value
+SECRET_VAR2=secret-var2-value
+SECRET_FOR_MISSING_FIELD=secret for missing field
+SECRET_INVALID_THERE_IS_ANOTHER=invalid value for there_is_another
+EMPTY_STRING=
+_ORIGIN=local

package/.github/workflows/github_server.yml

@@ -50,8 +50,10 @@ jobs:
       SECRET_FOR_MISSING_FIELD: secret for missing field
       INVALID_API_KEY: invalidAPIkey
       EMPTY_STRING: ""
-      USER_NO_PERMISSIONS_EMAIL: alkiln@example.com
-      USER_NO_PERMISSIONS_PASSWORD: User123^
+      NORMAL_USER_EMAIL: alkiln@example.com
+      NORMAL_USER_PASSWORD: User123^
+      WRONG_EMAIL=wrong_email@example.com
+      WRONG_PASSWORD=wrong_password
       
     steps:
       # Place the root directory in this branch to access
@@ -91,8 +93,8 @@ jobs:
             -H 'Content-Type: application/json' \
             -d '{
               "key": "${{ env.KEY }}",
-              "username": "${{ env.USER_NO_PERMISSIONS_EMAIL }}",
-              "password": "${{ env.USER_NO_PERMISSIONS_PASSWORD }}"
+              "username": "${{ env.NORMAL_USER_EMAIL }}",
+              "password": "${{ env.NORMAL_USER_PASSWORD }}"
             }')
           echo "User data:"
           echo "$user_data"
@@ -113,7 +115,7 @@ jobs:
           unquoted="${no_end_quote#\"}"
           echo "unquoted: $unquoted"
 
-          echo "USER_NO_PERMISSIONS_API_KEY=$unquoted" >> "$GITHUB_ENV"
+          echo "NORMAL_USER_API_KEY=$unquoted" >> "$GITHUB_ENV"
 
       #### Developer note: You can probably leave this out
       ## Optional debugging to explore things like docker issues

package/.github/workflows/playground.yml

@@ -43,10 +43,12 @@ jobs:
       PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
       USER1_EMAIL: ${{ secrets.USER1_EMAIL }}
       USER1_PASSWORD: ${{ secrets.USER1_PASSWORD }}
-      USER_NO_PERMISSIONS_EMAIL: ${{ secrets.USER_NO_PERMISSIONS_EMAIL }}
-      USER_NO_PERMISSIONS_PASSWORD: ${{ secrets.USER_NO_PERMISSIONS_PASSWORD }}
-      USER_NO_PERMISSIONS_API_KEY: ${{ secrets.USER_NO_PERMISSIONS_API_KEY }}
+      NORMAL_USER_EMAIL: ${{ secrets.USER_NO_PERMISSIONS_EMAIL }}
+      NORMAL_USER_PASSWORD: ${{ secrets.USER_NO_PERMISSIONS_PASSWORD }}
+      NORMAL_USER_API_KEY: ${{ secrets.USER_NO_PERMISSIONS_API_KEY }}
       INVALID_API_KEY: invalidAPIkey
+      WRONG_EMAIL=wrong_email@example.com
+      WRONG_PASSWORD=wrong_password
       EMPTY_STRING: ""
       SECRET_VAR1: secret-var1-value
       SECRET_VAR2: secret-var2-value

package/CHANGELOG.md

@@ -43,11 +43,30 @@ Format:
 - 
 -->
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Changed
+
+- Moves "expected" status error to only be visible to internal test errors. Closes [#933](https://github.com/SuffolkLITLab/ALKiln/issues/933).
+
+### Fixed
+
+- Detects failed sign in. Closes [#918](https://github.com/SuffolkLITLab/ALKiln/issues/918).
+- Updates pdfjs-dist for node v20 and v22. See [#952](https://github.com/SuffolkLITLab/ALKiln/issues/952).
+
+### Internal
+
+- Improved checks of log codes - more robust and flexible. See [#920](https://github.com/SuffolkLITLab/ALKiln/issues/920).
+- Returns report text from `.addToReport()` so it can be used again for error messages.
+- Update puppeteer to v22.15.0. Closes [#930](https://github.com/SuffolkLITLab/ALKiln/issues/930).
+- Update npm vulnerabilities except pdfjs-dist. See docs/decisions/pdfjs_version_2024_08_08.md.
+- Adds decision docs
+- Updated CONTRIBUTING.md
+- Added example.env, closes [#374](https://github.com/SuffolkLITLab/ALKiln/issues/374)
 
 ## [5.13.0] - 2024-07-11
 
-## Added
+### Added
 
 - Authors can now make sure that ALKiln deletes the interviews it creates for an ALKiln testing account. They can add a new (optional) value, an API key, to [the "sign in" Step](https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#sign-in) and use the ["start interview" Step](https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#start-interview) to go to the interview. The API key must belong to the user who signs in. Example: `Given I sign in with the email "<username env var>", the password "<password env var>", and the API key "<user API key>`. Admins can create an API key for a regular user with https://docassemble.org/docs/api.html#api_user_user_id_api_post. We will add this to the documentation for the "sign in" Step.
 

package/CONTRIBUTING.md

@@ -33,90 +33,83 @@ Before making a pull request
 1. Wait for the GitHub tests to pass. You may have to re-run failing tests—server restarts or race conditions may interfere with them. We have reduced them greatly, but some are impossible to avoid.
 1. Make your pull request. Work in progress pull requests are great too. A pull request must be reviewed before it can be merged.
 
-## .env
+## Running internal tests
+
+### Setup and takedown
 
-You need to make your own `.env` file. It contains sensitive variables, like passwords. We use them for our internal tests. The file should look something like the below:
+Only run this the first time you run our internal tests. That will install the code that you will test onto the docassemble server:
 
 ```bash
-# For everyone
-
-DOCASSEMBLE_DEVELOPER_API_KEY=<ask @niharikasingh>
-SERVER_URL=https://apps-dev.suffolklitlab.org
-REPO_URL=https://github.com/SuffolkLITLab/alkiln
-SERVER_RELOAD_TIMEOUT_SECONDS=
-MAX_SECONDS_FOR_SETUP=
-
-# For internal tests
-
-# Set DEBUG to 1 to run in non-headless mode and see the test run live
-DEBUG=
-# If you edit interview files (.yml files), you should push to a new 
-# branch and update BRANCH_PATH to that branch name
-BRANCH_PATH=v4
-USER1_EMAIL=<ask @niharikasingh>
-USER1_PASSWORD=<ask @niharikasingh>
-SECRET_VAR1=secret-var1-value
-SECRET_VAR2=secret-var2-value
-SECRET_FOR_MISSING_FIELD=secret for missing field
-SECRET_INVALID_THERE_IS_ANOTHER=invalid value for there_is_another
+npm run setup
 ```
 
-## Running internal tests
+If you run `takedown`, you will then have to run `setup` again:
 
-Only run this the first time you run tests in this repository to make the code available to test on the docassemble server:
+```bash
+npm run takedown
+```
+
+Use the syntax below to trigger all tests that should be passing[^1] (`pass` and unit tests):
 
 ```bash
-npm run setup
+npm run test
 ```
 
-If you run `takedown`, you will then have to run `setup` again.
+Run only cucumber tests that should pass:
 
-Use the syntax below to trigger all tests (cucumber and unit tests):
+```bash
+npm run pass
+```
+
+Run deliberately failing cucumber tests:
 
 ```bash
-npm run test
+npm run fail
 ```
 
-Run only cucumber tests:
+Run all cucumber tests, even those that are incorrectly failing:
 
 ```bash
 npm run cucumber
+```
+
+Run tests with specific cucumber tags or tag expressions:
 
-# To test Features or Scenarios specific tags:
-npm run cucumber -- "--tags" "@tagname"
+```bash
+npm run cucumber @tagname
 ```
 
-To run the unit tests in isolation:
+Run only unit tests:
 
 ```bash
 npm run unit
 ```
 
-If you or someone else changes the interview code in `./docassemble`, you have to clean up the old data on the server before running `setup` again:
+If you or someone else changes the interview code in `./docassemble/ALKilnTests/data/questions/*.yml`, you have to clean up the old code on the server before running `setup` again:
 
 ```bash
 npm run takedown
 ```
 
-## How the tests run
+## Updating dependencies
+
+To add or update a dependency, edit `package.json` with an exact version. That means avoid notations like `^`, `~`, and `x`. Then run `npm install` and `npm shrinkwrap` to update `npm-shrinkwrap.json`.
+
+## How one type of GitHub setup runs tests
 
-Our tests require the user/developer to have a docassemble server on which they host these interviews (online forms) and at least one developer account. With our help, our users set up the tests to run when they commit new code or to run manually. When GitHub runs the tests, it does the following:
+Our tests require the user/interview author/developer to have a docassemble server on which they host these interviews (online forms) and at least one developer account. With our help, our users set up the tests to run when they commit new code to GitHub. When these GitHub tests run, ALKiln does the following:
 
-1. Sets up on the docassemble server. In a given developer account:
-   1. Creates a new interview for this particular branch of the repository.
-   1. Pulls in the code from that branch into the docassemble server.
+1. Sets up on the docassemble server.
+   1. In a given docassemble developer account's Playground it creates a new Project.
+   1. Pulls in the code from the given branch into the new Project.
 1. Runs the tests
-   1. Pretends to be an anonymous account that comes to the form and inputs answers.
-   1. Writes up reports and possibly takes screenshots to show to the developer.
-1. Cleans up by deleting the interview it created
+   1. Pretends to be an anonymous or signed-in account that comes to the form and inputs answers.
+   1. Writes up reports and creates other artifacts to show to the developer.
+1. Cleans up by deleting the Project it created.
 
 When the developer commits code to GitHub, their account triggers our code, passing along variables that our code needs, like their GitHub secret of the API key for their docassemble server developer account.
 
-## Updating dependencies
-
-Sometimes you will have to add dependencies to ALKiln. You can do so by adding the dependency in the `package.json` "dependencies" section, specifying an exact version. Then, run `npm install` to update `npm-shrinkwrap.json` to have the new dependency.
-
-If you have to update an existing dependency, you can change the version in `package.json`, and run `npm install` to update `npm-shrankwrap.json`.
+There are [other kinds of test you can read more about in the user documentation](https://assemblyline.suffolklitlab.org/docs/alkiln/setup). The differences can be subtle and hard to explain, but they each have their pros and cons.
 
 ## Very general architecture of files and folders
 
@@ -124,24 +117,7 @@ An honest look at our current project architecture—some of our files and folde
 
 ### Logic architecture
 
-ALKiln uses [cucumber](https://cucumber.io/docs/installation/javascript/)[^1] with [Gherkin](https://cucumber.io/docs/gherkin/reference/) syntax, [puppeteer](https://pptr.dev/), and [chai](https://www.chaijs.com/).
-
-#### .feature files
-
-The `.feature` files are written in Gherkin, a syntax cucumber uses. The "code" in there relies on the functions set up in `./lib/steps.js`.
-
-```js
-// The test_something.feature file step
-Then I sign
-
-// relies on the code in steps.js
-Then('I sign', { timeout: -1 }, async () => {
-  return wrapPromiseWithTimeout(
-    scope.steps.sign( scope ),
-    scope.timeout
-  );
-});
-```
+ALKiln uses [cucumber](https://cucumber.io/docs/installation/javascript/)[^2] with [Gherkin](https://cucumber.io/docs/gherkin/reference/) syntax, [puppeteer](https://pptr.dev/), and [chai](https://www.chaijs.com/).
 
 #### steps.js
 
@@ -170,42 +146,81 @@ The file handles things like:
 * Checking for server restarts
 * Generating test report content
 
-### Logging
+#### Setup and takedown logic
 
-`./lib/utils/log.js` takes care of logging information of various kinds (normal, debug, error) to the command line in ways we hope are useful. We should probably find a logging library instead, but this is what we have for now. An important feature is that it ensures the messages clearly belong to ALKiln and not to some other process.
+All of the setup and takedown logic is in the `./lib/docassemble` directory. It is named after the docassemble API code that is in there. Setup and takedown interact very closely with docassemble and the docassemble server API.
 
-### session_vars.js
+### .env
 
-The `./lib/utils/session_var.js` file keeps track of what you might otherwise think of as environment variables. We like to think of them as constants, but some of them do need to go through functions, so for consistency we get them all through functions. Also because it was easier to test them when they are functions.
+You need to copy [our `.env.example` file](https://github.com/SuffolkLITLab/ALKiln/blob/HEAD/.env.example). It has sensitive variables, like passwords. It also has custom values our tests need. Contact us to get involved with the project and get the sensitive information. We need to use environment variables in the same way our users do when they run their workflow files in their GitHub action. At the moment, it is the only way to pass values into ALKiln from a GitHub action.
 
-### Setup and takedown logic
+### GitHub composite actions
 
-All of the setup and takedown logic is in the `./lib/docassemble` directory. It is named after the docassemble API code that is in there. Also, setup and takedown interact very closely with docassemble and the docassemble server.
+Our `./action.yml` and `action_for_github_server/action.yml` are [composite actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action). The GitHub workflow files are there to trigger the code in these files. These composite actions install npm, install ALKiln. They execute the scripts in our `package.json` to set up the tests, run them, save the output of the tests - artifacts reports, errors, screenshots, etc. - clean up the tests, and output the reports back to the author's workflow files.
 
-Other files also use the docassemble API functions, so this folder is in a bit of a messy position.
+### Internal tests
 
-### Bash commands
+We have our own docassemble package inside our repo `./docassemble` folder to test our own code with its own interview files and `.feature` test files.
 
-When you `npm run` the scripts in our `./package.json` you can setup, run, or takedown tests. We are working on converting this to a command line tool to avoid some complexity in GitHub actions, increase security, and align more with what this framework has grown into. (TODO: Define this better)
+There are other files the docassemble package needs, like `./setup.py`, so if you see them around, don't worry about them.
 
-### GitHub composite action
+If you want to run the tests, you can go to the [instructions for running tests section](#running-internal-tests) in this README.
 
-Our `./action.yml` is a [composite action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action). The users/developers let it do most of the work for them. It installs npm, installs our repo, then uses our repo to set up the tests, run the tests, generate and save reports, errors, and screenshots, and clean up the tests.
+#### .feature and .yml files
 
-### Internal tests
+The `.feature` are in `./docassemble/ALKilnTests/data/sources/*.feature`. They're written in Gherkin, a syntax cucumber uses. The "code" in there relies on the functions set up in `./lib/steps.js`. For example:
 
-We have our own docassemble package in our repo to test our own end-to-end tests. Most of what the package needs is in `./docassemble`. That docassemble package is what the test setup pulls into the docassemble server. Our internal end-to-end cucumber tests are `.feature` files that are stored in `./docassemble/ALKilnTests/data/sources`. The interview (online form) `.yml` files that those `.feature` files use are also deep in the `./docassemble` package. You probably won't be touching the interview files. If you get curious, feel free to ask us.
+```js
+// The test_something.feature file Step
+Then I sign
 
-There are other files the docassemble package needs, like `./setup.py`, so if you see them around, don't worry about them.
+// relies on the code in steps.js
+Then('I sign', { timeout: -1 }, async () => {
+  return wrapPromiseWithTimeout(
+    scope.steps.sign( scope ),
+    scope.timeout
+  );
+});
+```
 
-Our unit tests are in `./tests/unit_tests` and their filenames end in `.test.js`. Like the cucumber tests, they use chai for assertions. The fixtures for the tests are also contained in that folder and end in `.fixtures.js`.
+See [the documentation](https://assemblyline.suffolklitlab.org/docs/alkiln/writing) for other examples.
 
-If you want to know the commands, you can go to the [instructions for running tests](#running-internal-tests).
+The `.yml` interviews (online forms) those tests go to are in `./docassemble/ALKilnTests/data/questions/*.yml`.
 
-### Files that you don't need to look at
+#### Unit tests
+
+Our unit tests are in `./tests/unit_tests` and their filenames end in `.test.js`. Like some of the cucumber Steps, they use chai for assertions. The fixtures for the tests are also contained in that folder and end in `.fixtures.js`.
+
+We also validate our log codes. Log codes help identify specific messages the user gets. An example of a log code is `ALK0105`. We want to avoid repeating or leaving out log code numbers, so we check those log codes before pushing or merging. That test, a bash file, is also in `./tests/unit_tests`.
+
+#### GitHub workflow files
+
+Like our users, we use GitHub workflow files in `.github/workflows` to trigger the ALKiln composite actions. These files do their best to act as the most up-to-date demonstration of what an ALKiln workflow file can look like. They contain notes for our users to try to help them adjust the code to their purposes. It's not ideal, but they're the files that we can update most reliably.
+
+Those files use [environment variables that store sensitive information and custom variables](#env).
+
+We also use workflow files to trigger our unit tests and our log codes validation.
+
+### Logging
+
+`./lib/utils/log.js` and `./lib/utils/reports.js` take care of logging information of various kinds (normal, debug, error) to the command line in ways we hope are useful, as well as building files to store the same information. We should probably find a logging library instead, but this is what we have for now. An important feature is that it ensures the messages clearly belong to ALKiln and not to some other process.
+
+### session_vars.js
+
+The `./lib/utils/session_var.js` file keeps track of what you might otherwise think of as environment variables. We like to think of them as constants, but some of them do need to go through functions, so for consistency we get them all through functions. It is also easier to test them when they are functions.
+
+### Bash commands
+
+ALKiln is a command line tool to avoid some complexity in GitHub actions, increase security, and align with what this framework has grown into. When you `npm run` the scripts in our `./package.json` they will setup, run, or take down tests.
+
+### Files that you probably don't need to look at
 
 `index.js` and `world.js` are short files that cucumber needs.
 
 ## Footnotes
 
-[1] To be clear, our framework is a misuse of cucumberjs. cucumberjs is geared towards behavior driven development. We try to make BDD available to our developers, but it's not always possible and not necessarily our goal.
+[^1]: Some of our tests are sometimes in a failing state. For example, at times docassemble has changed its behavior and accessibility tests have failed. Those problems take a while to update and in the meantime we still need to continue development. For that reason, we sometimes mark tests with the tag `@temp_error`.
+</br></br>We have tests that pass when they cause errors. They let us test our own error messages and error behavior. They will log an `F` in the console and yet those Scenarios will still pass.
+</br></br>We also have some tests that cause actual errors so we can see their proper behavior. We have to run those manually and we avoid running them on GitHub. They have the tag `@error`.
+
+[^2]: To be clear, our framework is a misuse of cucumberjs. cucumberjs is geared towards behavior driven development. We try to make BDD available to our developers, but it's not always possible and not necessarily our goal.

package/docs/decisions/adopt_architectural_decision_records.md

@@ -0,0 +1,58 @@
+# Document decisions
+
+## Context and Problem Statement
+
+What is a good way to avoid re-hashing old decisions, or to at least know why those decisions were made?
+
+## Considered Options
+
+- GitHub issues
+- GitHub discussions
+- Actual files in the repo
+
+Formats:
+- https://adr.github.io/madr
+
+
+## Decision Outcome
+
+Use in-repo .md files using the https://adr.github.io/madr format. We found keeping the data within the repo to be the most compelling factor.
+
+## Pros and Cons of the Options
+
+### GitHub issues
+
+Pros:
+
+- Easy to search.
+- Can add labels and such.
+- In one of the most common places to search.
+- Allows comments
+
+Cons:
+
+- Not actually in the repository, so any forks or clones would lose that info.
+- Comments can get confusing and hard to read.
+
+### GitHub discussions
+
+Pros:
+
+- Labels and such.
+- Probably easy to search?
+
+Cons:
+
+- A separate place from issues. Not everyone even knows those exist.
+- All the cons of GitHub issues
+
+### Actual files in the repo
+
+Pros:
+
+- They go everywhere the repo goes.
+
+Cons:
+
+- Probably not as searchable, though maybe we could institute a way to "label"/tag them.
+- Not very visible.

package/docs/decisions/detect_sign_in.md

@@ -0,0 +1,124 @@
+# Use response data to detect sign-in success
+
+## Context and Problem Statement
+
+What is a robust way to detect whether signing in worked or not?
+
+## Considered Options
+
+- Elements in the DOM.
+  - Use some class or ID that only the sign-in page has, so we can detect that a user is on a new page and succeeded.
+  - User-facing invalidation message elements in the DOM on failure.
+- URL change.
+- Response data.
+
+## Decision Outcome
+
+Use a change in the URL to detect sign-in navigation.
+
+## Pros and Cons of the Options
+
+### DOM
+
+Pros:
+
+- It can be easy to do with the tools we are using.
+
+Cons:
+
+- The DOM can, and has been, changed by docassemble and these kinds of changes are made pretty quietly so we find it hard to keep track of them.
+- It is pretty easy for site developers to change the HTML of standard pages like the sign-in page.
+
+### URL change
+
+Pros:
+
+- It seems very likely that developers will keep an unsuccessful sign-in on the same page, even if they change some other functionality.
+- It seems very likely that developers will change the url when the sign-in succeeds.
+- Sticking with checking the url would mesh with how we currently detecting page navigation. See the cons for issues with that.
+
+Cons:
+
+- It seems precarious, though I haven't yet been able to articulate why. I know it hasn't been a sufficient full solution in the past for interview pages. For example, in a `show if` infinite page loop.
+- Developers can manipulate a page's url, though it seems unlikely in this situation.
+
+### Response data
+
+Use the response data from the sign in request.
+
+Pros:
+
+- It seems reliable - it seems very likely that developers will re-direct their users to a different page, even if they change some other functionality.
+- Less likely to change than the DOM.
+- Has some standard values we can expect, like status codes.
+
+Cons:
+
+- DA's responses are not typical. There's no 400's in unsuccessful responses.
+- Regular interview page navigation doesn't get a 302, so this method would be a special case for signing in.
+
+Options are:
+
+- 302 redirection status. It seems fairly reliable that a developer will send a user to a different page after they sign in, and also likely that they will keep the user on the same page if the sign-in failed.
+- Cache-Control header value that contains "must-revalidate" (See [MDN cache control directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#directives)). It makes sure this data isn't cached. I'm not familiar with this and I'm not sure what might or might not trigger this.
+- Cookie with the name "secret". This seems promising, but I don't know much about cookies.
+
+Based on our current knowledge, we think the 302 status response will be most reliable.
+
+Notes for response data:
+
+I have isolated the differences between the sign-in success and failure responses.
+
+Key for following entries:
+
+```
+<key of object containing the data>
+  🌈 <sign in success data>
+vs
+  🤕 <sign in failure data>
+```
+
+Findings:
+
+```
+response
+  🌈 "redirectURL": "/path", "headersSize": 552, "bodySize": 0, "_transferSize": 552,
+vs
+  🤕 "redirectURL": "", "headersSize": 570, "bodySize": 1998, "_transferSize": 2568,
+---
+response
+  🌈 "status": 302, "statusText": "FOUND",
+vs
+  🤕 "status": 200, "statusText": "OK",
+
+---
+headers
+  🌈 no cache-control
+vs
+  🤕 { "name": "Cache-Control", "value": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0" },
+---
+headers
+  🌈 { "name": "Content-Length", "value": "209" },
+vs
+  🤕 { "name": "Content-Encoding", "value": "gzip" },
+---
+headers
+  🌈 { "name": "Location", "value": "/interviews" },
+vs
+  🤕 no location
+---
+headers
+  🌈 { "name": "Set-Cookie", "value": "secret=secretchars; Secure; HttpOnly; Path=/; SameSite=Lax" },
+vs
+  🤕 no secret
+---
+headers
+  🌈 no transfer-encoding
+vs
+  🤕 { "name": "Transfer-Encoding", "value": "chunked" },
+---
+cookies
+  🌈 { "name": "secret", "value": "secretchars", "path": "/", "domain": "site.com", "expires": null, "httpOnly": true, "secure": true, "sameSite": "Lax" },
+vs
+  🤕 no secret
+```

package/docs/decisions/pdfjs_version_2024_08_08.md

@@ -0,0 +1,18 @@
+# Leave pdfjs at its current version
+
+## Context and Problem Statement
+
+pdfjs has a security vulnerability (that does not affect us) where malicious PDFs can inject code into an unsuspecting project and cause havoc.
+
+Our users are downloading and manipulating their own PDFs. We will assume they're not putting malicious code into their PDFs.
+
+The update changes pdfjs .js files to be .mjs files. It might take some bother to configure our repo to use .mjs files.
+
+## Considered Options
+
+- Update pdfjs
+- Leave pdfjs at its current version, 3.2.146
+
+## Decision Outcome
+
+Leave pdfjs at its current version, 3.2.146. The vulnerability is irrelevant for our situation and we don't have bandwidth to set up the configurations right now.

package/docs/decisions/update_puppeteer_2024_07_28.md

@@ -0,0 +1,62 @@
+# Use response data to detect sign-in success
+
+## Context and Problem Statement
+
+Should we update to the newest version of puppeteer, [22.15.0](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/CHANGELOG.md#22150-2024-07-31)?
+
+See https://github.com/SuffolkLITLab/ALKiln/issues/930.
+
+## Considered Options
+
+- Update to 22.15.0
+- Update to 22.12.0, which is the lowest version that would fix our current problems
+- Stay with 20.8.2
+
+See pros and cons
+
+## Decision Outcome
+
+Update puppeteer from 20.8.2 to 22.15.0
+
+## Pros and Cons of the Options
+
+### Update at all {#update}
+
+**Pros:**
+
+- Makes the current fix possible
+
+**Cons:**
+
+- Change in the middle of a complex PR
+- [A few breaking changes](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/CHANGELOG.md#2200-2024-02-05), which includes for us at the very least:
+   - "Removes the deprecated `$x` (replace with `$$`) and `waitForXpath` (replace with `waitForSelector`)." We need to add [extra syntax to the start of our selector strings](https://github.com/puppeteer/puppeteer/pull/11782): "xpath//."
+   - Replace any `page.waitForTimeout` with cucumber's version or ours.
+
+### Update to to 22.15.0
+
+**Pros:**
+
+- Has all the most recent bug fixes and features
+
+**Cons:**
+
+- Exposes us to possible unknown new bugs
+
+
+### Update to to 22.12.0
+
+This is the lowest version that would fix our problem
+
+**Pros:**
+
+- Avoids possibly unknown new bugs
+
+**Cons:**
+
+- Doesn't have fixes to already known bugs
+
+
+### Stay with 20.8.2
+
+Opposite of first entry ["Update at all"](#update).