Add "Breaking news" feature so ALKilnInThePlayground can show

CHANGELOG.md

@@ -18,32 +18,49 @@ Security - in case of vulnerabilities.
 Format:
 
 ## [Unreleased]
+
 - 
 
 ## [1.0.0] - 2021-01-16
 ### Added
+
 - 
 
 ### Changed
+
 - 
 
 ### Deprecated
+
 - 
 
 ### Removed
+
 - 
 
 ### Fixed
+
 - 
 
 ### Security
+
 - 
 
 ### Internal
+
 - 
 -->
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Added
+
+- "Breaking news" feature for ALKilnInThePlayground - a way new ALKiln versions can talk directly with authors even if ALKilnInThePlayground's version stays the same. ALKilnInThePlayground will be able to get text from ALKiln that ALKilnInThePlayground can turn into Mako and then insert on a screen the author can see.
+
+### Changed
+
+- Implement constrained random answers Step for ALKilnInThePlayground.
+
 
 ## [5.15.4] - 2025-11-29
 

docassemble/ALKilnTests/data/sources/observation_steps.feature

@@ -212,7 +212,7 @@ Scenario: I enter the date and time
     | time_input | 12:34 PM | |
 
 @fast @o16 @signature @screenshot
-Scenario: I take a screenshot of the signature
+Scenario: I take a screenshot of the typed signature
   Given I start the interview at "test_signature.yml"
   When I sign with the name "David"
   And I take a screenshot

docassemble/ALKilnTests/data/sources/story_tables.feature

@@ -119,7 +119,7 @@ Scenario: 0 target_number for there_are_any and target_number lists, 1 for there
   And I SHOULD see the phrase "target_people people: 0"
 
 @slow @st6 @loops
-Scenario: target_number 2 for there_are_any, there_is_another, and target_number lists
+Scenario: proxy target_number 2 for there_are_any, there_is_another, and target_number lists
   Given I start the interview at "test_loops.yml"
   And I take a screenshot
   And I get to "end" with this data:
@@ -138,7 +138,7 @@ Scenario: target_number 2 for there_are_any, there_is_another, and target_number
   And I SHOULD see the phrase "target_people people: 2"
 
 @slow @st6_no_proxy @loops @no_proxy
-Scenario: target_number 2 for there_are_any, there_is_another, and target_number lists
+Scenario: no proxy target_number 2 for there_are_any, there_is_another, and target_number lists
   Given I start the interview at "test_loops.yml"
   And I take a screenshot
   And I get to "end" with this data:

docs/decisions/2025_06_12-breaking_news_feat.md

