@datajaddah/course 0.0.2

package/README.md

@@ -0,0 +1,31 @@
+# @datajaddah/course
+
+CLI for authoring, validating, and previewing Datajaddah courses from GitHub repositories.
+
+## Install
+
+```bash
+npm install @datajaddah/course
+```
+
+## Commands
+
+### `datajaddah-course init [path] [--title "Title"] [--force]`
+
+Scaffold a new course repository with example lessons (slides, quiz, coding exercise, spreadsheet lab).
+
+### `datajaddah-course validate [path] [--json]`
+
+Validate a course repository against the `repo_tree_v1` contract. Reports structural errors, missing files, and invalid frontmatter.
+
+### `datajaddah-course preview [path] [--port 4310] [--host 127.0.0.1]`
+
+Start a local preview server that renders all course content in a browser. Refreshes from disk on each page load.
+
+## Supported Lesson Kinds
+
+- **slides** — Markdown slides with narration scripts, layouts, and image slots
+- **video** — External video URL with notes
+- **quiz** — Multiple-choice questions with feedback
+- **coding_exercise** — Python or R exercises with starter and solution code
+- **spreadsheet_lab** — Univerjs-powered spreadsheet exercises with checks

package/bin/datajaddah-course.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { initCourseRepository } from "../lib/init.js";
+import { startPreviewServer } from "../lib/preview.js";
+import {
+  RepoContractError,
+  buildValidationSummary,
+  parseCourseRepository,
+} from "../lib/repo-contract.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(path.join(__dirname, "../package.json"), "utf8"));
+  return pkg.version;
+}
+
+function printUsage() {
+  console.error("Usage:");
+  console.error("  datajaddah-course validate [path] [--json]");
+  console.error("  datajaddah-course init [path] [--title \"Course Title\"] [--force]");
+  console.error("  datajaddah-course preview [path] [--host 127.0.0.1] [--port 4310]");
+}
+
+function printValidateHelp() {
+  console.error("Usage: datajaddah-course validate [path] [--json]");
+  console.error("");
+  console.error("Validate a course repository against the repo_tree_v1 contract.");
+  console.error("");
+  console.error("Options:");
+  console.error("  [path]    Path to the course repository (default: current directory)");
+  console.error("  --json    Output validation result as JSON");
+}
+
+function printInitHelp() {
+  console.error("Usage: datajaddah-course init [path] [--title \"Course Title\"] [--force]");
+  console.error("");
+  console.error("Initialize a new course scaffold.");
+  console.error("");
+  console.error("Options:");
+  console.error("  [path]              Target directory (default: current directory)");
+  console.error("  --title <title>     Course title (default: derived from directory name)");
+  console.error("  --force             Overwrite existing files");
+}
+
+function printPreviewHelp() {
+  console.error("Usage: datajaddah-course preview [path] [--host 127.0.0.1] [--port 4310] [--dev]");
+  console.error("");
+  console.error("Start a local preview server for the course.");
+  console.error("");
+  console.error("Options:");
+  console.error("  [path]           Path to the course repository (default: current directory)");
+  console.error("  --host <host>    Bind address (default: 127.0.0.1)");
+  console.error("  --port <port>    Port number (default: 4310)");
+  console.error("  --dev            Enable Vite HMR for preview UI development");
+}
+
+function parseValidateArgs(args) {
+  const cwd = process.cwd();
+  const normalizedArgs = [];
+  let positionalOnly = false;
+
+  for (const arg of args) {
+    if (!positionalOnly && arg === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    normalizedArgs.push(arg);
+  }
+
+  let targetArg = ".";
+  let json = false;
+  let seenPath = false;
+
+  for (const arg of normalizedArgs) {
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (!seenPath) {
+      targetArg = arg;
+      seenPath = true;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  return {
+    rootPath: path.resolve(cwd, targetArg),
+    json,
+  };
+}
+
+function printValidationSummary(summary) {
+  console.log("Repository contract valid.");
+  console.log(`Path: ${summary.path}`);
+  console.log(`Contract: ${summary.contract}`);
+  if (summary.courseTitle) {
+    console.log(`Course: ${summary.courseTitle}`);
+  }
+  console.log(`Chapters: ${summary.chapterCount}`);
+  console.log(`Lessons: ${summary.lessonCount}`);
+  console.log(
+    "Resources: " +
+      `slides=${summary.resourceCounts.slides}, ` +
+      `video=${summary.resourceCounts.video}, ` +
+      `quiz=${summary.resourceCounts.quiz}, ` +
+      `coding_exercise=${summary.resourceCounts.coding_exercise}, ` +
+      `spreadsheet_lab=${summary.resourceCounts.spreadsheet_lab}`
+  );
+  if (summary.warnings.length > 0) {
+    console.log("Warnings:");
+    for (const warning of summary.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+}
+
+function runValidation(args) {
+  let options;
+  try {
+    options = parseValidateArgs(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+
+  try {
+    const parsedRepo = parseCourseRepository(options.rootPath);
+    const summary = buildValidationSummary(options.rootPath, parsedRepo);
+    if (options.json) {
+      console.log(JSON.stringify(summary));
+    } else {
+      printValidationSummary(summary);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof RepoContractError) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            ok: false,
+            path: options.rootPath,
+            error: {
+              path: error.path,
+              line: error.line,
+              message: error.message,
+            },
+          })
+        );
+      } else {
+        console.error("Repository contract invalid.");
+        console.error(`${error.path}:${error.line}: ${error.message}`);
+      }
+      return 1;
+    }
+    throw error;
+  }
+}
+
+function runValidate(args) {
+  process.exit(runValidation(args));
+}
+
+function runInit(args) {
+  let created;
+  try {
+    created = initCourseRepository(args, process.cwd());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+
+  console.error(`Initialized Datajaddah course scaffold at ${created.targetPath}`);
+  console.error(`Course title: ${created.title}`);
+  console.error(`Files written: ${created.writtenFiles.length}`);
+
+  const validationStatus = runValidation([created.targetPath]);
+  process.exit(validationStatus);
+}
+
+async function runPreview(args) {
+  try {
+    await startPreviewServer(args, process.cwd());
+  } catch (error) {
+    if (error instanceof RepoContractError) {
+      console.error("Repository contract invalid.");
+      console.error(`${error.path}:${error.line}: ${error.message}`);
+      process.exit(1);
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+const [command, ...args] = process.argv.slice(2);
+
+if (command === "--version" || command === "-v") {
+  console.log(getVersion());
+  process.exit(0);
+}
+
+if (!command || command === "--help" || command === "-h") {
+  printUsage();
+  process.exit(command ? 0 : 1);
+}
+
+if (command === "validate") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printValidateHelp();
+    process.exit(0);
+  }
+  runValidate(args);
+} else if (command === "init") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printInitHelp();
+    process.exit(0);
+  }
+  runInit(args);
+} else if (command === "preview") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printPreviewHelp();
+    process.exit(0);
+  }
+  await runPreview(args);
+} else {
+  console.error(`Unknown command: ${command}`);
+  printUsage();
+  process.exit(1);
+}

