Merge pull request #290 from pushkin-consortium/template-overhaul-spr…

…2024

Template overhaul spr2024

.changeset/blue-ghosts-flow.md

@@ -0,0 +1,9 @@
+---
+"@pushkin-templates/exp-grammaticality-judgment": major
+"@pushkin-templates/exp-self-paced-reading": major
+"@pushkin-templates/exp-lexical-decision": major
+---
+
+Experiment templates are now implemented as npm packages. The contents of the templates remain essentially unchanged but are compressed into `build/template.zip`. `pushkin-cli` v4+ is required to install the new packaged templates.
+
+The reason for this change has to do with Pushkin's transition to a monorepo structure. Previously, Pushkin distributed templates through each repo's GitHub releases, but the new monorepo made this more challenging (see [#254](https://github.com/pushkin-consortium/pushkin/issues/254)). By moving to distributing all projects through npm, Pushkin is able to streamline both its deployment workflow and the CLI code itself.

.changeset/famous-toes-speak.md

@@ -0,0 +1,7 @@
+---
+"@pushkin-templates/exp-basic": major
+---
+
+The basic experiment template -- along with all other templates -- is now implemented as an npm package. The contents of the template remain unchanged, but are compressed into `build/template.zip`. `pushkin-cli` v4+ is required to install the new packaged template.
+
+The reason for this change has to do with Pushkin's transition to a monorepo structure. Previously, Pushkin distributed templates through each repo's GitHub releases, but the new monorepo made this more challenging (see [#254](https://github.com/pushkin-consortium/pushkin/issues/254)). By moving to distributing all projects through npm, Pushkin is able to streamline both its deployment workflow and the CLI code itself.

.changeset/forty-insects-serve.md

@@ -0,0 +1,5 @@
+---
+"pushkin-cli": minor
+---
+
+Users can now delete and archive/unarchive experiments using the `remove experiment` (alias `rm exp`) command.

.changeset/friendly-lamps-fold.md

@@ -0,0 +1,9 @@
+---
+"@pushkin-templates/exp-grammaticality-judgment": minor
+"@pushkin-templates/exp-self-paced-reading": minor
+"@pushkin-templates/exp-lexical-decision": minor
+"@pushkin-templates/exp-basic": minor
+"pushkin-cli": minor
+---
+
+Testing with Jest is set up by default on the user's site. Current tests distributed with experiment templates now work after installation.

.changeset/seven-keys-learn.md

@@ -0,0 +1,5 @@
+---
+"pushkin-cli": major
+---
+
+The `--nomigrations` and `--nocache` flags in `prep` and `start` (respectively) are replaced with `--no-migrations` and `--no-cache`.

.changeset/smooth-boxes-collect.md

@@ -0,0 +1,7 @@
+---
+"@pushkin-templates/site-basic": major
+---
+
+The basic site template -- along with all other templates -- is now implemented as an npm package. The contents of the template remain unchanged, but are compressed into `build/template.zip`. `pushkin-cli` v4+ is required to install the new packaged template.
+
+The reason for this change has to do with Pushkin's transition to a monorepo structure. Previously, Pushkin distributed templates through each repo's GitHub releases, but the new monorepo made this more challenging (see [#254](https://github.com/pushkin-consortium/pushkin/issues/254)). By moving to distributing all projects through npm, Pushkin is able to streamline both its deployment workflow and the CLI code itself.

.changeset/three-comics-burn.md

@@ -0,0 +1,5 @@
+---
+"pushkin-cli": patch
+---
+
+If the user's site directory isn't empty when they call `install site`, the CLI now asks if they really want to install their site there.

.gitignore

@@ -7,6 +7,12 @@ build/
 # Test files
 testing/
 
+# Ignore all LICENSE files...
+LICENSE
+# except for the one in the root
+!/LICENSE
+# Root LICENSE will be included when each package is published
+
 # Swap files
 *.swp
 

docs/getting-started/quickstart.md

@@ -23,19 +23,15 @@ mkdir pushkin_quickstart
 cd pushkin_quickstart
 ```
 
-![](../assets/getting-started/quickstart/quickstart_1.gif)
-
 (For more on basic terminal commands, you can check out [this blog post](https://medium.com/@grace.m.nolan/terminal-for-beginners-e492ba10902a).)
 
 Install your pushkin site in the directory you just created:
 
 ```
 pushkin install site
 ```
-
-You will be asked to select a site template to use. Choose **basic**, then choose the recommended version.
-
-![](../assets/getting-started/quickstart/quickstart_2.gif)
+You will be asked where you want to look for a site template. Choose **Official Pushkin distribution**. 
+You will then be asked to select a site template to use. Choose **site-basic**; then choose the recommended version.
 
 This sets up a skeleton website in the current folder and a development database. Once the command finishes, you should have a directory tree like this:
 
@@ -108,16 +104,16 @@ salt: "cognitivescience"
 To add experiments to your Pushkin site, run:
 
 ```
- pushkin install experiment
+pushkin install experiment
 ```
 
 You'll first be asked what you want to name your experiment. Call it `hello`, since we're going to make this experiment a simple "hello, world" example.
 
-Then you'll be asked which experiment template you want to use. The **basic** template is a bare-bones "hello, world" experiment. Choose **basic** and then select the recommended version of the template. Choose 'no' when asked if you want to import a jsPsych experiment (this option only applies to the basic template).
+You'll then be asked where you want to look for experiment templates; choose **Official Pushkin distribution**. 
 
-Repeat the process above but this time select the **lexical-decision** template. You can call this one `lexdec`. Now do the same thing for the **grammaticality-judgment** and **self-paced-reading** templates, naming them `gram` and `spr`.
+Then you'll be asked which experiment template you want to use. The **exp-basic** template is a bare-bones "hello, world" experiment. Choose **exp-basic** and then select the recommended version of the template. Choose 'no' when asked if you want to import a jsPsych experiment (this option only applies to the basic template).
 
-![](../assets/getting-started/quickstart/quickstart_3.gif)
+Repeat the process above but this time select the **lexical-decision** template. You can call this one `lexdec`. Now do the same thing for the **grammaticality-judgment** and **self-paced-reading** templates, naming them `gram` and `spr`.
 
 The `experiments` directory of your site should now look like this:
 
@@ -167,45 +163,53 @@ experimentName: 'My super fun experiment!'
 Keeping all the files for an experiment within the same root folder is convenient for development, but not for actually deploying the website. To reorganize your site for deployment (and local testing), run:
 
 ```
- pushkin prep
+pushkin prep
 ```
 
-![](../assets/getting-started/quickstart/quickstart_4.gif)
-
 !!! note
     Don't worry: `pushkin prep` won't jumble up the files in the `pushkin_quickstart` directory you created; rather it reorganizes the files into Docker containers. There's never any need to "unprep" your site. You can run `pushkin prep`, make changes in your local site directory, re-run `pushkin prep`, and the changes you made will be reflected in Docker.
 
 ## Testing your site locally
 
 Now let’s look at your website! Start your local deploy by running:
 
-```bash
- pushkin start
 ```
-
-![](../assets/getting-started/quickstart/quickstart_5.gif)
+pushkin start
+```
 
 In a web browser, open [localhost](http://localhost) and you should see your site with the experiments you made. Click on the one you called `hello`. It should display "Hello world!". Complete the experiment by pressing any key. If you want to take a look at the other experiments you made, feel free to look over those now too.
 
 When you are done looking at your website, stop the local deploy by running:
 
 ```
- pushkin stop
+pushkin stop
 ```
 
-![](../assets/getting-started/quickstart/quickstart_7.gif)
-
 If you don’t do that, the web server will keep running in Docker until you quit Docker or restart. When the command has finished running, it should output `done`.
 
 ## Updating your site
 
 Imagine now you want to add another experiment or edit an existing one. Every time you update your site, you’ll need to run `pushkin prep` (and `pushkin start` if you want to look at your updates) again:
 
 ```
- pushkin prep
- pushkin start
+pushkin prep
+pushkin start
+```
+### Removing experiments 
+
+If you'd like to get rid of one or more of your site's experiments, you can remove them with this command:
+
+```
+pushkin remove experiment
 ```
 
+There are two options when removing an experiment, **archive** and **delete**. Archiving an experiment simply removes it from your site's front end. This means that the experiment will no longer be accessible to participants. Archiving an experiment can be undone by calling `pushkin remove experiment` again and specifying the `unarchive` mode. Deleting an experiment removes all of its files, data, and Docker components. Deleting an experiment is **irreversible**, so be sure you want the experiment gone before using this mode.
+
+!!! warning
+    For technical reasons, the current implementation of the `delete` mode deletes **all** experiments' data from your local database, not just the experiment(s) you deleted. Future development may address this limitation.
+
+Since the `remove experiment` command updates your site, you will need to run `pushkin prep` afterwards just like if you added an experiment or edited other parts of your site.
+
 ## Viewing your data
 
 At this point, you should have generated some data by testing at least one of your experiments. In order to view it, you can use whatever Postgres manager you installed based on the Pushkin [installation instructions](installation.md#installing-a-postgres-manager). Here, we'll go over how to view the data using either pgAdmin or SQLTools.

docs/getting-started/simple-experiment-tutorial.md

@@ -44,7 +44,7 @@ You should now have a folder in your site called `/experiments/lexdec` with the
 Open `/lexdec/web page/src/experiment.js`. It should look like this:
 
 ```js title="experiment.js"
---8<-- "templates/experiments/basic/web page/src/experiment.js"
+--8<-- "templates/experiments/basic/src/web page/src/experiment.js"
 ```
 
 From the jsPsych code [above](#initial-jspsych-code), copy everything between `const timeline = []` and `jsPsych.run(timeline);` (excluding those lines). Paste that content into `experiment.js` (replacing the existing content) between `const timeline = []` and `return timeline`. Thus you should now have a function `createTimeline()` within which you build up and finally return the timeline for the experiment.
@@ -58,7 +58,7 @@ In the jsPsych code [above](#initial-code), plugins are loaded with `<script>` t
 In theory, there's nothing preventing you from declaring your stimuli inside `experiment.js` in the same way as shown above in [`lexical-decision.html`](#initial-jspsych-code); however, we can keep our `experiment.js` tidier by exporting the stimuli from a dedicated file `/lexdec/web page/src/stim.js` like this:
 
 ```javascript title="stim.js"
---8<-- "templates/experiments/lexical-decision/web page/src/stim.js"
+--8<-- "templates/experiments/lexical-decision/src/web page/src/stim.js"
 ```
 
 Then we need to import `stimArray` into `experiment.js` by adding the following line underneath the `import` statement for the plugin: 
@@ -72,7 +72,7 @@ import stimArray from './stim';
 The experiment [above](#initial-jspsych-code) relies on CSS styling from `<link>` and `<style>` tags to display the experiment correctly. This styling needs be moved to `/experiments/lexdec/web page/src/assets/experiment.css` in order to style your Pushkin experiment. The new CSS file will look like this:
 
 ```css title="experiment.css"
---8<-- "templates/experiments/lexical-decision/web page/src/assets/experiment.css"
+--8<-- "templates/experiments/lexical-decision/src/web page/src/assets/experiment.css"
 ```
 
 ## Finishing up

docs/packages/pushkin-cli.md

@@ -106,6 +106,46 @@ If you select the basic template, this command will give you the option to impor
 
 The command also integrates a new experiment into the Pushkin framework. It performs key tasks such as updating template file names and contents to reflect the new experiment's name, setting up database migrations, initializing essential directories for the experiment's API, web page, and worker components, and ensuring the experiment is correctly configured in the Docker environment. The API and web page components are then locally published using yalc.
 
+### remove experiment
+
+This command allows users to remove an experiment from their site and offers two removal modes:
+
+1. **delete:** Deleting an experiment permanently removes all of its files, data, and associated Docker components. This command should only be used if you want the experiment completely gone, as it is irreversible. Note that this mode currently runs [`kill`](#kill), and will consequently delete **all** experiments' data from your local database, not just the experiment(s) you deleted. Future development may address this limitation.
+2. **archive:** Archiving an experiment removes it from your site's front end, so it is no longer accessible to participants. However, all of the experiment's files remain in place and the site's back end and data will not be affected.
+
+The command has a third mode, `unarchive`, that adds archived experiments back to your site's front end.
+
+!!! note
+    You must run [`prep`](#prep) after `remove experiment` for changes to your site to take effect.
+
+**Syntax:**
+
+```
+pushkin remove experiment <options>
+```
+
+or
+
+```
+pushkin rm exp <options>
+```
+
+**Options:**
+
+- experiments: `-e` or `--experiments` allows you to specify which experiment(s) to delete, archive, or unarchive. Provide the experiments' short names (i.e. the name of the folder in the `/experiments` directory) separated by spaces after the `-e` flag (e.g. `pushkin rm exp -e exp1 exp2 exp3`). If the `--experiments` option is omitted, the CLI will interactively prompt you to select the experiments you want.
+
+- mode: `-m` or `--mode` allows you to specify the `delete`, `archive`, or `unarchive` mode (e.g. `pushkin rm exp -m delete`). If the `--mode` option is omitted, the CLI will interactively prompt you to select which mode you want.
+
+- force: `-f` or `--force` applies only to the `delete` mode and allows you to suppress the deletion confirmation prompt.
+
+- verbose: `-v` or `--verbose` shows additional console output during the removal process which may be helpful for debugging.
+
+- help: `-h` or `--help` displays the command's help information.
+
+**Details:**
+
+Archiving and unarchiving experiments is a simple operation that entails setting the `archived` property in the experiment's `config.yaml` file to `true` or `false`. You can change this property manually if you wish, but using `pushkin rm exp -m archive` offers a convenient way to quickly change this property for multiple experiments.
+
 ### updateDB
 
 Runs migrations and seeds for experiments to update the database. This is set up to ensure experiments using the same database (as defined in `pushkin.yaml`) are migrated at the same time to avoid errors with the `knex_migrations` table. This is automatically run as part of `pushkin prep`.
@@ -127,7 +167,7 @@ pushkin prep <options>
 ```
 **Options:**
 
-- no-migrations: `--nomigrations` will run `prep` without database migrations. If you do this, make sure the database structure has not changed since you ran `prep` previously (with migrations).
+- no-migrations: `--no-migrations` will run `prep` without database migrations. If you do this, make sure the database structure has not changed since you ran `prep` previously (with migrations).
 
 - verbose: `-v` or `--verbose` shows additional console output which may be helpful for debugging.
 
@@ -155,7 +195,7 @@ pushkin start <options>
 
 **Options:**
 
-- no-cache: `--nocache` will rebuild all Docker images from scratch without using the cache. By default, this is false.
+- no-cache: `--no-cache` will rebuild all Docker images from scratch without using the cache. By default, this is false.
 
 - verbose: `-v` or `--verbose` shows additional console output which may be helpful for debugging.
 

packages/pushkin-api/package.json

@@ -18,7 +18,8 @@
     ],
     "scripts": {
         "test": "jest",
-        "build": "babel src -d build"
+        "build": "babel src -d build",
+        "prepack": "cp ../../LICENSE ."
     },
     "keywords": [
         "pushkin",

packages/pushkin-cli/package.json

@@ -11,7 +11,8 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "babel src -d build"
+    "build": "babel src -d build",
+    "prepack": "cp ../../LICENSE ."
   },
   "keywords": [
     "pushkin",
@@ -29,10 +30,9 @@
     "eslint-plugin-import": "^2.22.0"
   },
   "dependencies": {
-    "adm-zip": "^0.4.16",
     "balanced-match": "^1.0.0",
     "command-line-args": "^5.1.1",
-    "commander": "^6.0.0",
+    "commander": "^11.1.0",
     "core-js": "^3.6.5",
     "corejs": "^1.0.0",
     "docker-compose": "^0.23.5",
@@ -45,7 +45,6 @@
     "regenerator-runtime": "^0.13.5",
     "replace-in-file": "^6.1.0",
     "shelljs": "^0.8.4",
-    "superagent": "^5.3.1",
     "tar": "^6.0.2",
     "uuid": "^8.3.0"
   }

packages/pushkin-cli/src/commands/aws/index.js

@@ -94,7 +94,7 @@ const buildFE = function (projName) {
       console.log(modName, " does not have build-if-changed installed. Recommend installation for faster runs of prep.")
       buildCmd = pacMan.concat(' --mutex network run build')
     } else {
-      console.log("Using build-if-changed for ",projName)
+      console.log("Using build-if-changed for", projName)
       const pacRunner = (pacMan == 'yarn') ? 'yarn' : 'npx'
       buildCmd = pacRunner.concat(' build-if-changed --mutex network')
     }