@@ -0,0 +1,118 @@
+# Document decisions
+
+## Context and Problem Statement
+
+Sometimes we want to let authors who use ALKilnInThePlayground (ALKiP) know about changes or enhancements to ALKiln that can affect their use of ALKiP.
+
+ALKiP is closely coupled with, yet disconnected from, ALKiln. Authors can update to the latest ALKiln version right inside the ALKiP interview, but the relationship between the versions of the two packages can be a little unclear so mistakes are easy to make.
+
+
+## Considered Options
+
+- Make a new nodejs executable for ALKiP to use
+- Leave the system alone and just stick to making announcements
+
+
+## Decision Outcome
+
+Make a new nodejs executable for ALKiP to use.
+
+
+## Pros and Cons of the Options
+
+### New executable
+
+Pros:
+
+It will let us do something we usually are unable to do - tell our authors new information without requiring them to update ALKiP first. It will keep authors informed who:
+
+- Don't have the bandwidth to keep up with the community channels
+- Don't have the bandwidth to check the changelog regularly
+- Are unsure how to align versions of ALKiP with ALKiln
+
+Cons:
+
+- It creates a new strange coupling between ALKiln and ALKiP. That said, this new coupling is a very light coupling.
+- It gives ALKiln a way to influence ALKiP. We will have to make sure that we review the "breaking news" code to make sure that any Mako that gets executed will be safe. Granted, that is the case with most code everywhere.
+
+
+### Just announcements in community channels
+
+Pros:
+
+- Less work
+- Less coupling between ALKiln and ALKiP
+
+Cons:
+
+- We should keep making announcements in our community channels regardless, but I feel it's insufficient. In GitHub actions, most authors use an up-to-date version of ALKiln. I'm not as sure about ALKiP sitting on author's servers with no indications of updates. Docassemble didn't have indications of an out of date installed packages the last time I looked.
+
+<!-- Fun for internal developers
+
+Brainstorms that went into creating the new feature:
+
+What kind of info could we need?
+
+Now:
+
+- Version of ALKiln users are asking for
+- Version of ALKiP they have in the Playground
+- Current version of ALKiln
+
+Will we need more info in the future?
+
+- docassemble-os/docassemble version?
+- version of AssemblyLine if it's there?
+- various env vars...? Not sure which ones, though, and those change. All env
+  vars seems like tmi, though we are sending all env vars for test runs anyway.
+- npm-shrinkwrap.json of ALKiln? Or maybe just package.json? We should be able
+  to see that in the given version of ALKiln.
+- addresses of files we know we've put on the system...? (runtime_config.json)
+- contents of files we know we've put on the system...? (runtime_config.json)
+- question id (https://docassemble.org/docs/functions.html#current_context)
+- variable being sought (https://docassemble.org/docs/functions.html#current_context)
+- start_time (https://docassemble.org/docs/functions.html#start_time)
+
+
+Message format?
+
+| Reason | Announcement |
+| --- | --- |
+| ALKiln version >= ... with ALKilnInTheP version <= ... | the message |
+
+or
+
+## Hear ye, hear ye
+
+An ALKiln version or two has one or more messages for you
+
+| Why this message? | Message |
+| --- | --- |
+| You have ALKiln >= ... and ALKiP <= ... | the message |
+
+or
+
+| Relevant versions | Message |
+| ALKiln >= ..., ALKiP <= ... | the message |
+
+or
+
+## 📯 📣 📰 Breaking news! 📰 📣 📯
+
+An ALKiln version or two has one or more messages for you
+
+~~### Message 1~~
+
+Version mismatch: alk ver >3 and alkp ver < 3
+
+The message
+
+
+Possible `reason`s:
+🏚️ 🧩 🌋 🩺 🧹 💔 🔀 ™️ Version mismatch
+✨ New feature
+🛠️ Fix
+-->
+
+
+

docs/version_formatting_rules.md

@@ -0,0 +1,83 @@
+# Format for ALKiln version numbers
+
+These basically follow a subset of [semver](https://semver.org/) rules when we update our npm package version. We should publish new versions when we need to be able to share our code, either for all our authors to use or for testing. Or maybe just to impress our friends.
+
+Also, remember that version numbers are not a guarantee. Any change may be a breaking change even if we just meant to add a feature or fix a bug. Version numbers just tell our authors what we were trying to do. The road to bugs is paved with good intentions.
+
+Below are our own definitions of the parts (symbols) that ALKiln's version numbers are made of. If a definition includes other symbols, those symbols will have definitions of their own.
+
+Characters you may use:
+
+- `.` (maximum of 3 of these)
+- Alphanumeric (A-z, 0-9)
+- `-`
+
+
+## Stable versions
+
+Summary: `major.minor.patch`
+
+Example: `12.4.105`
+
+When you publish a new major, minor, or patch version of ALKlin, it should have the format of a `stableVersion`.
+
+Definitions:
+
+| symbol | definition |
+| -- | -- |
+| `stableVersion` | `major.minor.patch` (see definitions below) |
+| `.` | A period |
+| `major` | An integer. Increase this by 1 to show that we know that the new code breaks previous ALKiln Steps or other features. Old tests may incorrectly fail or succeed. Old config env var values may behave differently than before. |
+| `minor` | An integer. Increase this by 1 to show that we have a new feature or features in a way that we intend to be backwards compatible. |
+| `patch` | An integer. Increase this by 1 to show that we have fixed a bug or refactored internal code in a way we intend to be backwards compatible. |
+
+
+## Development versions
+
+Summary: `parentVersion-type-purpose-increment`
+
+Example: `12.4.105-feat-story-2`
+
+> [!CAUTION]
+> When you publish a development version, you **must** publish using a descriptive `tag`. The `tag` should be a one-word reminder of the purpose of this version. Example:
+> 
+> ```
+> npm publish --tag "story"
+> ```
+> 
+> > If used in the `npm publish` command, this is the tag that will be added to the package submitted to the registry.
+> \- [npm docs](https://docs.npmjs.com/cli/v11/commands/npm-dist-tag)
+> 
+> If you forget this then your code counts as the latest official version of ALKiln (as far as npm is concerned) and authors' code will automatically use that code to run tests.
+> 
+> Also, forgetting is not the worst thing in the world. Everyone forgets sometimes. I certainly have.
+
+When you are publishing a `devVersion` of ALKiln to try out a feature, fix, or other change, use these rules.
+
+| symbol | definition |
+| -- | -- |
+| `devVersion` | `parentVersion-type-purpose-increment`. Use this version scheme to try out new changes before publishing them for all authors. |
+| `parentVersion` | Has the same format as `stableVersion` (from above). This should be the branch's original version number. Why not a new version number? Because what other core version number do you want to give it? When we start developing a change, we don't know what version number ALKiln will get to before we actually publish this change. The whole world could change in between then and now. |
+| `-` | A dash |
+| `type` | The type of change this is testing. E.g. `feat`, `fix`, `test`, `docs`, `fort` (see definitions below). If you really need something different, you can come up with your own. Then possibly discuss it and add it to these docs. |
+| `purpose` | A one or two word reminder of what specific topic this change is addressing. Really truly try to keep this short. It is just a reminder after all. If you **must** use multiple words, separate them with a dash. |
+| `increment` | An integer. Starts at 1. If this will be your first time publishing for this development, use 1. If this is your second time, use 2. And so on. To be very specific, and more confusing: when you publish these changes to try them out, how many times will you have published changes for this `parentVersion-type-purpose` combination? |
+
+**Some `type`s**
+
+It is better to choose something closer to the top of the list if the definition fits your changes.
+
+| symbol | definition |
+| -- | -- |
+| `feat` | The string "feat". It stands for "feature". Use this when you're making a new feature |
+| `fix` | The string "fix". Use this when you're fixing a bug |
+| `test` | The string "test". Most code changes should include new tests, of course. This is for changes that improve *only* testing. This will help your fellow devs know when to expect just test changes as opposed to refactoring and so on. |
+| `docs` | The string "docs". It stands for "documentation". Use this when you update or add only documentation. This file is an example of documentation! You probably shouldn't need to use this `type`. Why would you need anyone to test docs? Still, there are stranger things, etc. |
+| `fort` | The string "fort". It stands for "fortify". Use this when you are strengthening or improving code in other ways. For example, refactoring. Also for situations where pillow forts can be involved. |
+
+
+## Why did we choose these rules?
+
+1. Simplicity and clarity. Semver has a lot of details our project doesn't need right now, so we can simplify it. Using semver as a base, though, has advantages. It is clear in many ways and a lot of developers are familiar with it.
+1. Our `breaking_news` feature compares version numbers to decide what notifications to show to authors that are using ALKilnInThePlayground. We want to keep those version comparison calculations as simple as possible. At the same time, we want to let internal developers be descriptive enough with version names so that they are useful at-a-glance. This doc describes the balance we have chosen.
+1. I can't remember another reason right now, but every list should have a minimum of 3 items, so here's the 3rd.