@workshops.de/slidev-toolkit 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @workshops.de/slidev-toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared build, dev and deploy tooling for the workshops.de Slidev slide repositories. Slide repositories
+depend on this package instead of maintaining their own build scripts, deploy workflow and core
+dependencies (Slidev, Playwright, TypeScript, Vue). A fix or dependency update happens here once and
+reaches every repository with one version bump.
+
+## What it provides
+
+- **`workshop-slides` CLI**
+  - `workshop-slides build [--base /<repo>] [--no-pdf]`: builds every deck into `dist/`, exports a PDF
+    per deck and makes deep links like `/<deck>/presenter/1` work on GitHub Pages.
+  - `workshop-slides dev [<lesson-number>|all]`: starts the Slidev dev server (interactive menu without
+    an argument).
+  - `workshop-slides install-browser`: installs the Chromium version that matches the bundled
+    Playwright (npm 11 does not run Playwright's own install script).
+- **Pinned core dependencies:** `@slidev/cli`, `playwright-chromium`, `typescript` (6, required by
+  Slidev's Twoslash setup) and `vue`.
+- **Reusable deploy workflow:** `.github/workflows/deploy.yml`, called from each slide repository.
+
+Two repository layouts are detected automatically:
+
+| Layout      | Detected by                                                    | Output                                          |
+| ----------- | -------------------------------------------------------------- | ----------------------------------------------- |
+| Multi-deck  | `lessons/<NN-name>/*.md` with `base:` and `out:` in headmatter | `dist/<deck>/`, root `index.html` + `404.html`  |
+| Single-deck | `slides.md` in the repository root                             | `dist/` (Slidev's own `404.html`)               |
+
+## Using it in a slide repository
+
+`package.json`: only the toolkit, the theme and the addons the decks use:
+
+```json
+{
+  "scripts": {
+    "dev": "workshop-slides dev",
+    "build": "workshop-slides build",
+    "export": "slidev export"
+  },
+  "dependencies": {
+    "@workshops.de/slidev-theme": "2.1.0",
+    "slidev-addon-tldraw": "^0.5.1",
+    "slidev-addon-window-mockup": "0.3.1"
+  },
+  "devDependencies": {
+    "@workshops.de/slidev-toolkit": "^1.0.0"
+  }
+}
+```
+
+`.nvmrc`: `v24`
+
+`.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    uses: workshops-de/slidev-toolkit/.github/workflows/deploy.yml@v1
+```
+
+Then set **Settings → Pages → Source → GitHub Actions** once per repository.
+
+## Releasing
+
+1. Bump `version` in `package.json` and commit.
+2. Push a tag `vX.Y.Z`. The release workflow publishes to npm via trusted publishing (OIDC, no
+   token; configured on npmjs.com for `workshops-de/slidev-toolkit` and `release.yml`) and moves the
+   major tag (`v1`) that slide repositories use for the reusable workflow.
+3. Dependabot in the slide repositories picks up the new version.
+
+Breaking changes (a new Slidev major that needs content changes, a changed CLI) get a new major version,
+so repositories move over deliberately.

package/bin/workshop-slides.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// workshop-slides: shared build, dev and deploy tooling for workshops.de Slidev repositories.
+//
+// Two repository layouts are supported and detected automatically:
+//   multi-deck:  00-index.md + lessons/<NN-name>/<file>.md, each with `base:` and `out:` in its
+//                headmatter. Every deck is built into its own subfolder of dist/.
+//   single-deck: slides.md in the repository root, built into dist/.
+//
+// Commands:
+//   workshop-slides build [--base /<repo>] [--no-pdf]   build all decks (+ PDFs) into dist/
+//   workshop-slides dev [<lesson-number>|all]           start the Slidev dev server
+//   workshop-slides install-browser                     install the Chromium used for PDF export
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+const root = process.cwd();
+const requireFromProject = createRequire(path.join(root, 'package.json'));
+const color = (code) => (text) => (process.stdout.isTTY ? `\x1b[${code}m${text}\x1b[0m` : text);
+const green = color('32');
+const yellow = color('33');
+const cyan = color('36');
+const red = color('31');
+
+function fail(message) {
+  console.error(`${red('Error:')} ${message}`);
+  process.exit(1);
+}
+
+// Resolve a package bin from the project's node_modules. Transitive dependencies (like
+// @slidev/cli when it comes in through this toolkit) are not linked into node_modules/.bin,
+// so `npx slidev` would fetch a different version from the registry instead.
+function resolveBin(pkg, binName) {
+  let manifestPath;
+  try {
+    manifestPath = requireFromProject.resolve(`${pkg}/package.json`);
+  } catch {
+    fail(`${pkg} is not installed. Run npm install first.`);
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[binName];
+  if (!bin) fail(`${pkg} has no "${binName}" executable.`);
+  return path.join(path.dirname(manifestPath), bin);
+}
+
+function run(pkg, binName, args, { allowFailure = false } = {}) {
+  const result = spawnSync(process.execPath, [resolveBin(pkg, binName), ...args], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  if (result.status !== 0 && !allowFailure) process.exit(result.status ?? 1);
+  return result.status === 0;
+}
+
+const slidev = (args, options) => run('@slidev/cli', 'slidev', args, options);
+
+function headmatter(file) {
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  if (lines[0].trim() !== '---') return {};
+  const data = {};
+  for (const line of lines.slice(1)) {
+    if (line.trim() === '---') break;
+    const match = line.match(/^(base|out):\s*(.+?)\s*$/);
+    if (match) data[match[1]] = match[2].replace(/^['"]|['"]$/g, '');
+  }
+  return data;
+}
+
+function lessonDecks() {
+  const lessonsDir = path.join(root, 'lessons');
+  if (!fs.existsSync(lessonsDir)) return [];
+  return fs
+    .readdirSync(lessonsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .flatMap((dir) =>
+      fs
+        .readdirSync(path.join(lessonsDir, dir))
+        .filter((file) => file.endsWith('.md'))
+        .sort()
+        .map((file) => ({ dir, file: path.join('lessons', dir, file) })),
+    );
+}
+
+function layout() {
+  if (lessonDecks().length > 0) return 'multi';
+  if (fs.existsSync(path.join(root, 'slides.md'))) return 'single';
+  fail('No decks found: expected lessons/<NN-name>/*.md or slides.md in the repository root.');
+}
+
+function parseArgs(argv) {
+  const options = { base: '', pdf: true, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--base') options.base = (argv[++i] ?? '').replace(/\/+$/, '');
+    else if (argv[i] === '--no-pdf') options.pdf = false;
+    else options.rest.push(argv[i]);
+  }
+  return options;
+}
+
+function exportPdf(entry, output) {
+  console.log(`${green('Exporting PDF')} ${entry} → ${output}`);
+  const ok = slidev(['export', entry, '--output', output, '--timeout', '60000'], { allowFailure: true });
+  console.log(ok ? `   ${green('✓')} PDF exported` : `   ${yellow('⚠')} PDF export failed (is Chromium installed?)`);
+}
+
+function buildMulti({ base, pdf }) {
+  const decks = [{ dir: null, file: '00-index.md' }, ...lessonDecks()].filter(({ file }) =>
+    fs.existsSync(path.join(root, file)),
+  );
+  for (const { dir, file } of decks) {
+    const { base: deckBase, out } = headmatter(path.join(root, file));
+    if (!deckBase || !out) {
+      console.log(`${yellow('Skipping')} ${file} (missing base or out in headmatter)`);
+      continue;
+    }
+    const fullBase = `${base}${deckBase}`;
+    console.log(`${green('Building')} ${file}\n   ➤ base: ${fullBase}\n   ➤ out : ${out}`);
+    slidev(['build', file, '--base', fullBase, '--out', out]);
+    if (pdf && dir) exportPdf(file, path.join('dist', dir, 'slides.pdf'));
+  }
+
+  const dist = path.join(root, 'dist');
+  fs.mkdirSync(dist, { recursive: true });
+  const indexUrl = `${base}/00-index/`;
+  fs.writeFileSync(
+    path.join(dist, 'index.html'),
+    `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=${indexUrl}">
+  <title>Redirecting...</title>
+</head>
+<body>
+  <p>Redirecting to <a href="${indexUrl}">slide decks</a>...</p>
+</body>
+</html>
+`,
+  );
+
+  // GitHub Pages only serves the 404.html at the site root, but every deck is its own SPA in a
+  // subfolder (Slidev's own 404.html lands in dist/<deck>/ and is never used). This page loads the
+  // matching deck's index.html in place, so the URL stays intact and the deck router opens the
+  // requested route, e.g. /<deck>/presenter/1.
+  fs.writeFileSync(
+    path.join(dist, '404.html'),
+    `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Loading…</title>
+  <script>
+    (function () {
+      var base = '${base}/';
+      var path = location.pathname;
+      var deck = path.indexOf(base) === 0 ? path.slice(base.length).split('/')[0] : '';
+      function notFound() {
+        document.title = 'Not found';
+        document.body.innerHTML = '<h1>404</h1><p><a href="' + base + '">Back to the overview</a></p>';
+      }
+      if (!deck) { document.addEventListener('DOMContentLoaded', notFound); return; }
+      fetch(base + deck + '/index.html')
+        .then(function (r) { if (!r.ok) throw new Error(r.status); return r.text(); })
+        .then(function (html) { document.open(); document.write(html); document.close(); })
+        .catch(notFound);
+    })();
+  </script>
+</head>
+<body></body>
+</html>
+`,
+  );
+  console.log(`${green('Created')} dist/index.html and dist/404.html`);
+}
+
+function buildSingle({ base, pdf }) {
+  // Slidev writes its own dist/404.html (a copy of index.html), which covers deep links here.
+  console.log(`${green('Building')} slides.md\n   ➤ base: ${base}/\n   ➤ out : dist`);
+  slidev(['build', 'slides.md', '--base', `${base}/`, '--out', 'dist']);
+  if (pdf) exportPdf('slides.md', path.join('dist', 'slides.pdf'));
+}
+
+async function dev(choice) {
+  if (layout() === 'single') return slidev(['slides.md', '--open']);
+
+  const lessons = lessonDecks().filter(({ dir }, i, all) => all.findIndex((d) => d.dir === dir) === i);
+  const hasAll = fs.existsSync(path.join(root, 'slides.md'));
+  if (!choice) {
+    console.log(`\n${cyan('Workshop slides: development server')}\n`);
+    if (hasAll) console.log(`  ${green('0')}) All lessons (slides.md) [default]`);
+    for (const { dir } of lessons) console.log(`  ${green(dir.split('-')[0])}) ${dir.replace(/^[^-]*-/, '')}`);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    choice = (await rl.question(`\nEnter your choice${hasAll ? ' [0]' : ''}: `)).trim() || (hasAll ? '0' : '');
+    rl.close();
+  }
+  if (choice === '0' || choice === 'all') {
+    if (!hasAll) fail('slides.md not found in the repository root.');
+    return slidev(['slides.md', '--open']);
+  }
+  const lesson = lessons.find(({ dir }) => dir.split('-')[0] === choice.padStart(2, '0'));
+  if (!lesson) fail(`No lesson found starting with '${choice}'.`);
+  return slidev([lesson.file, '--open']);
+}
+
+const [command, ...argv] = process.argv.slice(2);
+switch (command) {
+  case 'build': {
+    const options = parseArgs(argv);
+    (layout() === 'multi' ? buildMulti : buildSingle)(options);
+    console.log(cyan('Build complete!'));
+    break;
+  }
+  case 'dev':
+    await dev(argv[0]);
+    break;
+  case 'install-browser':
+    run('playwright-chromium', 'playwright', ['install', 'chromium']);
+    break;
+  default:
+    console.log(`Usage:
+  workshop-slides build [--base /<repo>] [--no-pdf]   build all decks (+ PDFs) into dist/
+  workshop-slides dev [<lesson-number>|all]           start the Slidev dev server
+  workshop-slides install-browser                     install Chromium for the PDF export`);
+    process.exit(command ? 1 : 0);
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@workshops.de/slidev-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Shared build, dev and deploy tooling for workshops.de Slidev slide repositories",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workshops-de/slidev-toolkit.git"
+  },
+  "bin": {
+    "workshop-slides": "bin/workshop-slides.mjs"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=24",
+    "npm": ">=11"
+  },
+  "dependencies": {
+    "@slidev/cli": "^53.1.0",
+    "playwright-chromium": "^1.65.0",
+    "typescript": "^6.0.3",
+    "vue": "^3.5.45"
+  }
+}