Initial plugin scaffold: lesson scheduling WordPress plugin

- Custom DB tables for availability slots and lesson bookings
- Instructor (wp-admin) and student (front-end) roles with custom capabilities
- REST API under us-scheduler/v1 for availability CRUD and booking
- [us_booking] and [us_student_login] shortcodes for student front end
- PHPUnit + Brain\Monkey unit test suite (29 tests)
- Gitea Actions CI: lint, PHPStan, tests on PHP 8.1/8.2/8.3, no-debug check
- Feature docs under docs/features/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/Unit/Data/AvailabilityRepositoryTest.php

@@ -0,0 +1,149 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Data;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Data\AvailabilityRepository;
+use Unsupervised\Schedular\Model\AvailabilitySlot;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class AvailabilityRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private AvailabilityRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db       = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo     = new AvailabilityRepository($this->db);
+    }
+
+    public function testInsertCallsWpdbInsertAndReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-04-01 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_availability',
+                Mockery::on(static function (array $data): bool {
+                    return $data['instructor_id'] === 5
+                        && $data['start_dt'] === '2026-04-01 09:00:00'
+                        && $data['is_booked'] === 0;
+                }),
+                ['%d', '%s', '%s', '%d', '%s']
+            );
+
+        $this->db->insert_id = 42;
+
+        $slot   = new AvailabilitySlot(5, '2026-04-01 09:00:00', '2026-04-01 10:00:00');
+        $result = $this->repo->insert($slot);
+
+        self::assertSame(42, $result);
+    }
+
+    public function testFindByIdReturnsNullWhenNotFound(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->andReturn('SELECT * FROM wp_us_availability WHERE id = 99');
+
+        $this->db->shouldReceive('get_row')
+            ->once()
+            ->andReturn(null);
+
+        $result = $this->repo->findById(99);
+
+        self::assertNull($result);
+    }
+
+    public function testFindByIdReturnsSlotWhenFound(): void
+    {
+        $row = (object) [
+            'id'            => '10',
+            'instructor_id' => '5',
+            'start_dt'      => '2026-04-01 09:00:00',
+            'end_dt'        => '2026-04-01 10:00:00',
+            'is_booked'     => '0',
+        ];
+
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn($row);
+
+        $slot = $this->repo->findById(10);
+
+        self::assertInstanceOf(AvailabilitySlot::class, $slot);
+        self::assertSame(10, $slot->id);
+        self::assertSame(5, $slot->instructorId);
+    }
+
+    public function testMarkBookedUpdatesRecord(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with('wp_us_availability', ['is_booked' => 1], ['id' => 7], ['%d'], ['%d'])
+            ->andReturn(1);
+
+        $result = $this->repo->markBooked(7);
+
+        self::assertTrue($result);
+    }
+
+    public function testDeleteReturnsFalseWhenRowNotDeleted(): void
+    {
+        $this->db->shouldReceive('delete')
+            ->once()
+            ->with('wp_us_availability', ['id' => 1, 'is_booked' => 0], ['%d', '%d'])
+            ->andReturn(0);
+
+        self::assertFalse($this->repo->delete(1));
+    }
+
+    public function testFindAvailableWithNoFiltersUsesNoParams(): void
+    {
+        $this->db->shouldReceive('get_results')
+            ->once()
+            ->with(Mockery::pattern('/WHERE is_booked = 0/'))
+            ->andReturn([]);
+
+        $result = $this->repo->findAvailable();
+
+        self::assertSame([], $result);
+    }
+
+    public function testFindAvailableWithInstructorFilterPreparesQuery(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/instructor_id = %d/'), Mockery::any())
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([]);
+
+        $this->repo->findAvailable(instructorId: 3);
+    }
+
+    public function testFindByInstructorReturnsSlots(): void
+    {
+        $row = (object) [
+            'id'            => '5',
+            'instructor_id' => '3',
+            'start_dt'      => '2026-04-01 09:00:00',
+            'end_dt'        => '2026-04-01 10:00:00',
+            'is_booked'     => '0',
+        ];
+
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_results')->andReturn([$row]);
+
+        $slots = $this->repo->findByInstructor(3);
+
+        self::assertCount(1, $slots);
+        self::assertInstanceOf(AvailabilitySlot::class, $slots[0]);
+    }
+}

