npm - @datajaddah/course - Versions diffs - 0.0.2 - Mend

@datajaddah/course 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/preview-dist/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Datajaddah Course Preview</title>
+    <script type="module" crossorigin src="/assets/index-CavDNP3d.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CJUgarn8.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/scaffold/.agents/rules/general.md ADDED Viewed

@@ -0,0 +1,91 @@
+# General Rules
+## Mission
+- This repository exists to author one Datajaddah course.
+- Keep the repository focused on course content, course metadata, assets, and `.agents`.
+- Do not add application code, package manifests, build tooling, CI files, database files, or unrelated documentation.
+## Non-Goals
+- Do not create or maintain `course.json` in this repository.
+- Do not reintroduce legacy root files such as `AGENT.md` or `AI_AUTHORING.md`.
+- Do not invent lesson kinds beyond `slides`, `video`, `quiz`, `coding_exercise`, and `spreadsheet_lab`.
+- Do not add platform-only metadata that is not represented by the GitHub course contract.
+## Default Workflow
+1. Identify the smallest scope that satisfies the request:
+   - course metadata
+   - chapter or lesson structure
+   - slides v2
+   - video lesson
+   - quiz
+   - coding exercise
+   - spreadsheet lab
+2. Edit the minimum number of files needed.
+3. Preserve ordering, slugs, and folder layout unless the user explicitly asks to reorder or rename content.
+4. Keep learner-facing content in markdown bodies and supported frontmatter fields only.
+5. Validate with `npx @datajaddah/course validate .` before finishing.
+6. Use `npx @datajaddah/course preview .` when slide, video, quiz, or exercise rendering needs a visual check.
+## Repository Contract
+- The repository uses the markdown-first `repo_tree_v1` contract.
+- `course.md` is the root source of truth for course metadata and overview.
+- `chapters/NN-slug/chapter.md` stores chapter metadata and chapter summary.
+- `chapters/NN-slug/lessons/NN-slug/lesson.md` declares the lesson kind.
+- Each lesson has exactly one supported resource location:
+  - `slides/NN-slug.md`
+  - `video.md`
+  - `quiz/quiz.md` and `quiz/questions/NN-slug.md`
+  - `exercise/exercise.md`, `starter.*`, `solution.*`
+  - `spreadsheet/exercise.md`, `workbook.json`, `solution.json`, `checks.json`
+- Ordered folders and files must use contiguous `NN-slug` naming.
+## Platform Interpretation
+- Slides authored from GitHub become slides v2 content in the platform.
+- Slide markdown becomes HTML content; `@script` content becomes narration text.
+- Slides can use the markdown slide DSL for `@layout`, `@column`, reveal attrs such as `{delay=2 highlight=2}`, and image slots like `slot:diagram-name`.
+- Most explainer videos are produced later on the platform from slide decks plus narration audio.
+- In the repo, author those explainer videos as `slides` with strong `@script` content.
+- Slide audio, generated video, timing, and step markers are platform-owned and are not authored in this repo.
+- Use `video.md` only for a real standalone external video URL that already exists or was explicitly requested.
+- Never invent placeholder `video_url` values such as `example.com` or `replace-me`.
+- Quiz prompts and choice bodies render as HTML in the platform.
+- For quizzes, the learner-visible answer text comes from the choice body, not the choice title.
+- Use `feedback` and `correct_feedback` for explanations; keep choice bodies as the actual answer options.
+- A quiz becomes multi-select automatically when more than one choice is marked correct.
+- Coding exercises must keep `## Context` and `## Instructions` as separate sections in `exercise/exercise.md`.
+- Coding exercise `language` must be only `python` or `r`, and starter/solution files must match that language.
+- Spreadsheet labs use a Univerjs-powered spreadsheet in the platform; the learner edits `workbook.json` data live and checks are evaluated as a requirements checklist.
+- Spreadsheet lab exercises must keep `## Context` and `## Instructions` as separate sections in `spreadsheet/exercise.md`.
+## Content Quality
+- Prefer incremental edits over broad rewrites.
+- Keep course copy concise, explicit, and learner-facing.
+- Keep learner-facing material anchored to the requested course subject and the current lesson objective.
+- Make titles short enough to scan in course navigation.
+- Write slides for presentation, quizzes for assessment, and exercises for hands-on practice.
+- Keep slide text lighter than the spoken script; use reveal steps, columns, and planned image slots to structure the visual explanation.
+- Treat repository structure, filenames, `.agents`, validation commands, sync behavior, and platform mechanics as authoring infrastructure. Do not turn them into slides, quiz questions, video notes, or exercises unless the user explicitly asks for a course about Datajaddah authoring.
+- Avoid placeholders unless the user explicitly asks for scaffolding or examples.
+## Skills In This Repository
+- Use `.agents/skills/course-platform-overview` for commands, sync behavior, and platform model knowledge.
+- Use `.agents/skills/course-repo-contract` for structure, naming, and validation rules.
+- Use `.agents/skills/course-slides-v2` for slide lessons.
+- Use `.agents/skills/course-video-lessons` for video lessons.
+- Use `.agents/skills/course-quizzes` for quizzes.
+- Use `.agents/skills/course-coding-exercises` for coding exercises.
+- Use `.agents/skills/course-spreadsheet-labs` for spreadsheet labs.
+## Done Criteria
+- The repository still validates.
+- The changed lesson kind and file layout match the contract.
+- New content is placed in the correct ordered location.
+- No unrelated files were introduced.

