feat: add support for Book activities and chapters in course sync

Author: allanhaggett

README.md

@@ -6,7 +6,7 @@ A Moodle local plugin that syncs course content from a GitHub repository. Conten
 
 - **One-click sync** from a GitHub repository into a Moodle course
 - **Automatic section creation** based on directory structure
-- **Page, Label, and URL activities** created from HTML files
+- **Page, Label, URL, and Book activities** created from HTML files and directories
 - **YAML front matter** support for controlling activity types
 - **Asset management** — CSS, images, and JS uploaded to Moodle file storage with automatic URL rewriting
 - **Incremental sync** — only changed files are updated (content hash tracking)
@@ -44,8 +44,13 @@ sections/
   01-introduction/
     section.yaml                   # Section title and summary (optional)
     01-welcome.html                # -> Page activity "Welcome"
-    02-overview.html               # -> Page activity "Overview"
-    03-notice.html                 # -> Label activity (with front matter)
+    02-course-handbook/            # -> Book activity "Course Handbook"
+      book.yaml                    # Optional: title, numbering, intro
+      01-getting-started.html      # -> Chapter 1
+      02-assessment-guide.html     # -> Chapter 2
+      03-resources.html            # -> Chapter 3
+    03-overview.html               # -> Page activity "Overview"
+    04-notice.html                 # -> Label activity (with front matter)
   02-module-one/
     section.yaml
     01-lesson.html
@@ -117,11 +122,68 @@ url: "https://docs.moodle.org"
 **Supported front matter fields:**
 | Field | Description |
 |-------|-------------|
-| `type` | Activity type: `page` (default), `label`, `url` |
+| `type` | Activity type: `page` (default), `label`, or `url`. Books are created from directories, not front matter. Other Moodle activity types (quiz, forum, assign, etc.) are not yet implemented. Unrecognized types are treated as `page`. |
 | `name` | Override the activity name (otherwise derived from filename) |
 | `url` | External URL (required for `type: url`) |
 | `visible` | `true` or `false` |
 
+### Book Activities
+
+A subdirectory inside a section directory becomes a **Book** activity. Each `.html` file in the subdirectory becomes a chapter, ordered by numeric prefix. This maps one directory to one Moodle book module.
+
+```
+sections/
+  01-introduction/
+    02-course-handbook/              # -> Book "Course Handbook"
+      book.yaml                      # Optional metadata
+      01-getting-started.html        # -> Chapter 1 "Getting Started"
+      02-assessment-guide.html       # -> Chapter 2 "Assessment Guide"
+      03-resources.html              # -> Chapter 3 "Resources"
+```
+
+#### book.yaml
+
+Optional. Sets book-level metadata:
+
+```yaml
+title: "Course Handbook"
+numbering: bullets
+intro: "<p>Reference handbook for this course.</p>"
+```
+
+| Field | Description |
+|-------|-------------|
+| `title` | Override the book name (otherwise derived from directory name) |
+| `numbering` | Chapter numbering style: `none`, `numbers` (default), `bullets`, or `indented` |
+| `intro` | HTML description shown on the book's intro page |
+
+#### Chapter Front Matter
+
+Chapter HTML files support YAML front matter for per-chapter settings:
+
+```html
+---
+title: "Getting Started Guide"
+subchapter: true
+---
+<h2>Welcome</h2>
+<p>This chapter covers...</p>
+```
+
+| Field | Description |
+|-------|-------------|
+| `title` | Override the chapter title (otherwise derived from filename) |
+| `subchapter` | `true` to make this a sub-chapter (indented under the previous chapter). The first chapter in a book cannot be a subchapter. |
+
+#### Sync Behavior for Books
+
+- **New book directory**: Creates the book activity and all chapters in one operation
+- **Modified chapter**: Only the changed chapter is updated (content hash tracking)
+- **New chapter file**: Added at the correct position based on filename ordering
+- **Removed chapter file**: The chapter is hidden (not deleted), matching the behavior for removed pages
+- **Modified book.yaml**: Updates book name, numbering, and intro without touching chapters
+- **Reordered chapters** (renamed with different numeric prefixes): Page numbers are updated even if content is unchanged
+
 ### Assets
 
 Files in the `assets/` directory are uploaded to Moodle's file storage. References in HTML are automatically rewritten:

classes/sync/course_builder.php

@@ -21,6 +21,7 @@
 require_once($CFG->dirroot . '/course/lib.php');
 require_once($CFG->dirroot . '/course/modlib.php');
 require_once($CFG->dirroot . '/lib/resourcelib.php');
+require_once($CFG->dirroot . '/mod/book/locallib.php');
 
 /**
  * Handles creating and updating Moodle course structure from repo data.
@@ -46,7 +47,7 @@ public function __construct(\stdClass $course) {
         $this->course = $course;
 
         // Cache module IDs for the types we support.
-        foreach (['page', 'label', 'url'] as $modname) {
+        foreach (['page', 'label', 'url', 'book'] as $modname) {
             $id = $DB->get_field('modules', 'id', ['name' => $modname]);
             if ($id) {
                 $this->moduleids[$modname] = (int) $id;
@@ -270,6 +271,177 @@ public function create_url(int $sectionnum, string $name, string $url, string $i
         return $result->coursemodule;
     }
 
+    /**
+     * Create a Book activity with chapters.
+     *
+     * @param int $sectionnum Section number
+     * @param string $name Book name
+     * @param array $chapters Ordered array of chapter data: ['title', 'content', 'subchapter', 'importsrc']
+     * @param array $bookmeta Optional book metadata from book.yaml (numbering, intro)
+     * @return int The course module ID (cmid)
+     */
+    public function create_book(int $sectionnum, string $name, array $chapters, array $bookmeta = []): int {
+        global $DB;
+
+        if (empty($this->moduleids['book'])) {
+            throw new \moodle_exception('syncfailed', 'local_githubsync', '', 'Book module not available');
+        }
+
+        // Map numbering string values to book constants.
+        $numberingmap = ['none' => 0, 'numbers' => 1, 'bullets' => 2, 'indented' => 3];
+        $numbering = 0;
+        if (!empty($bookmeta['numbering']) && isset($numberingmap[$bookmeta['numbering']])) {
+            $numbering = $numberingmap[$bookmeta['numbering']];
+        }
+
+        $moduleinfo = new \stdClass();
+        $moduleinfo->modulename = 'book';
+        $moduleinfo->module = $this->moduleids['book'];
+        $moduleinfo->name = !empty($bookmeta['title']) ? $bookmeta['title'] : $name;
+        $moduleinfo->section = $sectionnum;
+        $moduleinfo->visible = 1;
+        $moduleinfo->visibleoncoursepage = 1;
+
+        $moduleinfo->intro = purify_html($bookmeta['intro'] ?? '');
+        $moduleinfo->introformat = FORMAT_HTML;
+        $moduleinfo->numbering = $numbering;
+        $moduleinfo->navstyle = 1;
+        $moduleinfo->customtitles = 0;
+
+        $result = add_moduleinfo($moduleinfo, $this->course);
+        $cmid = $result->coursemodule;
+
+        // Get the book instance ID.
+        $cm = get_coursemodule_from_id('book', $cmid, 0, false, MUST_EXIST);
+        $bookid = $cm->instance;
+
+        // Insert chapters.
+        $pagenum = 0;
+        foreach ($chapters as $chapter) {
+            $pagenum++;
+            $rec = new \stdClass();
+            $rec->bookid = $bookid;
+            $rec->pagenum = $pagenum;
+            $rec->subchapter = ($pagenum === 1) ? 0 : (!empty($chapter['subchapter']) ? 1 : 0);
+            $rec->title = $chapter['title'];
+            $rec->content = purify_html($chapter['content']);
+            $rec->contentformat = FORMAT_HTML;
+            $rec->hidden = 0;
+            $rec->importsrc = $chapter['importsrc'] ?? '';
+            $rec->timecreated = time();
+            $rec->timemodified = time();
+            $DB->insert_record('book_chapters', $rec);
+        }
+
+        // Preload chapters to validate structure.
+        $book = $DB->get_record('book', ['id' => $bookid], '*', MUST_EXIST);
+        book_preload_chapters($book);
+
+        return $cmid;
+    }
+
+    /**
+     * Update book metadata (name, numbering, intro) from book.yaml.
+     *
+     * @param int $cmid Course module ID of the book
+     * @param array $bookmeta Parsed book.yaml data
+     */
+    public function update_book_metadata(int $cmid, array $bookmeta): void {
+        global $DB;
+
+        $cm = get_coursemodule_from_id('book', $cmid, 0, false, MUST_EXIST);
+        $book = $DB->get_record('book', ['id' => $cm->instance], '*', MUST_EXIST);
+
+        $numberingmap = ['none' => 0, 'numbers' => 1, 'bullets' => 2, 'indented' => 3];
+        $changed = false;
+
+        if (!empty($bookmeta['title']) && $bookmeta['title'] !== $book->name) {
+            $book->name = $bookmeta['title'];
+            $changed = true;
+        }
+        if (!empty($bookmeta['numbering']) && isset($numberingmap[$bookmeta['numbering']])) {
+            $newnumbering = $numberingmap[$bookmeta['numbering']];
+            if ($newnumbering !== (int) $book->numbering) {
+                $book->numbering = $newnumbering;
+                $changed = true;
+            }
+        }
+        if (isset($bookmeta['intro'])) {
+            $newintro = purify_html($bookmeta['intro']);
+            if ($newintro !== $book->intro) {
+                $book->intro = $newintro;
+                $book->introformat = FORMAT_HTML;
+                $changed = true;
+            }
+        }
+
+        if ($changed) {
+            $book->timemodified = time();
+            $DB->update_record('book', $book);
+            rebuild_course_cache($this->course->id, true);
+        }
+    }
+
+    /**
+     * Update an existing book chapter found by importsrc.
+     *
+     * @param int $bookid Book instance ID
+     * @param string $importsrc The repo path stored in importsrc
+     * @param string $title Chapter title
+     * @param string $content Chapter HTML content
+     * @param bool $subchapter Whether this is a subchapter
+     * @param int $pagenum New page number
+     * @return bool True if found and updated
+     */
+    public function update_book_chapter(int $bookid, string $importsrc, string $title,
+            string $content, bool $subchapter, int $pagenum): bool {
+        global $DB;
+
+        $chapter = $DB->get_record('book_chapters', ['bookid' => $bookid, 'importsrc' => $importsrc]);
+        if (!$chapter) {
+            return false;
+        }
+
+        $chapter->title = $title;
+        $chapter->content = purify_html($content);
+        $chapter->contentformat = FORMAT_HTML;
+        $chapter->subchapter = $subchapter ? 1 : 0;
+        $chapter->pagenum = $pagenum;
+        $chapter->hidden = 0;
+        $chapter->timemodified = time();
+        $DB->update_record('book_chapters', $chapter);
+
+        return true;
+    }
+
+    /**
+     * Create a new chapter in an existing book.
+     *
+     * @param int $bookid Book instance ID
+     * @param string $title Chapter title
+     * @param string $content Chapter HTML content
+     * @param bool $subchapter Whether this is a subchapter
+     * @param int $pagenum Page number for ordering
+     * @param string $importsrc Repo path for tracking
+     */
+    public function create_book_chapter(int $bookid, string $title, string $content,
+            bool $subchapter, int $pagenum, string $importsrc): void {
+        global $DB;
+
+        $rec = new \stdClass();
+        $rec->bookid = $bookid;
+        $rec->pagenum = $pagenum;
+        $rec->subchapter = $subchapter ? 1 : 0;
+        $rec->title = $title;
+        $rec->content = purify_html($content);
+        $rec->contentformat = FORMAT_HTML;
+        $rec->hidden = 0;
+        $rec->importsrc = $importsrc;
+        $rec->timecreated = time();
+        $rec->timemodified = time();
+        $DB->insert_record('book_chapters', $rec);
+    }
+
     /**
      * Create an activity based on front matter type.
      *