package/lib/init.js

@@ -0,0 +1,375 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCAFFOLD_ROOT = fileURLToPath(new URL("../scaffold", import.meta.url));
+
+function toTitleCase(value) {
+  return value
+    .replace(/[^a-zA-Z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .split(" ")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function loadDirectoryTemplates(directoryPath, relativePrefix = "") {
+  const entries = readdirSync(directoryPath, { withFileTypes: true }).sort((left, right) =>
+    left.name.localeCompare(right.name)
+  );
+
+  return entries.flatMap((entry) => {
+    const absolutePath = path.join(directoryPath, entry.name);
+    const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      return loadDirectoryTemplates(absolutePath, relativePath);
+    }
+
+    return [
+      {
+        path: relativePath,
+        content: readFileSync(absolutePath, "utf8"),
+      },
+    ];
+  });
+}
+
+function buildTemplates(courseTitle) {
+  return [
+    {
+      path: "course.md",
+      content: `---
+schema_version: 1
+title: ${yamlString(courseTitle)}
+duration: 45
+tags:
+  - sample
+  - draft
+---
+Replace this description with the course overview.
+`,
+    },
+    {
+      path: "assets/.gitkeep",
+      content: "",
+    },
+    ...loadDirectoryTemplates(path.join(SCAFFOLD_ROOT, ".agents"), ".agents"),
+    {
+      path: "chapters/01-intro/chapter.md",
+      content: `---
+title: "Introduction"
+---
+Use this chapter to orient learners, define the first learning goal, and establish the course workflow.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/01-welcome/lesson.md",
+      content: `---
+kind: slides
+title: "Welcome"
+---
+Introduce the course and explain what the learner will build.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/01-welcome/slides/01-cover.md",
+      content: `---
+title: "Welcome"
+---
+# Welcome to ${courseTitle}
+
+Use this first slide to introduce the topic and set expectations.
+
+@script
+Welcome to the course. Use this slide to set context, explain the value of the material, and tell the learner what comes next.
+@endscript
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/01-welcome/slides/02-outline.md",
+      content: `---
+title: "Lesson Outline"
+---
+## Today
+
+- Why this topic matters
+- What the learner will build
+- How the lesson is structured
+
+@script
+Walk through the lesson outline and explain the sequence of concepts, practice, and assessment.
+@endscript
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/02-checkpoint-quiz/lesson.md",
+      content: `---
+kind: quiz
+title: "Checkpoint Quiz"
+---
+Check whether the learner understands the main goal of this opening lesson.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/02-checkpoint-quiz/quiz/quiz.md",
+      content: `---
+title: "Checkpoint Quiz"
+---
+Use this quiz to reinforce the core idea from the chapter. Replace the sample question with one that matches your course topic before publishing.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/02-checkpoint-quiz/quiz/questions/01-course-goal.md",
+      content: `---
+title: "Course Goal Check"
+correct_feedback: "Correct. The first chapter should build a practical foundation for the course topic."
+randomize_choices: false
+---
+What should this first chapter help a learner do in ${courseTitle}?
+
+@choice
+title: Build a practical foundation
+correct: true
+
+Build a practical foundation
+@endchoice
+
+@choice
+title: Memorize repository files
+correct: false
+feedback: Repository filenames and authoring rules are internal details, not the learner objective for a topic course.
+
+Memorize repository files
+@endchoice
+
+@choice
+title: Skip practice entirely
+correct: false
+feedback: An introduction should prepare learners for practice, not replace it.
+
+Skip practice entirely
+@endchoice
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/03-first-exercise/lesson.md",
+      content: `---
+kind: coding_exercise
+title: "First Exercise"
+---
+Give the learner a small task that matches the concepts introduced in the chapter.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/03-first-exercise/exercise/exercise.md",
+      content: `---
+title: "First Exercise"
+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.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/03-first-exercise/exercise/starter.py",
+      content: `def sum_values(values: list[int]) -> int:
+    return 0
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/03-first-exercise/exercise/solution.py",
+      content: `def sum_values(values: list[int]) -> int:
+    return sum(values)
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/04-first-spreadsheet/lesson.md",
+      content: `---
+kind: spreadsheet_lab
+title: "First Spreadsheet"
+---
+Give the learner a small spreadsheet task that reinforces the concepts from the chapter.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/04-first-spreadsheet/spreadsheet/exercise.md",
+      content: `---
+title: "First Spreadsheet"
+---
+## Context
+
+You have a small table with two values that need to be summed.
+
+## Instructions
+
+- In cell \`B4\`, enter a SUM formula to calculate the total of cells \`B2\` and \`B3\`.
+- The result should equal \`300\`.
+`,
+    },
+    {
+      path: "chapters/01-intro/lessons/04-first-spreadsheet/spreadsheet/workbook.json",
+      content: JSON.stringify(
+        {
+          sheets: {
+            Sheet1: {
+              name: "Sheet1",
+              cellData: {
+                0: { 0: { v: "Item" }, 1: { v: "Amount" } },
+                1: { 0: { v: "Item A" }, 1: { v: 100 } },
+                2: { 0: { v: "Item B" }, 1: { v: 200 } },
+                3: { 0: { v: "Total" } },
+              },
+            },
+          },
+        },
+        null,
+        2
+      ) + "\n",
+    },
+    {
+      path: "chapters/01-intro/lessons/04-first-spreadsheet/spreadsheet/solution.json",
+      content: JSON.stringify(
+        {
+          sheets: {
+            Sheet1: {
+              name: "Sheet1",
+              cellData: {
+                0: { 0: { v: "Item" }, 1: { v: "Amount" } },
+                1: { 0: { v: "Item A" }, 1: { v: 100 } },
+                2: { 0: { v: "Item B" }, 1: { v: 200 } },
+                3: { 0: { v: "Total" }, 1: { v: 300, f: "=SUM(B2:B3)" } },
+              },
+            },
+          },
+        },
+        null,
+        2
+      ) + "\n",
+    },
+    {
+      path: "chapters/01-intro/lessons/04-first-spreadsheet/spreadsheet/checks.json",
+      content: JSON.stringify(
+        [
+          {
+            id: "total-value",
+            label: "Total equals 300",
+            type: "value_equals",
+            cell: "B4",
+            value: 300,
+          },
+        ],
+        null,
+        2
+      ) + "\n",
+    },
+  ];
+}
+
+function parseInitArgs(args, cwd) {
+  let targetArg = ".";
+  let title;
+  let force = false;
+  let seenPath = false;
+  let positionalOnly = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!positionalOnly && arg === "--") {
+      positionalOnly = true;
+      continue;
+    }
+
+    if (!positionalOnly && arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (!positionalOnly && arg === "--title") {
+      index += 1;
+      if (index >= args.length) {
+        throw new Error("Missing value for --title");
+      }
+      title = args[index];
+      continue;
+    }
+
+    if (!positionalOnly && arg.startsWith("--title=")) {
+      title = arg.slice("--title=".length);
+      continue;
+    }
+
+    if (!seenPath) {
+      targetArg = arg;
+      seenPath = true;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  const targetPath = path.resolve(cwd, targetArg);
+  const fallbackTitle = toTitleCase(path.basename(targetPath)) || "New Course";
+
+  return {
+    targetPath,
+    title: title?.trim() || fallbackTitle,
+    force,
+  };
+}
+
+export function initCourseRepository(args, cwd = process.cwd()) {
+  const { targetPath, title, force } = parseInitArgs(args, cwd);
+
+  if (existsSync(targetPath)) {
+    const stats = statSync(targetPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Target path must be a directory: ${targetPath}`);
+    }
+  } else {
+    mkdirSync(targetPath, { recursive: true });
+  }
+
+  const templates = buildTemplates(title);
+  const conflicts = templates
+    .map((template) => path.join(targetPath, template.path))
+    .filter((filePath) => existsSync(filePath));
+
+  if (conflicts.length > 0 && !force) {
+    const conflictList = conflicts.map((filePath) => `- ${path.relative(targetPath, filePath)}`).join("\n");
+    throw new Error(
+      `Refusing to overwrite existing scaffold files in ${targetPath}.\n${conflictList}\nRe-run with --force to overwrite these files.`
+    );
+  }
+
+  const writtenFiles = [];
+  for (const template of templates) {
+    const absolutePath = path.join(targetPath, template.path);
+    mkdirSync(path.dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, template.content, "utf8");
+    writtenFiles.push(template.path);
+  }
+
+  return {
+    targetPath,
+    title,
+    force,
+    writtenFiles,
+  };
+}