package/scaffold/.agents/skills/course-coding-exercises/SKILL.md ADDED Viewed

@@ -0,0 +1,22 @@
+---
+name: course-coding-exercises
+description: Author Datajaddah coding exercise lessons in a GitHub course repository. Use this skill when creating or editing coding exercise prompts, language metadata, starter files, solution files, or exercise structure.
+---
+# Course Coding Exercises
+Use this skill when the request is about hands-on coding exercises in the GitHub course repo.
+## Workflow
+1. Read `references/coding-exercises.md`.
+2. Ensure `lesson.md` declares `kind: coding_exercise`.
+3. Keep the prompt in `exercise/exercise.md` with explicit `## Context` and `## Instructions` sections.
+4. Keep code in exactly one `starter.*` file and one `solution.*` file, using only Python or R.
+5. Validate with `npx @datajaddah/course validate .`.
+## Boundaries
+- Do not add hidden test files to the repo contract unless the platform contract is extended first.
+- Keep the learner prompt in markdown and code in code files.
+- Keep exercises aligned with the requested lesson topic, not repository mechanics or platform workflows.

package/scaffold/.agents/skills/course-coding-exercises/references/coding-exercises.md ADDED Viewed

@@ -0,0 +1,111 @@
+# Coding Exercises
+## Files
+Inside a coding exercise lesson:
+```text
+lesson.md
+exercise/
+  exercise.md
+  starter.py
+  solution.py
+```
+`lesson.md` must contain:
+```md
+---
+kind: coding_exercise
+title: "Lesson Title"
+---
+Optional lesson summary.
+```
+`exercise/exercise.md` must contain:
+```md
+---
+title: "Exercise Title"
+language: "python"
+---
+## Context
+Brief problem setup in markdown.
+## Instructions
+Exact task in markdown.
+```
+## Required Constraints
+- `language` is required.
+- `language` must be `python` or `r`.
+- `exercise.md` must contain `## Context` followed by `## Instructions`.
+- The exercise directory must contain exactly one `starter.*` file.
+- The exercise directory must contain exactly one `solution.*` file.
+- `starter.*` and `solution.*` must use the same extension.
+## Supported Language To Extension Mapping
+- `python` -> `.py`
+- `r` -> `.r`
+## Platform Behavior
+- The repo contract stores coding exercise context and instructions in explicit markdown sections.
+- The platform stores those sections in separate `context_description` and `instructions` fields.
+- Student code is executed through Judge0 and the platform can attach AI-generated feedback to submissions.
+- The repo contract does not currently include test fixtures or hidden grader files.
+## Writing Guidance
+- State the task in concrete, verifiable terms.
+- Keep the function signature, entrypoint, or expected output explicit.
+- Make the starter code compile or run in the declared language whenever practical.
+- Keep the solution file correct, minimal, and aligned with the prompt.
+- Prefer exercises that can be checked from code behavior, not subjective style.
+- Keep the exercise on the requested lesson topic. Use repo-contract details only for file placement and validation.
+## Good Prompt Structure
+1. `## Context`
+2. `## Instructions`
+3. Constraints
+4. Edge cases
+5. What file the learner should edit
+## Example
+```md
+---
+title: "Sum Values"
+language: "python"
+---
+## Context
+You are given a helper function that should add all values in a list.
+## Instructions
+Implement `sum_values` in `starter.py`.
+- Keep the function signature unchanged.
+- Return `0` for an empty list.
+- Compare your answer with `solution.py` after you finish.
+```
+Starter example:
+```py
+def sum_values(values: list[int]) -> int:
+    return 0
+```
+Solution example:
+```py
+def sum_values(values: list[int]) -> int:
+    return sum(values)
+```

