action-writer

name	action-writer
description	Create or update an Action in app/Actions following JournalOS conventions (validation, logging, queues, tests).

Action Writer

This Skill helps you add or update an Action in app/Actions using the project conventions.

When to use this Skill

Use this Skill when:

• Creating a new Action
• Updating an existing Action

Instructions

Quick start

• Pick the action name (verb-first) and its input/output types.
• Create the Action class and implement execute().
• Add or update unit tests in tests/Unit/Actions.
• Run the smallest relevant test(s), then composer journalos:unit.

Step 1: Choose the action name and scope

1. Actions represent a single user intent (example: LogHealth, CreateBook, ResetWorkData).
2. Keep inputs minimal and explicit. Use descriptive parameter names.
3. Decide whether the Action returns a model, a scalar, or nothing (void).

Step 2: Create the Action class

1. Use Artisan to create the class:

php artisan make:class Actions/ActionName --no-interaction

1. Use declare(strict_types=1); and the App\Actions namespace.
2. Default to final readonly class with constructor property promotion.
3. If the Action must store a result (ex: $this->book), keep it final but not readonly, and declare a private property for the result.
4. Always include explicit return types.

Step 3: Implement the action flow

1. Typical flow:
   • validate input
   • perform data changes
   • log user action
   • update last activity date
   • refresh content presence (when journal entry content changes)
2. Validate ownership with ModelNotFoundException when a user does not own a journal or entry.
3. Validate input with ValidationException::withMessages([...]) when values are invalid.
4. Sanitize user-provided text with TextSanitizer::plainText().
5. Use Eloquent models and relationships. Avoid DB::.
6. Queue background work on the low queue:

LogUserAction::dispatch(...)->onQueue('low');
UpdateUserLastActivityDate::dispatch($user)->onQueue('low');
CheckPresenceOfContentInJournalEntry::dispatch($entry)->onQueue('low');

1. If the Action mutates a journal entry module, reload the relationship before returning:

$this->entry->load('moduleHealth');

Step 4: Add tests

1. Create tests/Unit/Actions/ActionNameTest.php.
2. Use RefreshDatabase and Queue::fake().
3. Use factories with explicit foreign keys. Never use for() on factories.
4. Cover:
   • happy path
   • invalid input (throws ValidationException)
   • unauthorized access (throws ModelNotFoundException)
   • queued jobs on low queue

Step 5: Run tests and lint

1. Run the smallest relevant test file:

php artisan test tests/Unit/Actions/ActionNameTest.php

1. Run composer journalos:unit.
2. Run Pint:

vendor/bin/pint --dirty