tests/Unit/Data/BookingRepositoryTest.php

@@ -0,0 +1,126 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Data;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Data\BookingRepository;
+use Unsupervised\Schedular\Model\Lesson;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class BookingRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private BookingRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new BookingRepository($this->db);
+    }
+
+    public function testInsertCallsWpdbInsertAndReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-04-01 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_lessons',
+                Mockery::on(static function (array $data): bool {
+                    return $data['slot_id'] === 10
+                        && $data['student_id'] === 5
+                        && $data['status'] === Lesson::STATUS_PENDING;
+                }),
+                ['%d', '%d', '%d', '%s', '%s', '%s']
+            );
+
+        $this->db->insert_id = 77;
+
+        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3);
+        $result = $this->repo->insert($lesson);
+
+        self::assertSame(77, $result);
+    }
+
+    public function testFindByIdReturnsNullWhenNotFound(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn(null);
+
+        self::assertNull($this->repo->findById(99));
+    }
+
+    public function testFindByIdReturnsLesson(): void
+    {
+        $row = (object) [
+            'id'            => '15',
+            'slot_id'       => '10',
+            'student_id'    => '5',
+            'instructor_id' => '3',
+            'status'        => 'pending',
+            'notes'         => null,
+        ];
+
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn($row);
+
+        $lesson = $this->repo->findById(15);
+
+        self::assertInstanceOf(Lesson::class, $lesson);
+        self::assertSame(15, $lesson->id);
+    }
+
+    public function testUpdateStatusReturnsFalseForInvalidStatus(): void
+    {
+        $result = $this->repo->updateStatus(1, 'invalid');
+        self::assertFalse($result);
+    }
+
+    public function testUpdateStatusCallsWpdbUpdate(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with(
+                'wp_us_lessons',
+                ['status' => Lesson::STATUS_CONFIRMED],
+                ['id' => 1],
+                ['%s'],
+                ['%d']
+            )
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->updateStatus(1, Lesson::STATUS_CONFIRMED));
+    }
+
+    public function testUpdateStatusReturnsFalseWhenDbFails(): void
+    {
+        $this->db->shouldReceive('update')->andReturn(0);
+
+        self::assertFalse($this->repo->updateStatus(1, Lesson::STATUS_CONFIRMED));
+    }
+
+    public function testFindByStudentReturnsLessons(): void
+    {
+        $row = (object) [
+            'id'            => '1',
+            'slot_id'       => '2',
+            'student_id'    => '5',
+            'instructor_id' => '3',
+            'status'        => 'pending',
+            'notes'         => null,
+        ];
+
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_results')->andReturn([$row]);
+
+        $lessons = $this->repo->findByStudent(5);
+
+        self::assertCount(1, $lessons);
+        self::assertInstanceOf(Lesson::class, $lessons[0]);
+    }
+}

tests/Unit/Model/AvailabilitySlotTest.php