package/scaffold/.agents/skills/course-platform-overview/SKILL.md ADDED Viewed

@@ -0,0 +1,36 @@
+---
+name: course-platform-overview
+description: Datajaddah course platform overview for markdown-first GitHub course repositories. Use this skill when creating or editing a course repo, when a user asks how the platform interprets course files, what commands to run, how GitHub sync works, or how lessons map to platform resources.
+---
+# Course Platform Overview
+Use this skill before making broad course-authoring changes or when the request depends on platform behavior rather than a single resource type.
+## What this skill covers
+- The markdown-first GitHub course contract
+- The supported lesson/resource types
+- Platform-owned versus repo-authored data
+- Core authoring commands
+- GitHub sync behavior and current limitations
+## Workflow
+1. Read `references/platform-overview.md`.
+2. If the task is about repository shape, also use `../course-repo-contract/SKILL.md`.
+3. If the task is resource-specific, use the matching skill:
+   - `../course-slides-v2/SKILL.md`
+   - `../course-video-lessons/SKILL.md`
+   - `../course-quizzes/SKILL.md`
+   - `../course-coding-exercises/SKILL.md`
+4. Validate with `npx @datajaddah/course validate .`.
+## Output Expectations
+- Keep course repos markdown-first and course-only.
+- Do not invent platform fields that are not represented in the repository contract.
+- Use repository and platform details to shape files, not to choose learner-facing lesson topics.
+- Do not copy `course.md`, `lesson.md`, `.agents`, validation commands, or sync behavior into course material unless the requested course is about Datajaddah authoring.
+- When the user wants explainer video content and no external URL exists yet, author `slides` plus `@script` instead of a standalone `video.md`.
+- Keep implementation notes inside `.agents`, not in learner-facing files.

package/scaffold/.agents/skills/course-platform-overview/references/platform-overview.md ADDED Viewed

