Implement views for file actions (#87)

This PR adds a marketplace for file actions.

<div align="center">
<img
src="https://github.com/user-attachments/assets/fce0a1fe-0c7f-4903-b21f-bf2e55f983e0"
width=800>
</div>

<details>

<summary>
<strong>How it looks on mobile</strong>
</summary>

<div align="center">
<img
src="https://github.com/user-attachments/assets/865898cb-0e2c-4b50-b0c2-0bd2da041707"
width=500>
</div>

</details>

## Changelog
* Add a `description` field to `FileAction`
* Right now it's a `CharField(max_length=100)`, it should be discussed
whether a `TextField` or a `CharField` with a larger length limit is
needed.
* Add a view for managing file actions
  * Teachers can add and remove file actions from their course here.
  * Redirects to a new create/edit view
* Add a create/edit view.
    * If `?copy=1` is passed, it will create a copy of a file action.
* Changed file action parsing from `self.command.split(" ")` to
`shlex.split` for more intuitive command behavior.
* Changes css rule `.btn.btn-ion` to `.btn-ion`
* It was confusing if `.btn` did anything, or if you were supposed to do
`.btn.tin-btn`, etc.

## TODO
- [x] CSS
- [x] "Marketplace" for courses
- [x] Views
- [x] Docs
- [x] Tests
- [x] Turn trash button into normal remove button
- [ ] Improve copy file action

Closes #7

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: JasonGrace2282

docs/source/usage.md

@@ -10,4 +10,5 @@ the pages below:
 usage/graders/writing_graders
 usage/graders/examples
 usage/submission-cap
+usage/file-actions
 ```

docs/source/usage/file-actions.md

@@ -0,0 +1,53 @@
+# File Actions
+
+File actions are Tin's way of running commands on the files of an assignment.
+
+For example, say you have a Java file used in a grader, and you wanted to compile
+it into a `.class` file. Instead of compiling the java file locally and uploading
+the class file to Tin each time you change it, you can upload the Java file to
+Tin and use a file action to compile it to a `.class` file.
+
+## The File Action Marketplace
+When viewing a course, there will be a button called "Manage File Actions". This will take you to the
+File Action Marketplace, where you can see every file action created across courses, or create your
+own file action. We **strongly recommend** checking if a file action that suits your needs can be found
+in the marketplace before creating your own.
+
+After adding a file action to your course, you can edit it, copy it, or remove it from your course
+by hovering over it.
+
+## File Action Commands
+Let's take the previous example of compiling all `.java` files uploaded to Tin.
+To do that, we need to:
+
+1. Find all files _ending_ with `.java`
+2. Run `javac <space separated filenames>`
+
+To do this, we can create a file action with
+
+- Match type set to "Ends with"
+- Match value set to `.java`
+- The command set to `javac $FILES`
+
+```{note}
+For security reasons, the command does not have the same capabilities
+as a full shell. For example, redirections, heredocs, or command substitutions
+are not possible. Instead, think of the command as being run as a subprocess.
+```
+
+## `$FILE` vs `$FILES`
+In some cases, the need may arise to call a command on every
+matching file, instead of a space separated list of filenames. In such
+a case, one can use `$FILE` instead of `$FILES`.
+
+To illustrate, suppose we had the following directory structure:
+```
+.
+├── Bar.java
+├── data.txt
+└── Foo.java
+```
+Then, assuming that the match value is set to ending with `.java`,
+
+- Setting the command to `javac $FILES` would run `javac Bar.java Foo.java`
+- Setting the command to `javac $FILE` would first run `javac Bar.java` and after that, `javac Foo.java`

tin/apps/assignments/forms.py

@@ -7,7 +7,7 @@
 from django.db.models import Q
 
 from ..submissions.models import Submission
-from .models import Assignment, Folder, Language, MossResult, SubmissionCap
+from .models import Assignment, FileAction, Folder, Language, MossResult, SubmissionCap
 
 logger = getLogger(__name__)
 
@@ -305,3 +305,58 @@ class Meta:
             "student": "The student to apply the cap to.",
         }
         labels = {"submission_cap_after_due": "Submission cap after due date"}
+
+
+class FileActionForm(forms.ModelForm):
+    """A form to create (or edit) a :class:`.FileAction`."""
+
+    class Meta:
+        model = FileAction
+        fields = [
+            "name",
+            "description",
+            "command",
+            "match_type",
+            "match_value",
+            "case_sensitive_match",
+        ]
+        widgets = {
+            "description": forms.Textarea(attrs={"cols": 32, "rows": 2}),
+        }
+
+    def clean(self):
+        cleaned_data = super().clean()
+        if cleaned_data is None:
+            cleaned_data = self.cleaned_data
+        cmd = cleaned_data.get("command", "")
+
+        if "$FILE" in cmd or "$FILES" in cmd:
+            if not cleaned_data.get("match_type"):
+                self.add_error("match_type", "required if command uses $FILE or $FILES")
+            if not cleaned_data.get("match_value"):
+                self.add_error("match_value", "required if command uses $FILE or $FILES")
+
+        return cleaned_data
+
+
+class ChooseFileActionForm(forms.Form):
+    """A form to choose a file action.
+
+    .. warning::
+
+        This will allow a user to modify any file action,
+        including file actions that are added to a course the user
+        is not a teacher in.
+
+    This form is primarily intended for use with Javascript,
+    where the file action id cannot be determined at template rendering
+    time.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self.fields["file_action"] = forms.ModelChoiceField(
+            queryset=FileAction.objects.all(),
+            widget=forms.HiddenInput(),
+        )

tin/apps/assignments/migrations/0036_fileaction_description.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.12 on 2026-03-21 21:29
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('assignments', '0035_remove_submissioncap_unique_type_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='fileaction',
+            name='description',
+            field=models.CharField(blank=True, max_length=100),
+        ),
+    ]

tin/apps/assignments/models.py

@@ -1,6 +1,7 @@
 import datetime
 import logging
 import os
+import shlex
 import subprocess
 from pathlib import Path
 from typing import Literal
@@ -713,11 +714,20 @@ def run_action(command: list[str]) -> str:
 
 
 class FileAction(models.Model):
-    """Runs a user uploaded script on files uploaded to an assignment."""
+    """Runs a user uploaded script on files uploaded to an assignment.
+
+    This can also take (fake) environment variables like ``$FILE``/``$FILES``,
+    which are replaced with their actual value.
+
+    ``$FILES`` is expanded to a space separated list of paths that match the filter.
+
+    ``$FILE`` means the command will be called once with each file that matches the filter.
+    """
 
     MATCH_TYPES = (("S", "Start with"), ("E", "End with"), ("C", "Contain"))
 
     name = models.CharField(max_length=50)
+    description = models.CharField(max_length=100, blank=True)
 
     courses = models.ManyToManyField(Course, related_name="file_actions")
     command = models.CharField(max_length=1024)
@@ -736,7 +746,9 @@ def __repr__(self):
 
     def run(self, assignment: Assignment):
         """Runs the command on the input assignment"""
-        command = self.command.split(" ")
+        # shlex.split splits it with POSIX-style shell syntax
+        # This handles e.g. echo "Hello World" correctly
+        command = shlex.split(self.command)
 
         if (
             ("$FILE" in self.command or "$FILES" in self.command)

tin/apps/assignments/tests/test_file_actions.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from django.urls import reverse
+
+from tin.tests import login, model_to_dict
+
+from ..models import FileAction
+
+
+@login("teacher")
+def test_manage_file_actions_view(client, course, file_action) -> None:
+    # make sure the view works
+    url = reverse("assignments:manage_file_actions", args=[course.id])
+    response = client.get(url)
+    assert response.status_code == 200
+
+    file_action.courses.clear()
+    response = client.post(url, {"file_action": file_action.id})
+    assert file_action.courses.filter(id=course.id).exists()
+
+
+@login("teacher")
+def test_create_file_action_view(client, course) -> None:
+    url = reverse("assignments:create_file_action", args=[course.id])
+    # make sure the view works normally
+    response = client.get(url)
+    assert response.status_code == 200
+
+    response = client.post(url, {"name": "Hi", "command": "echo bye"})
+    assert course.file_actions.count() == 1
+
+    response = client.post(url, {"name": "Hi", "command": "echo $FILES"})
+    assert course.file_actions.count() == 1, (
+        f"Creation form should error if $FILES is a command without a match value (got {response})"
+    )
+
+    file_action = course.file_actions.first()
+    assert file_action is not None
+    fa_data = model_to_dict(file_action)
+
+    # try copying the data
+    response = client.post(f"{url}?action={file_action.id}", fa_data | {"copy": True})
+    assert course.file_actions.count() == 2, (
+        "Passing copy as a POST parameter should copy the file action"
+    )
+
+    # or modifying the original instance
+    client.post(f"{url}?action={file_action.id}", fa_data | {"name": "New name!"})
+    file_action.refresh_from_db()
+    assert file_action.name == "New name!"
+
+    response = client.post(f"{url}?copy=1", fa_data | {"copy": True})
+    assert course.file_actions.count() == 3, (
+        f"Passing copy without an action should create a file action (got {response})"
+    )
+
+
+@login("teacher")
+def test_delete_file_action_view(client, course, file_action) -> None:
+    client.post(
+        f"{reverse('assignments:delete_file_action', args=[course.id])}",
+        {"file_action": file_action.id},
+    )
+    # it should be removed from the course, but should still exist
+    assert not course.file_actions.filter(id=file_action.id).exists()
+    assert FileAction.objects.filter(id=file_action.id).exists()

tin/apps/assignments/urls.py

@@ -22,6 +22,21 @@
         views.delete_file_view,
         name="delete_file",
     ),
+    path(
+        "<int:course_id>/files/actions/manage",
+        views.manage_file_actions,
+        name="manage_file_actions",
+    ),
+    path(
+        "<int:course_id>/files/actions/choose/new",
+        views.create_file_action,
+        name="create_file_action",
+    ),
+    path(
+        "<int:course_id>/files/actions/delete/",
+        views.delete_file_action_view,
+        name="delete_file_action",
+    ),
     path(
         "<int:assignment_id>/files/action/<int:action_id>",
         views.file_action_view,

tin/apps/assignments/views.py

@@ -26,6 +26,8 @@
 from ..users.models import User
 from .forms import (
     AssignmentForm,
+    ChooseFileActionForm,
+    FileActionForm,
     FileSubmissionForm,
     FileUploadForm,
     FolderForm,
@@ -35,7 +37,7 @@
     SubmissionCapForm,
     TextSubmissionForm,
 )
-from .models import Assignment, CooldownPeriod, QuizLogMessage, SubmissionCap
+from .models import Assignment, CooldownPeriod, FileAction, QuizLogMessage, SubmissionCap
 from .tasks import run_moss
 
 logger = logging.getLogger(__name__)
@@ -529,6 +531,104 @@ def file_action_view(request, assignment_id, action_id):
     return redirect("assignments:manage_files", assignment.id)
 
 
+@teacher_or_superuser_required
+def manage_file_actions(request, course_id: int):
+    """Add, remove and edit :class:`.FileAction`s for a :class:`.Course`
+
+    Args:
+        request: The request
+        course_id: The primary key of the :class:`.Course`
+    """
+    course = get_object_or_404(
+        Course.objects.filter_editable(request.user),
+        id=course_id,
+    )
+
+    if request.method == "POST":
+        form = ChooseFileActionForm(request.POST)
+        if form.is_valid():
+            file_action = form.cleaned_data["file_action"]
+            file_action.courses.add(course)
+            return http.JsonResponse({"success": True})
+        return http.JsonResponse({"success": False, "errors": form.errors.as_json()}, status=400)
+
+    actions = FileAction.objects.exclude(courses=course)
+    course_actions = course.file_actions.all()
+    return render(
+        request,
+        "assignments/manage_file_actions.html",
+        {
+            "actions": actions,
+            "course_actions": course_actions,
+            "course": course,
+            "nav_item": "Manage file actions",
+        },
+    )
+
+
+@teacher_or_superuser_required
+def create_file_action(request, course_id: int):
+    """Creates or edits a :class:`.FileAction`
+
+    If the ``GET`` request has a ``action`` parameter,
+    the view will action as an edit view.
+
+    Args:
+        request: The request
+        course_id: The primary key of the :class:`.Course`
+    """
+    course = get_object_or_404(Course.objects.filter_editable(request.user), id=course_id)
+    if (action_id := request.GET.get("action", "")).isdigit():
+        action = get_object_or_404(course.file_actions, id=action_id)
+    else:
+        action = None
+
+    if request.method == "POST":
+        form = FileActionForm(request.POST, instance=action)
+        if form.is_valid():
+            action = form.save(commit=False)
+            if request.POST.get("copy"):
+                action.pk = None
+                action._state.adding = True
+            action.save()
+            action.courses.add(course)
+            return redirect("courses:show", course.id)
+    else:
+        form = FileActionForm(instance=action)
+
+    return render(
+        request,
+        "assignments/custom_file_action.html",
+        {
+            "form": form,
+            "action": action,
+            "course": course,
+            "nav_item": "Create file action",
+        },
+    )
+
+
+@teacher_or_superuser_required
+@require_POST
+def delete_file_action_view(request, course_id: int):
+    """Removes a :class:`.FileAction` from a :class:`.Course`.
+
+    This does NOT permanently delete the :class:`.FileAction`.
+
+    Args:
+        request: The request
+        course_id: The primary key of the :class:`.Course`
+        action_id: The primary key of the :class:`.FileAction`
+    """
+    course = get_object_or_404(Course.objects.filter_editable(request.user), id=course_id)
+    form = ChooseFileActionForm(request.POST)
+    if form.is_valid():
+        action = form.cleaned_data["file_action"]
+        action.courses.remove(course)
+        return http.JsonResponse({"success": True})
+    return http.JsonResponse({"success": False, "errors": form.errors.as_json()}, status=400)
+
+
 @teacher_or_superuser_required
 def student_submissions_view(request, assignment_id, student_id):
     """See the submissions of a student