@@ -0,0 +1,68 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Model;
+
+use Unsupervised\Schedular\Model\AvailabilitySlot;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class AvailabilitySlotTest extends TestCase
+{
+    public function testConstructorAndProperties(): void
+    {
+        $slot = new AvailabilitySlot(
+            instructorId: 5,
+            startDt:      '2026-04-01 09:00:00',
+            endDt:        '2026-04-01 10:00:00',
+            isBooked:     false,
+            id:           42,
+        );
+
+        self::assertSame(5, $slot->instructorId);
+        self::assertSame('2026-04-01 09:00:00', $slot->startDt);
+        self::assertSame('2026-04-01 10:00:00', $slot->endDt);
+        self::assertFalse($slot->isBooked);
+        self::assertSame(42, $slot->id);
+    }
+
+    public function testFromRowMapsCorrectly(): void
+    {
+        $row = (object) [
+            'id'            => '7',
+            'instructor_id' => '3',
+            'start_dt'      => '2026-05-10 14:00:00',
+            'end_dt'        => '2026-05-10 15:00:00',
+            'is_booked'     => '1',
+        ];
+
+        $slot = AvailabilitySlot::fromRow($row);
+
+        self::assertSame(7, $slot->id);
+        self::assertSame(3, $slot->instructorId);
+        self::assertTrue($slot->isBooked);
+    }
+
+    public function testToArrayContainsExpectedKeys(): void
+    {
+        $slot = new AvailabilitySlot(1, '2026-04-01 09:00:00', '2026-04-01 10:00:00', false, 10);
+        $arr  = $slot->toArray();
+
+        self::assertArrayHasKey('id', $arr);
+        self::assertArrayHasKey('instructor_id', $arr);
+        self::assertArrayHasKey('start_dt', $arr);
+        self::assertArrayHasKey('end_dt', $arr);
+        self::assertArrayHasKey('is_booked', $arr);
+    }
+
+    public function testDefaultIsBookedIsFalse(): void
+    {
+        $slot = new AvailabilitySlot(1, '2026-04-01 09:00:00', '2026-04-01 10:00:00');
+        self::assertFalse($slot->isBooked);
+    }
+
+    public function testDefaultIdIsNull(): void
+    {
+        $slot = new AvailabilitySlot(1, '2026-04-01 09:00:00', '2026-04-01 10:00:00');
+        self::assertNull($slot->id);
+    }
+}

tests/Unit/Model/LessonTest.php

@@ -0,0 +1,68 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Model;
+
+use Unsupervised\Schedular\Model\Lesson;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class LessonTest extends TestCase
+{
+    public function testStatusConstants(): void
+    {
+        self::assertSame('pending', Lesson::STATUS_PENDING);
+        self::assertSame('confirmed', Lesson::STATUS_CONFIRMED);
+        self::assertSame('cancelled', Lesson::STATUS_CANCELLED);
+    }
+
+    public function testValidStatusesContainsAllThree(): void
+    {
+        self::assertContains(Lesson::STATUS_PENDING, Lesson::VALID_STATUSES);
+        self::assertContains(Lesson::STATUS_CONFIRMED, Lesson::VALID_STATUSES);
+        self::assertContains(Lesson::STATUS_CANCELLED, Lesson::VALID_STATUSES);
+        self::assertCount(3, Lesson::VALID_STATUSES);
+    }
+
+    public function testConstructorDefaults(): void
+    {
+        $lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3);
+
+        self::assertSame(Lesson::STATUS_PENDING, $lesson->status);
+        self::assertNull($lesson->notes);
+        self::assertNull($lesson->id);
+    }
+
+    public function testFromRowMapsCorrectly(): void
+    {
+        $row = (object) [
+            'id'            => '99',
+            'slot_id'       => '10',
+            'student_id'    => '20',
+            'instructor_id' => '30',
+            'status'        => 'confirmed',
+            'notes'         => 'Bring your guitar.',
+        ];
+
+        $lesson = Lesson::fromRow($row);
+
+        self::assertSame(99, $lesson->id);
+        self::assertSame(10, $lesson->slotId);
+        self::assertSame(20, $lesson->studentId);
+        self::assertSame(30, $lesson->instructorId);
+        self::assertSame('confirmed', $lesson->status);
+        self::assertSame('Bring your guitar.', $lesson->notes);
+    }
+
+    public function testToArrayContainsExpectedKeys(): void
+    {
+        $lesson = new Lesson(1, 2, 3, Lesson::STATUS_PENDING, 'Note', 5);
+        $arr    = $lesson->toArray();
+
+        self::assertArrayHasKey('id', $arr);
+        self::assertArrayHasKey('slot_id', $arr);
+        self::assertArrayHasKey('student_id', $arr);
+        self::assertArrayHasKey('instructor_id', $arr);
+        self::assertArrayHasKey('status', $arr);
+        self::assertArrayHasKey('notes', $arr);
+    }
+}