@@ -0,0 +1,105 @@
+# Platform Overview
+## Purpose
+This repository format is the GitHub authoring contract for Datajaddah courses. The repository is not an application project. It is a structured content tree that the platform parses and syncs.
+## Scope Boundary
+- Use this reference to decide file placement, commands, and platform-owned data.
+- Treat these mechanics as authoring infrastructure, not learner curriculum.
+- Do not turn repository or platform details into course content unless the course itself is about Datajaddah authoring.
+## Core Commands
+- Initialize a new course repo: `npx @datajaddah/course init ./my-course`
+- Validate a repo: `npx @datajaddah/course validate .`
+- Preview a repo locally: `npx @datajaddah/course preview .`
+Use `validate` as the default final check. Use `preview` when the request changes rendered learner content.
+## Supported Lesson Types
+- `slides`
+- `video`
+- `quiz`
+- `coding_exercise`
+Every lesson maps to exactly one of those resource types.
+## How The Platform Interprets Repo Content
+### Course
+- `course.md` becomes course title, description, duration, thumbnail, and tags.
+### Chapters
+- Each ordered chapter folder becomes one chapter in the platform.
+- `chapter.md` body becomes the chapter description.
+### Lessons
+- Each ordered lesson folder becomes one lesson in the platform.
+- `lesson.md` declares the kind.
+- The lesson folder title and order drive course navigation.
+### Slides
+- GitHub-authored slides become slides v2 content.
+- Slide markdown is rendered to HTML.
+- `@script` becomes slide narration text.
+- Most course explainer videos are later rendered on the platform from slide content plus narration audio.
+- In the repo, author those future videos as render-ready slides with strong `@script` blocks.
+- Audio blobs, generated video, delay metadata, and step markers are not authored in the repo contract.
+### Video Lessons
+- `video.md` is for standalone externally hosted videos, not the default explainer flow.
+- `video.md` must provide a real external `video_url`.
+- The platform stores that URL and renders it as the lesson video source.
+- This contract does not represent uploaded binaries or slide-generated videos.
+- Do not invent placeholder URLs such as `example.com` or `replace-me`.
+### Quizzes
+- Quiz prompts and choices are authored in markdown and rendered to HTML.
+- A question is treated as multi-select when more than one choice is marked correct.
+- The repository contract stores content and correctness, not learner attempts.
+### Coding Exercises
+- The repo stores coding exercise `## Context` and `## Instructions` sections plus starter and solution files.
+- The platform stores those sections separately as `context_description` and `instructions`.
+- Coding exercise `language` is restricted to `python` or `r`.
+## GitHub Sync Status
+- Pull from GitHub: supported
+- Push to GitHub: supported for non-destructive updates on the managed sync branch
+- Reorders, moves, and deletes: still blocked in the managed sync flow
+## Platform-Owned Versus Repo-Owned
+### Repo-Owned
+- Course, chapter, lesson titles and summaries
+- Slide markdown and narration script
+- Video title, URL, and notes
+- Quiz prompt, choice bodies, correctness, and feedback
+- Coding exercise context, instructions, language, starter code, and solution code
+### Platform-Owned
+- Slide audio blobs
+- Slide timing and step markers
+- Generated slide videos
+- Quiz attempts and learner progress
+- Coding exercise submissions, execution output, and AI-generated feedback
+## Operational Guardrails
+- Stay inside the documented lesson/resource formats.
+- Avoid broad rewrites when the user asked for a small change.
+- Keep new files ordered and contiguous.
+- Run `npx @datajaddah/course validate .` after structural edits.

package/scaffold/.agents/skills/course-quizzes/SKILL.md ADDED Viewed

@@ -0,0 +1,23 @@
+---
+name: course-quizzes
+description: Author Datajaddah quiz lessons in a GitHub course repository. Use this skill when creating or editing quiz lessons, quiz descriptions, quiz questions, choice blocks, feedback, or correctness rules.
+---
+# Course Quizzes
+Use this skill when the request is about assessments in the GitHub course repo.
+## Workflow
+1. Read `references/quizzes.md`.
+2. Ensure `lesson.md` declares `kind: quiz`.
+3. Keep quiz metadata in `quiz/quiz.md`.
+4. Keep each question in its own ordered markdown file under `quiz/questions/`.
+5. Validate with `npx @datajaddah/course validate .`.
+## Boundaries
+- Do not split one question across multiple files.
+- Do not invent quiz metadata outside the documented frontmatter and choice-block format.
+- Keep every question aligned with the lesson topic and learning objective.
+- Treat repo or platform examples as format references only. Do not quiz learners on `course.md`, `lesson.md`, `.agents`, validation commands, or sync behavior unless the course is explicitly about Datajaddah authoring.

package/scaffold/.agents/skills/course-quizzes/references/quizzes.md ADDED Viewed

