mdeck 3.0.0 → 3.1.0

package/src/extensions/discover.js

@@ -5,7 +5,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { resolve, dirname, relative } from 'node:path'
 import { homedir } from 'node:os'
 import { MANIFEST_FILENAME, ManifestError, KINDS, parseManifestText, validateManifest } from './manifest.js'
-import { builtinExtensionsRoot, bundledPacksRoot } from '../paths.js'
+import { builtinExtensionsRoot } from '../paths.js'
 
 const SKIP = name => name.startsWith('.') || name === 'node_modules'
 
@@ -20,36 +20,31 @@ export function userExtensionsDir() {
   return resolve(mdeckHome(), 'extensions')
 }
 
-// The bundled packs this user removed (`mdeck themes remove <pack> --global`):
-// they stay in mdeck's folder but are not offered.
+// The built-in themes and palettes this user removed (`mdeck themes remove
+// aurora`): they stay in mdeck's folder but are not offered. Kept as
+// "theme:aurora" and "palette:neon".
 const removedFile = () => resolve(mdeckHome(), 'removed.json')
-export function removedPacks() {
-  try { const packs = JSON.parse(readFileSync(removedFile(), 'utf8')).packs; return Array.isArray(packs) ? packs : [] } catch { return [] }
+export function removedBuiltIns() {
+  let saved = {}
+  try { saved = JSON.parse(readFileSync(removedFile(), 'utf8')) } catch {}
+  return (Array.isArray(saved.hidden) ? saved.hidden : []).filter(key => /^(theme|palette):[a-z][a-z0-9-]*$/.test(key))
 }
-export function setRemovedPacks(packs) {
+export function setRemovedBuiltIns(keys) {
   mkdirSync(mdeckHome(), { recursive: true })
-  writeFileSync(removedFile(), JSON.stringify({ packs: [...new Set(packs)].sort() }, null, 2) + '\n')
+  writeFileSync(removedFile(), JSON.stringify({ hidden: [...new Set(keys)].sort() }, null, 2) + '\n')
 }
 
-// The packs that come with mdeck: { id: folder }, all or only those offered
-// (not `hidden`, by default those this user removed).
-export function bundledPacks({ root = bundledPacksRoot, all = false, hidden = all ? [] : removedPacks() } = {}) {
-  if (!existsSync(root)) return {}
-  const removed = hidden
-  return Object.fromEntries(sortedEntries(root).map(entry => entry.name).filter(id => !removed.includes(id)).map(id => [id, resolve(root, id)]))
-}
-
-// Built-in layouts and the bundled packs, then the user's, then the deck's
+// mdeck's own layouts, themes and palettes, then the user's, then the deck's
 // own. For themes and palettes a later place replaces an earlier one with the
-// same id: an installed newer version replaces the bundled one, and a deck's
-// copy replaces both.
-// `userRoot: null` leaves out what this user installed and removed, for
-// results that must not depend on the computer (checks, the repository).
-export function extensionRoots(slidesPath, { builtinRoot = builtinExtensionsRoot, packsRoot = bundledPacksRoot, userRoot = userExtensionsDir() } = {}) {
+// same id: an installed newer version replaces the built-in one, and a
+// deck's copy replaces both. Built-in themes and palettes this user removed
+// are left out. `userRoot: null` leaves out what this user installed and
+// removed, for results that must not depend on the computer (checks, the
+// repository).
+export function extensionRoots(slidesPath, { builtinRoot = builtinExtensionsRoot, userRoot = userExtensionsDir() } = {}) {
   const deckDir = dirname(resolve(slidesPath))
   return [
-    { dir: builtinRoot, source: 'built-in' },
-    ...Object.entries(bundledPacks({ root: packsRoot, hidden: userRoot ? removedPacks() : [] })).map(([pack, dir]) => ({ dir, source: 'built-in', pack })),
+    { dir: builtinRoot, source: 'built-in', hidden: userRoot ? removedBuiltIns() : [] },
     ...(userRoot ? [{ dir: userRoot, source: 'user' }] : []),
     { dir: resolve(deckDir, 'extensions'), source: 'local' },
   ]
@@ -80,21 +75,17 @@ function readLayout(record) {
 function loadManifest({ dir, file, folderName }) {
   const raw = parseManifestText(readFileSync(file, 'utf8'), file)
   const record = validateManifest(raw, { file, dir, folderName })
-  // An installed pack leaves a note in each folder saying which pack it is.
-  let pack = null
-  try { pack = JSON.parse(readFileSync(resolve(dir, '.mdeck-pack.json'), 'utf8')).pack ?? null } catch {}
-  const withPack = pack ? { ...record, pack } : record
-  return record.kind === 'layout' ? readLayout(withPack) : withPack
+  return record.kind === 'layout' ? readLayout(record) : record
 }
 
 export function discoverExtensions(roots) {
   const registry = { layouts: {}, themes: {}, palettes: {}, records: [], warnings: [] }
   const byKey = new Map()
   const RANK = { 'built-in': 0, user: 1, local: 2 }
-  const add = (record, source, pack) => {
+  const add = (record, source) => {
     const key = `${record.kind}:${record.id}`
     const existing = byKey.get(key)
-    const entry = { ...record, source, ...(pack ? { pack } : {}) }
+    const entry = { ...record, source }
     // Themes and palettes may be replaced from a later place; layouts and two
     // with one id in the same place may not.
     const replaces = existing && record.kind !== 'layout' && RANK[source] > RANK[existing.source]
@@ -108,7 +99,10 @@ export function discoverExtensions(roots) {
   }
   for (const root of roots) {
     if (!existsSync(root.dir) || !statSync(root.dir).isDirectory()) continue
-    for (const found of walk(root.dir)) { const record = loadManifest(found); add(record, root.source, root.pack ?? record.pack) }
+    for (const found of walk(root.dir)) {
+      const record = loadManifest(found)
+      if (!root.hidden?.includes(`${record.kind}:${record.id}`)) add(record, root.source)
+    }
   }
   // Themes and palettes in name order, wherever they come from.
   for (const kind of ['themes', 'palettes']) registry[kind] = Object.fromEntries(Object.entries(registry[kind]).sort(([a], [b]) => a.localeCompare(b, 'en')))
@@ -135,10 +129,9 @@ function checkPaletteReferences(registry) {
   }
 }
 
-// The extensions that come with mdeck, alone: layouts and every bundled pack,
-// removed or not.
+// The extensions that come with mdeck, alone, removed or not.
 export function builtInRegistry() {
-  return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }, ...Object.entries(bundledPacks({ all: true })).map(([pack, dir]) => ({ dir, source: 'built-in', pack }))])
+  return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }])
 }
 
 export function loadRegistry(slidesPath, options) {
@@ -158,7 +151,7 @@ export function serializeRegistry(registry, { relativeTo } = {}) {
   const out = { schema: 2, warnings: registry.warnings }
   for (const kind of KINDS) {
     out[`${kind}s`] = Object.values(registry[`${kind}s`]).map(record => ({
-      ...record.manifest, kind, source: record.source, ...(record.pack ? { pack: record.pack } : {}),
+      ...record.manifest, kind, source: record.source, ...(record.package?.version ? { version: record.package.version } : {}),
       file: relativeTo ? relative(relativeTo, record.file) : record.file,
     }))
   }

package/src/extensions/installed.js

@@ -1,63 +1,88 @@
-// Where packs are installed: for every deck (the user's folder, where the
-// bundled packs are offered too) or beside one deck. Shared by mdeck themes
-// and the design page.
-import { existsSync, statSync } from 'node:fs'
+// Where themes and palettes are installed: for every deck (the user's
+// folder, where the built-in ones are offered too) or beside one deck.
+// Shared by mdeck themes / mdeck palettes and the design page.
+import { existsSync, rmSync, statSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
-import { bundledPacks, loadRegistry, mdeckHome, removedPacks, setRemovedPacks, userExtensionsDir } from './discover.js'
-import { installedPacks, installWithRequirements, PackError, removePack } from './packs.js'
+import { loadRegistry, mdeckHome, removedBuiltIns, setRemovedBuiltIns, userExtensionsDir } from './discover.js'
+import { installedPackages, installPackage, keyOf, obtainPackage, PackageError, removePackage, satisfies, withDependencies } from './packages.js'
+
+const fail = message => { throw new PackageError(message) }
 
 // Where a command works: for every deck (the user's folder), or beside a
 // deck when one is named or --local is given.
 export function target(where, local) {
-  if (!where && !local) return { user: true, root: userExtensionsDir(), deck: resolve('slides.md'), label: 'for every deck' }
+  if (!where && !local) return { user: true, root: userExtensionsDir(), deck: resolve(mdeckHome(), 'no-deck', 'slides.md'), label: 'for every deck' }
   const given = resolve(where ?? '.')
-  if (!existsSync(given) && !/\.md$/i.test(given)) throw new PackError(`${where} does not exist; name a slides file or the folder it is in`)
+  if (!existsSync(given) && !/\.md$/i.test(given)) fail(`${where} does not exist; name a slides file or the folder it is in`)
   const folder = existsSync(given) && statSync(given).isDirectory() ? given : dirname(given)
   return { user: false, root: resolve(folder, 'extensions'), deck: existsSync(given) && !statSync(given).isDirectory() ? given : resolve(folder, 'slides.md'), label: `in ${resolve(folder, 'extensions')}` }
 }
 
-// The packs that `where` has: installed there, and for the user's folder
-// also the bundled packs that are offered.
-export function packsAt(where) {
-  const installed = installedPacks(where.root)
-  if (!where.user) return installed
-  const offered = Object.fromEntries(Object.keys(bundledPacks()).map(id => [id, { bundled: true, requires: [] }]))
-  return { ...offered, ...installed }
-}
-
-// The packs at `where` that require `id`.
-export function requiredBy(id, where, catalogue) {
-  return Object.entries(packsAt(where)).filter(([other, pack]) => {
-    if (other === id) return false
-    const requires = pack.bundled ? catalogue.packs.find(p => p.id === other)?.requires ?? [] : pack.requires
-    return requires.includes(id)
-  }).map(([other]) => other)
-}
+// The themes and palettes `where` sees, as a registry: for every deck what
+// this user has, beside a deck also what that deck has.
+const registryAt = where => loadRegistry(where.deck)
 
-// Installs a pack with what it requires. For every deck, a bundled pack is
-// offered again instead of copied.
-export async function installHere(catalogue, id, where, { mdeckVersion, force = false }) {
-  const removed = removedPacks()
-  const has = pack => Object.hasOwn(packsAt(where), pack)
-  const bundledHere = where.user ? entry => { setRemovedPacks(removedPacks().filter(other => other !== entry.id)); return true } : null
-  const done = await installWithRequirements(catalogue, id, { root: where.root, mdeckVersion, force, has, bundledHere })
-  return done.map(step => ({ ...step, wasRemoved: step.bundled && removed.includes(step.id) }))
+// Installs a theme or palette with what it needs. What `where` has already
+// stays as it is. A built-in one is not copied: for every deck it is offered
+// again if it was removed. A theme and its own palette may need each other,
+// so the registry is checked before anything is written and once all is
+// there; if anything fails, what this call installed is taken out again.
+export async function installHere(catalogue, kind, id, where, { mdeckVersion, force = false }) {
+  const before = registryAt(where)
+  const plan = withDependencies(catalogue, kind, id)
+  const done = [], written = []
+  try {
+    for (const entry of plan) {
+      const key = keyOf(entry.kind, entry.id)
+      const requested = entry.kind === kind && entry.id === id
+      if (entry.builtIn) {
+        const hidden = removedBuiltIns()
+        const wasRemoved = hidden.includes(key)
+        if (wasRemoved) setRemovedBuiltIns(hidden.filter(other => other !== key))
+        done.push({ kind: entry.kind, id: entry.id, version: entry.version, builtIn: true, wasRemoved, requested })
+        continue
+      }
+      const have = installedPackages(where.root)[key]
+      // Beside a deck, what is installed only for every deck is copied too,
+      // so the slide folder carries it.
+      const there = before[`${entry.kind}s`][entry.id]
+      if (!requested && (have || (there && (where.user || there.source !== 'user')))) { done.push({ kind: entry.kind, id: entry.id, version: have?.version ?? null, kept: true, requested }); continue }
+      if (!satisfies(entry.mdeck, mdeckVersion)) fail(`The ${entry.kind} ${entry.id} ${entry.version} needs mdeck ${entry.mdeck}; this is ${mdeckVersion}. Update mdeck first: npm install -g mdeck`)
+      const { bundle, url, digest } = await obtainPackage(catalogue, entry)
+      const result = installPackage(bundle, { root: where.root, url, digest, force })
+      if (!result.replaced) written.push(result.dir)
+      done.push({ kind: entry.kind, id: entry.id, version: entry.version, replaced: result.replaced, requested })
+    }
+    registryAt(where)
+  } catch (error) {
+    for (const dir of written) rmSync(dir, { recursive: true, force: true })
+    throw error
+  }
+  return done
 }
 
-// Removes a pack. For every deck, a bundled pack is hidden (and a newer
-// version installed over it removed too); install brings it back.
-export function removeHere(catalogue, id, where, { force = false } = {}) {
-  const needed = requiredBy(id, where, catalogue)
-  if (needed.length && !force) throw new PackError(`${needed.join(', ')} ${needed.length > 1 ? 'require' : 'requires'} ${id}; remove ${needed.length > 1 ? 'them' : 'it'} first, or add --force`)
-  const installed = installedPacks(where.root)[id]
-  const isBundled = Object.hasOwn(bundledPacks({ all: true }), id)
-  if (!installed && !(where.user && isBundled)) throw new PackError(`The pack ${id} is not installed ${where.label}`)
-  // Every deck needs a theme: the last one stays, even with --force.
-  if (where.user) {
-    const themes = Object.values(loadRegistry(resolve(mdeckHome(), 'no-deck', 'slides.md')).themes)
-    if (themes.length && themes.every(theme => theme.pack === id)) throw new PackError(`${id} has the last theme installed for every deck (${themes.map(theme => theme.id).join(', ')}); install another theme first, for example mdeck themes install neue`)
+// Removes a theme or palette. A built-in one is hidden instead, for every
+// deck; installing it brings it back. A palette a theme here uses by default
+// stays; a theme takes the palettes that belong only to it along; the last
+// theme stays.
+export function removeHere(kind, id, where, { force = false } = {}) {
+  const registry = registryAt(where)
+  const record = registry[`${kind}s`][id]
+  const installed = installedPackages(where.root)
+  const key = keyOf(kind, id)
+  if (!installed[key] && !(where.user && record?.source === 'built-in')) fail(`The ${kind} ${id} is not installed ${where.label}`)
+  if (kind === 'palette') {
+    const users = Object.values(registry.themes).filter(theme => theme.manifest.palette === id).map(theme => theme.id)
+    if (users.length) fail(`${users.join(', ')} ${users.length > 1 ? 'use' : 'uses'} the palette ${id} by default; remove ${users.length > 1 ? 'those themes' : 'that theme'} first`)
+  }
+  if (kind === 'theme' && Object.keys(registry.themes).length === 1) fail(`${id} is the last theme ${where.label}; install another theme first (mdeck themes search lists them)`)
+  const removed = []
+  const take = (k, i) => {
+    const r = registry[`${k}s`][i]
+    if (installedPackages(where.root)[keyOf(k, i)]) { removePackage(k, i, { root: where.root, force }); removed.push({ kind: k, id: i }) }
+    else if (where.user && r?.source === 'built-in') { setRemovedBuiltIns([...removedBuiltIns(), keyOf(k, i)]); removed.push({ kind: k, id: i, hidden: true }) }
   }
-  const pack = installed ? removePack(id, { root: where.root, force }) : null
-  if (where.user && isBundled) setRemovedPacks([...removedPacks(), id])
-  return { folders: pack?.folders ?? [], hidden: where.user && isBundled }
+  take(kind, id)
+  if (kind === 'theme') for (const palette of Object.values(registry.palettes)) if (palette.manifest.theme === id) take('palette', palette.id)
+  return removed
 }

package/src/extensions/manifest.js

@@ -15,11 +15,16 @@ export const MANIFEST_FILENAME = 'extension.toml'
 const FRAMES = ['standard', 'title', 'chapter', 'none']
 const PROPERTY_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object']
 const SHARED_KEYS = ['schema', 'kind', 'id', 'title', 'description']
+// A theme or palette is also a package that can be installed: its version,
+// who made it, its licence, a web page and the oldest mdeck it works with.
+const PACKAGE_KEYS = ['version', 'author', 'license', 'homepage', 'mdeck']
 const KEYS = {
   layout: [...SHARED_KEYS, 'frame', 'files', 'regions', 'properties'],
-  theme: [...SHARED_KEYS, 'palette', 'palettes', 'appearance', 'fonts', 'files', 'tokens', 'params'],
-  palette: [...SHARED_KEYS, 'theme', 'light', 'dark'],
+  theme: [...SHARED_KEYS, ...PACKAGE_KEYS, 'palette', 'palettes', 'appearance', 'fonts', 'files', 'tokens', 'params'],
+  palette: [...SHARED_KEYS, ...PACKAGE_KEYS, 'theme', 'light', 'dark'],
 }
+export const VERSION_RE = /^\d+\.\d+\.\d+$/
+export const RANGE_RE = /^>=\s*(\d+\.\d+\.\d+)$/
 const SCHEMA_KEYS = ['type', 'title', 'description', 'enum', 'required', 'default', 'minimum', 'maximum', 'minItems', 'maxItems', 'items']
 const RESERVED_NAMES = ['constructor', 'prototype', '__proto__']
 
@@ -72,7 +77,19 @@ export function validateManifest(raw, { file, dir, folderName, fileExists = exis
   const manifest = kind === 'layout' ? validateLayout(raw, shared, fail)
     : kind === 'theme' ? validateTheme(raw, shared, fail)
     : validatePalette(raw, shared, fail)
-  return { kind, id: raw.id, title: shared.title, description: shared.description, dir, file, manifest, files }
+  const pkg = kind === 'layout' ? null : validatePackage(raw, fail)
+  return { kind, id: raw.id, title: shared.title, description: shared.description, dir, file, manifest, files, ...(pkg ? { package: pkg } : {}) }
+}
+
+// The package settings, all optional for a theme or palette of one's own;
+// the theme repository requires version, author and license.
+function validatePackage(raw, fail) {
+  const pkg = {}
+  if (raw.version != null) { if (typeof raw.version !== 'string' || !VERSION_RE.test(raw.version)) fail('version must look like 1.0.0', 'version'); pkg.version = raw.version }
+  for (const key of ['author', 'license']) if (raw[key] != null) { if (typeof raw[key] !== 'string' || !raw[key].trim()) fail(`${key} must be text`, key); pkg[key] = raw[key].trim() }
+  if (raw.homepage != null) { if (typeof raw.homepage !== 'string' || !/^https:\/\//.test(raw.homepage)) fail('homepage must be an https:// address', 'homepage'); pkg.homepage = raw.homepage }
+  if (raw.mdeck != null) { if (typeof raw.mdeck !== 'string' || !RANGE_RE.test(raw.mdeck)) fail('mdeck must look like ">=3.1.0"', 'mdeck'); pkg.mdeck = raw.mdeck }
+  return pkg
 }
 
 const FILE_KEYS = { layout: ['layout', 'styles', 'starter'], theme: ['styles'], palette: [] }

package/src/extensions/moved.js

@@ -1,13 +1,20 @@
 // Themes and palettes that came with mdeck before 3.0 and now live in the
-// theme repository, by the pack that has them. A deck that names one is told
-// how to install it instead of being told the name is unknown.
+// theme repository. A deck that names one is told how to install it instead
+// of being told the name is unknown.
 export const MOVED = {
-  themes: { duet: 'duet', editorial: 'editorial', fhnw: 'fhnw', terminal: 'terminal', sketch: 'sketch' },
-  palettes: { cobalt: 'duet', terra: 'editorial', brand: 'fhnw', phosphor: 'terminal', pastel: 'sketch', ember: 'earth', forest: 'earth', graphite: 'graphite' },
+  themes: ['duet', 'editorial', 'fhnw', 'terminal', 'sketch'],
+  palettes: ['cobalt', 'terra', 'brand', 'phosphor', 'pastel', 'forest'],
 }
 
-// "The theme "duet" is no longer built in: mdeck themes install duet", or null.
+// Palettes that were removed because another one looks almost the same, by
+// the one to use instead.
+export const REPLACED = { palettes: { graphite: 'nordic', ember: 'paper' } }
+
+// "The theme "duet" is no longer built into mdeck; install it with: mdeck
+// themes install duet", what to use instead of a removed one, or null.
+// Installing goes to every deck by default.
 export function movedHint(kind, id) {
-  const pack = MOVED[`${kind}s`]?.[id]
-  return pack ? `The ${kind} "${id}" is no longer built into mdeck; install it beside the deck with: mdeck themes install ${pack}` : null
+  const instead = REPLACED[`${kind}s`]?.[id]
+  if (instead) return `The ${kind} "${id}" was removed from mdeck; use ${kind}: ${instead}, which looks almost the same`
+  return MOVED[`${kind}s`]?.includes(id) ? `The ${kind} "${id}" is no longer built into mdeck; install it with: mdeck ${kind}s install ${id}` : null
 }