tests/Unit/Roles/RoleManagerTest.php

@@ -0,0 +1,70 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Roles;
+
+use Brain\Monkey\Functions;
+use Unsupervised\Schedular\Roles\RoleManager;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class RoleManagerTest extends TestCase
+{
+    public function testRegisterAddsInitHook(): void
+    {
+        Functions\expect('add_action')
+            ->once()
+            ->with('init', \Mockery::any());
+
+        (new RoleManager())->register();
+    }
+
+    public function testCreateRolesSkipsExistingRoles(): void
+    {
+        Functions\when('get_role')->alias(static fn() => new \stdClass());
+        Functions\expect('add_role')->never();
+
+        (new RoleManager())->createRoles();
+    }
+
+    public function testCreateRolesAddsInstructorRoleWithCorrectCaps(): void
+    {
+        Functions\when('get_role')->alias(static function (string $role): ?object {
+            return $role === RoleManager::INSTRUCTOR ? null : new \stdClass();
+        });
+
+        Functions\expect('add_role')
+            ->once()
+            ->with(
+                RoleManager::INSTRUCTOR,
+                \Mockery::any(),
+                \Mockery::on(static function (array $caps): bool {
+                    return ($caps['read'] ?? false) === true
+                        && ($caps[RoleManager::CAP_MANAGE_AVAILABILITY] ?? false) === true
+                        && ($caps[RoleManager::CAP_VIEW_LESSONS] ?? false) === true;
+                })
+            );
+
+        (new RoleManager())->createRoles();
+    }
+
+    public function testCreateRolesAddsStudentRoleWithCorrectCaps(): void
+    {
+        Functions\when('get_role')->alias(static function (string $role): ?object {
+            return $role === RoleManager::STUDENT ? null : new \stdClass();
+        });
+
+        Functions\expect('add_role')
+            ->once()
+            ->with(
+                RoleManager::STUDENT,
+                \Mockery::any(),
+                \Mockery::on(static function (array $caps): bool {
+                    return ($caps['read'] ?? false) === true
+                        && ($caps[RoleManager::CAP_BOOK_LESSON] ?? false) === true
+                        && ($caps[RoleManager::CAP_VIEW_LESSONS] ?? false) === true;
+                })
+            );
+
+        (new RoleManager())->createRoles();
+    }
+}

tests/Unit/TestCase.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit;
+
+use Brain\Monkey;
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use PHPUnit\Framework\TestCase as BaseTestCase;
+
+abstract class TestCase extends BaseTestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Monkey\setUp();
+        Monkey\Functions\stubTranslationFunctions();
+        Monkey\Functions\stubEscapeFunctions();
+    }
+
+    protected function tearDown(): void
+    {
+        Monkey\tearDown();
+        parent::tearDown();
+    }
+}

tests/bootstrap.php

@@ -0,0 +1,15 @@
+<?php
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/vendor/autoload.php';
+
+// Minimal WordPress constants required by plugin code under test.
+if (! defined('ABSPATH')) {
+    define('ABSPATH', sys_get_temp_dir() . '/wordpress/');
+}
+
+define('WPINC', 'wp-includes');
+define('USC_VERSION', '1.0.0');
+define('USC_PLUGIN_FILE', dirname(__DIR__) . '/unsupervised-schedular.php');
+define('USC_PLUGIN_DIR', dirname(__DIR__) . '/');
+define('USC_PLUGIN_URL', 'http://example.com/wp-content/plugins/unsupervised-schedular/');