@@ -0,0 +1,121 @@
+# Quizzes
+## Files
+Inside a quiz lesson:
+```text
+lesson.md
+quiz/
+  quiz.md
+  questions/
+    01-first-question.md
+    02-second-question.md
+```
+`lesson.md` must contain:
+```md
+---
+kind: quiz
+title: "Lesson Title"
+---
+Optional lesson summary.
+```
+`quiz/quiz.md` contains:
+- optional `title` frontmatter
+- markdown body for quiz description
+## Question File Format
+Each question file supports:
+- optional `title`
+- optional `correct_feedback`
+- optional `randomize_choices: true|false`
+The question prompt is the markdown before the first `@choice` block.
+Each choice must use this structure:
+```text
+@choice
+title: Choice label
+correct: true
+feedback: Optional feedback
+Choice body markdown
+@endchoice
+```
+The platform imports the choice body as the learner-visible answer text.
+Treat `title` as optional metadata or a plain-text fallback only.
+Do not put the answer in `title` and an explanation in the body.
+Put the actual answer in the body, and put explanations in `feedback` or `correct_feedback`.
+## Validation Rules
+- Every question must include at least one `@choice` block.
+- Every question must have at least one correct choice.
+- Choice metadata must appear before the blank line in the block.
+- All content after the first `@choice` must stay inside choice blocks.
+- `randomize_choices` must be a boolean when present.
+## Platform Behavior
+- Question prompt markdown becomes HTML.
+- Choice body markdown becomes HTML.
+- `correct_feedback` becomes the success message for a correct answer.
+- A question becomes multi-select automatically when more than one choice is correct.
+- Learner answers are checked against the exact set of correct choices.
+## Writing Guidance
+- Ask one clear thing per question.
+- Use distractors that are plausible but clearly wrong for someone who understands the concept.
+- Keep feedback corrective and specific.
+- Keep each choice body short and learner-facing. Use feedback for explanations, not the visible answer body.
+- Avoid trick questions unless the user explicitly wants them.
+- Prefer concrete behaviors from the lesson topic over vague theory.
+- When the request is topical, keep every question and distractor inside that topic.
+- Use repo or platform mechanics only when the course itself is about Datajaddah authoring.
+## Multiline Feedback
+Use YAML block syntax when the feedback needs multiple lines:
+```text
+feedback: |
+  First line.
+  Second line with more detail.
+```
+## Example
+This example demonstrates the file shape only. Replace the prompt and choices with the actual lesson concept instead of copying the sample wording into the course.
+```md
+---
+title: "Key Concept Check"
+correct_feedback: "Correct. This option matches the concept taught in the lesson."
+randomize_choices: false
+---
+Which answer best matches the concept taught in this lesson?
+@choice
+title: The statement supported by the lesson content
+correct: true
+The statement supported by the lesson content
+@endchoice
+@choice
+title: A plausible misconception
+correct: false
+feedback: Use a near-miss from the same topic so the learner feedback can correct the misunderstanding.
+A plausible misconception
+@endchoice
+```

package/scaffold/.agents/skills/course-repo-contract/SKILL.md ADDED Viewed

@@ -0,0 +1,24 @@
+---
+name: course-repo-contract
+description: Repository structure and validation rules for Datajaddah GitHub course repositories. Use this skill when creating or reorganizing course.md, chapters, lessons, resource folders, filenames, frontmatter, or when fixing validation errors in a course repo.
+---
+# Course Repo Contract
+Use this skill when the task is about repository shape, filenames, frontmatter, or validation.
+## Workflow
+1. Read `references/repo-contract.md`.
+2. Edit the smallest structural surface that satisfies the request.
+3. Preserve contiguous ordering unless the user explicitly asks to reorder.
+4. Validate with `npx @datajaddah/course validate .`.
+## Scope
+- `course.md`
+- `chapters/`
+- lesson folders and resource locations
+- root `.agents` guidance files
+For resource-specific authoring (slides, video, quizzes, coding exercises, spreadsheet labs), use the matching resource skill after applying the contract rules.