create-marp-presentation 1.2.0 → 1.2.1

package/cli/commands/add-themes-cli.js

@@ -0,0 +1,85 @@
+// cli/commands/add-themes-cli.js
+/**
+ * Add themes to existing project command for meta-package CLI
+ * This file is NOT copied to generated projects
+ */
+const fs = require('fs');
+const path = require('path');
+
+const { AddThemesCommand } = require('../../lib/add-themes-command');
+const { ThemeError } = require('../../lib/errors');
+
+/**
+ * Add themes to an existing project
+ * @param {string} targetPath - Path to the target project
+ * @param {Object} options - Configuration options
+ * @param {string} options.themesLibraryPath - Path to themes library
+ * @param {string[]} options.themeNames - Specific theme names to add (optional)
+ * @returns {Promise<void>}
+ */
+async function addThemesToExistingProject(targetPath, options = {}) {
+  const {
+    themesLibraryPath = path.join(__dirname, '../..', 'themes'),
+    themeNames = null
+  } = options;
+
+  // Validate target path exists
+  const resolvedPath = path.resolve(targetPath);
+  if (!fs.existsSync(resolvedPath)) {
+    console.error(`Error: Directory does not exist: ${targetPath}`);
+    throw new ThemeError(`Target path does not exist: ${targetPath}`);
+  }
+
+  // Check if it's a valid Marp project (has presentation.md or package.json)
+  const hasPresentation = fs.existsSync(path.join(resolvedPath, 'presentation.md'));
+  const hasPackageJson = fs.existsSync(path.join(resolvedPath, 'package.json'));
+
+  if (!hasPresentation && !hasPackageJson) {
+    console.warn('Warning: This does not appear to be a Marp presentation project.');
+    console.warn('  (no presentation.md or package.json found)');
+  }
+
+  // Create AddThemesCommand with themes library path
+  const command = new AddThemesCommand({
+    templatePath: themesLibraryPath,
+    interactive: true
+  });
+
+  try {
+    console.log(`Adding themes to: ${resolvedPath}`);
+    console.log();
+
+    // Execute command - pass theme names if provided, otherwise prompt
+    const { copied, skipped, conflicts } = await command.execute(resolvedPath, {
+      themes: themeNames || undefined
+    });
+
+    // Show summary
+    const copiedNames = copied.map(t => t.name);
+    console.log(`\nCopied themes: ${copiedNames.join(', ') || 'none'}`);
+    if (skipped.length > 0) {
+      console.log(`Skipped: ${skipped.join(', ')}`);
+    }
+    if (conflicts.length > 0) {
+      console.log(`Conflicts: ${conflicts.join(', ')}`);
+    }
+
+    console.log();
+    console.log('Themes added successfully!');
+    console.log(`\nNext steps in ${targetPath}:`);
+    console.log('  npm run theme:list # List available themes');
+    console.log('  npm run theme:set <theme>  # Set active theme');
+    console.log();
+
+  } catch (error) {
+    if (error instanceof ThemeError) {
+      console.error(`Error: ${error.message}`);
+      throw error;
+    }
+    throw error;
+  }
+}
+
+module.exports = {
+  addThemesToExistingProject
+};

package/cli/commands/create-project.js

@@ -0,0 +1,199 @@
+// cli/commands/create-project.js
+/**
+ * Project creation command for meta-package CLI
+ * This file is NOT copied to generated projects
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { AddThemesCommand } = require('../../lib/add-themes-command');
+const { Prompts } = require('../../lib/prompts');
+const { ThemeManager } = require('../../lib/theme-manager');
+
+const { copyDir, copyOptionalFiles } = require('../utils/file-utils');
+const { askCreateExamples } = require('../utils/prompt-utils');
+
+/**
+ * Validate project name
+ * @param {string} name - Project name to validate
+ * @returns {boolean} True if valid
+ */
+function validateProjectName(name) {
+  const validName = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+  return validName.test(name);
+}
+
+/**
+ * Parse --path argument from argv
+ * @param {string[]} argv - Process argv (should start from index 2)
+ * @returns {{outputPath: string, pathIndex: number|null}} Parsed arguments
+ */
+function parsePathArg(argv) {
+  let outputPath = process.cwd();
+  const pathIndex = argv.indexOf('--path');
+  if (pathIndex !== -1 && pathIndex + 1 < argv.length) {
+    return { outputPath: null, pathIndex }; // Signal that validation is needed
+  }
+  return { outputPath, pathIndex: null };
+}
+
+/**
+ * Create a new Marp presentation project
+ * @param {string} projectName - Name of the project
+ * @param {Object} options - Configuration options
+ * @param {string} options.outputPath - Output directory path (default: current directory)
+ * @param {string} options.templatePath - Path to template directory
+ * @param {string} options.themesLibraryPath - Path to themes library
+ * @param {Function} options.validatePath - Path validation function
+ * @returns {Promise<void>}
+ */
+async function createProject(projectName, options = {}) {
+  const {
+    outputPath: providedOutputPath,
+    templatePath = path.join(__dirname, '../..', 'template'),
+    themesLibraryPath = path.join(__dirname, '../..', 'themes'),
+    validatePath
+  } = options;
+
+  // Validate project name
+  if (!validateProjectName(projectName)) {
+    console.error(`Invalid project name: "${projectName}"`);
+    console.error('Project name must be lowercase, contain only letters, numbers, and hyphens.');
+    throw new Error('Invalid project name');
+  }
+
+  // Determine output path
+  let outputPath = providedOutputPath || process.cwd();
+
+  // Build final project path
+  const projectPath = path.join(outputPath, projectName);
+
+  // Check if project already exists
+  if (fs.existsSync(projectPath)) {
+    console.error(`Directory "${projectName}" already exists.`);
+    throw new Error('Project directory already exists');
+  }
+
+  console.log(`Creating Marp presentation: ${projectName}`);
+  if (outputPath !== process.cwd()) {
+    console.log(`  Location: ${projectPath}`);
+  }
+  console.log();
+
+  // Ask about example slides
+  const createExamples = await askCreateExamples();
+
+  // Create project directory
+  fs.mkdirSync(projectPath, { recursive: true });
+
+  // Copy template completely
+  copyDir(templatePath, projectPath);
+
+  // Copy lib scripts to project
+  const rootLibPath = path.join(__dirname, '../..', 'lib');
+  const projectScriptsLibPath = path.join(projectPath, 'scripts', 'lib');
+  fs.mkdirSync(projectScriptsLibPath, { recursive: true });
+  copyDir(rootLibPath, projectScriptsLibPath);
+
+  // Verify marp.themeSet configuration exists in package.json
+  ThemeManager.ensureThemeSetConfig(projectPath);
+
+  console.log('✓ Project created');
+
+  // Copy optional files
+  if (createExamples) {
+    copyOptionalFiles(projectPath);
+    console.log('✓ Example slides added');
+    console.log('✓ Demo image added to static/');
+  }
+
+  // Copy theme management documentation
+  const themeDocsSource = path.join(__dirname, '../..', 'docs', 'theme-management.md');
+  const themeDocsDest = path.join(projectPath, 'docs', 'theme-management.md');
+  if (fs.existsSync(themeDocsSource)) {
+    fs.mkdirSync(path.dirname(themeDocsDest), { recursive: true });
+    fs.copyFileSync(themeDocsSource, themeDocsDest);
+    console.log('✓ Theme management guide added');
+  }
+
+  // Add themes to project (prompts user interactively if TTY)
+  let copied = [];
+  if (process.stdin.isTTY) {
+    // Interactive mode - prompt for themes
+    console.log();
+    const command = new AddThemesCommand({
+      templatePath: themesLibraryPath,
+      interactive: true
+    });
+
+    const result = await command.execute(projectPath, {
+      themes: null  // Triggers built-in prompt
+    });
+    copied = result.copied;
+  }
+  // Non-interactive mode: skip theme addition entirely
+
+  // Select and set active theme from copied themes
+  if (copied && copied.length > 0) {
+    console.log();
+    const themeNames = copied.map(t => t.name);
+    const activeTheme = await Prompts.promptActiveTheme(themeNames);
+    const themeManager = new ThemeManager(projectPath);
+    try {
+      themeManager.setActiveTheme(activeTheme);
+      console.log(`✓ Set active theme to "${activeTheme}"`);
+    } catch (error) {
+      console.warn(`  Warning: Could not set active theme: ${error.message}`);
+    }
+  } else {
+    // No themes copied, set default active theme
+    const themeManager = new ThemeManager(projectPath);
+    try {
+      themeManager.setActiveTheme('default');
+      console.log(`✓ Set active theme to "default"`);
+    } catch (error) {
+      console.warn(`  Warning: Could not set active theme: ${error.message}`);
+    }
+  }
+
+  console.log();
+
+  // Run npm install
+  console.log('Installing dependencies...');
+  const installResult = spawnSync('npm', ['install'], {
+    cwd: projectPath,
+    stdio: 'inherit',
+  });
+
+  if (installResult.status !== 0) {
+    console.error();
+    console.error('Failed to install dependencies.');
+    console.error('Please run "cd ' + projectName + ' && npm install" manually.');
+    throw new Error('npm install failed');
+  }
+
+  console.log();
+  console.log('✓ Dependencies installed');
+  console.log();
+  console.log('Next steps:');
+  const cwdRelativePath = path.relative(process.cwd(), projectPath);
+  const cdPath = cwdRelativePath.startsWith('..') ? projectPath : cwdRelativePath;
+  const readmePath = path.join(cdPath, 'README.md');
+  console.log(`  cd ${cdPath}`);
+  console.log('  npm run dev        # Start live preview');
+  console.log('  npm run theme:list # List available themes');
+  console.log('  npm run theme:set <theme-name> # Set active theme');
+  console.log('  npm run theme:add  # Add more themes to the project');
+  console.log('  npm run build:all  # Build all formats');
+  console.log('  Open project folder in vscode with Marp extension for editing your presentation');
+  console.log(`  Read ${readmePath} for more information`);
+  console.log('  Enjoy!');
+  console.log();
+}
+
+module.exports = {
+  createProject,
+  validateProjectName,
+  parsePathArg
+};

package/cli/utils/file-utils.js

@@ -0,0 +1,106 @@
+// cli/utils/file-utils.js
+/**
+ * File and directory utilities for meta-package CLI commands
+ * These functions are NOT copied to generated projects
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Expand ~ to home directory
+ * @param {string} input - Path that may start with ~
+ * @returns {string} Expanded path
+ */
+function expandHomePath(input) {
+  if (input.startsWith('~')) {
+    return path.join(os.homedir(), input.slice(1));
+  }
+  return input;
+}
+
+/**
+ * Validate and normalize an output directory path
+ * @param {string} inputPath - Path to validate
+ * @returns {{valid: boolean, error?: string, resolvedPath?: string}} Validation result
+ */
+function validateOutputPath(inputPath) {
+  if (!inputPath || inputPath.trim() === '') {
+    return { valid: false, error: 'Path cannot be empty' };
+  }
+
+  // Check for null bytes (security)
+  if (inputPath.includes('\0')) {
+    return { valid: false, error: 'Path contains null bytes' };
+  }
+
+  const expanded = expandHomePath(inputPath);
+  const resolved = path.resolve(expanded);
+  const normalizedResolved = resolved.toLowerCase();
+
+  // Block system-sensitive directories
+  const sensitiveDirs = ['/etc', '/sys', '/proc', '/root', '/boot'];
+  for (const sensitive of sensitiveDirs) {
+    if (normalizedResolved.startsWith(sensitive.toLowerCase() + path.sep) ||
+        normalizedResolved === sensitive.toLowerCase()) {
+      return { valid: false, error: `Cannot create project in system directory: ${sensitive}` };
+    }
+  }
+
+  // Don't allow creation inside node_modules
+  if (normalizedResolved.includes('node_modules')) {
+    return { valid: false, error: 'Cannot create project inside node_modules directory' };
+  }
+
+  return { valid: true, resolvedPath: resolved };
+}
+
+/**
+ * Recursively copy a directory
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ */
+function copyDir(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Copy optional template files to destination
+ * @param {string} destPath - Destination project path
+ */
+function copyOptionalFiles(destPath) {
+  const optionalPath = path.join(__dirname, '..', '..', 'template-optional');
+
+  // Copy examples.md
+  const examplesSrc = path.join(optionalPath, 'examples.md');
+  const examplesDest = path.join(destPath, 'examples.md');
+  if (fs.existsSync(examplesSrc)) {
+    fs.copyFileSync(examplesSrc, examplesDest);
+  }
+
+  // Copy demo image
+  const demoImageSrc = path.join(optionalPath, 'static', 'demo-image.png');
+  const demoImageDest = path.join(destPath, 'static', 'demo-image.png');
+  if (fs.existsSync(demoImageSrc)) {
+    fs.copyFileSync(demoImageSrc, demoImageDest);
+  }
+}
+
+module.exports = {
+  expandHomePath,
+  validateOutputPath,
+  copyDir,
+  copyOptionalFiles
+};

package/cli/utils/prompt-utils.js

@@ -0,0 +1,89 @@
+// cli/utils/prompt-utils.js
+/**
+ * Prompt utilities for meta-package CLI commands
+ * These functions are NOT copied to generated projects
+ */
+const readline = require('readline');
+
+/**
+ * Ask user if they want to create example slides
+ * @returns {Promise<boolean>} True if user wants examples
+ */
+async function askCreateExamples() {
+  return new Promise((resolve) => {
+    // Interactive mode - ask user
+    if (process.stdin.isTTY) {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+
+      rl.question('Create example slides file? (Y/n) ', (answer) => {
+        rl.close();
+        const normalized = answer.toLowerCase().trim();
+        resolve(normalized !== 'n' && normalized !== 'no');
+      });
+    } else {
+      // Non-interactive mode - read from stdin if there's data
+      let input = '';
+      process.stdin.setEncoding('utf8');
+
+      process.stdin.on('readable', () => {
+        let chunk;
+        while ((chunk = process.stdin.read()) !== null) {
+          input += chunk;
+        }
+      });
+
+      process.stdin.on('end', () => {
+        const normalized = input.toLowerCase().trim();
+        // If input is empty, create examples by default
+        if (normalized === '') {
+          resolve(true);
+        } else {
+          resolve(normalized !== 'n' && normalized !== 'no');
+        }
+      });
+
+      // If stdin has no data immediately, finish
+      if (process.stdin.readableLength === 0) {
+        // Give a short time for data to appear
+        setTimeout(() => {
+          if (input === '') {
+            process.stdin.destroy();
+            resolve(true);
+          }
+        }, 10);
+      }
+    }
+  });
+}
+
+/**
+ * Ask user if they want to add themes to the project
+ * @returns {Promise<boolean>} True if user wants themes
+ */
+async function askAddThemes() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+
+      rl.question('Add custom themes to the project? (Y/n) ', (answer) => {
+        rl.close();
+        const normalized = answer.toLowerCase().trim();
+        resolve(normalized !== 'n' && normalized !== 'no');
+      });
+    } else {
+      // Non-interactive mode: default to false (don't add themes without consent)
+      resolve(false);
+    }
+  });
+}
+
+module.exports = {
+  askCreateExamples,
+  askAddThemes
+};

package/docs/plans/2025-02-19-marp-template-design.md

@@ -0,0 +1,207 @@
+# Marp Presentation Template - Design Document
+
+**Дата:** 2025-02-19
+**Статус:** Draft
+
+## Обзор
+
+npm-пакет `create-marp-presentation` для создания готовых шаблонов Marp-презентаций. Установка через npx одной командой, поддержка статических файлов, генерация в HTML/PDF/PPTX.
+
+## Архитектура и структура
+
+### Структура инициализируемого проекта
+
+```
+my-presentation/
+├── presentation.md      # Главный файл презентации
+├── marp.config.js       # Конфигурация (статические папки, output директория)
+├── package.json         # Зависимости и npm-скрипты
+├── .gitignore           # Исключает output/ и node_modules/
+├── README.md            # Инструкции по использованию
+├── output/              # Сгенерированные файлы (создаётся при сборке)
+├── static/              # Статические файлы по умолчанию
+└── scripts/
+    └── copy-static.js   # Скрипт копирования статики
+```
+
+### Структура npm-пакета
+
+```
+create-marp-presentation/
+├── package.json           # Meta-package с bin полем
+├── index.js               # Точка входа для CLI
+├── template/              # Шаблон проекта
+│   ├── package.json       # Шаблон package.json
+│   ├── marp.config.js     # Шаблон конфига
+│   ├── presentation.md    # Пример презентации
+│   ├── .gitignore         # Шаблон gitignore
+│   ├── README.md          # Шаблон README
+│   ├── static/            # Пустая папка с .gitkeep
+│   └── scripts/
+│       └── copy-static.js # Скрипт копирования статики
+```
+
+## Конфигурация
+
+### marp.config.js
+
+```javascript
+module.exports = {
+  staticFolders: ['static/**', 'assets/**'],  // glob-паттерны для копирования
+  outputDir: 'output',                         // папка для генерации
+}
+```
+
+- `staticFolders` - массив glob-паттернов для поиска статических файлов
+- `outputDir` - папка для генерации (по умолчанию `output`)
+
+## Команды и скрипты
+
+### package.json скрипты
+
+```json
+{
+  "scripts": {
+    "dev": "marp -s . --html",
+    "build:html": "marp presentation.md -o output/index.html --html && npm run copy:static",
+    "build:pdf": "marp presentation.md -o output/presentation.pdf --allow-local-files && npm run copy:static",
+    "build:pptx": "marp presentation.md -o output/presentation.pptx --allow-local-files && npm run copy:static",
+    "build:all": "npm run build:html && npm run build:pdf && npm run build:pptx",
+    "copy:static": "node scripts/copy-static.js",
+    "clean": "rimraf output"
+  },
+  "devDependencies": {
+    "@marp-team/marp-cli": "^4.1.2",
+    "fast-glob": "^3.3.3",
+    "rimraf": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+```
+
+| Команда | Описание |
+|---------|----------|
+| `npm run dev` | Live-предпросмотр с hot-reload |
+| `npm run build:html` | Генерация HTML с встроенным viewer |
+| `npm run build:pdf` | Генерация PDF |
+| `npm run build:pptx` | Генерация PowerPoint |
+| `npm run build:all` | Все форматы подряд |
+| `npm run clean` | Очистка output/ |
+
+## Скрипт копирования статики
+
+### scripts/copy-static.js
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const { globSync } = require('fast-glob');
+
+// Читаем конфиг с дефолтными значениями
+let config;
+try {
+  config = require('../marp.config.js');
+} catch {
+  config = {};
+}
+
+const outputDir = config.outputDir || 'output';
+const staticFolders = config.staticFolders || ['static/**'];
+
+// Создаём output если нет
+if (!fs.existsSync(outputDir)) {
+  fs.mkdirSync(outputDir, { recursive: true });
+}
+
+// Находим файлы по паттернам
+const files = globSync(staticFolders);
+
+// Копируем с сохранением структуры
+for (const file of files) {
+  const relativePath = path.relative(process.cwd(), file);
+  const destPath = path.join(outputDir, relativePath);
+
+  const destDir = path.dirname(destPath);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  fs.copyFileSync(file, destPath);
+}
+
+console.log(`✓ Copied ${files.length} files to ${outputDir}/`);
+```
+
+## Обработка ошибок
+
+### Что обрабатываем
+
+1. **Отсутствие `marp.config.js`** - использовать дефолтные значения
+2. **Несуществующие папки в staticFolders** - пропускать молча
+3. **Пустая staticFolders** - не копировать ничего, не падать
+4. **Конфликт имён файлов** - перезаписывать с предупреждением
+5. **Ошибки копирования** - логировать и продолжать
+
+### Валидация в CLI
+
+- Проверять, что папка для проекта не существует
+- Валидировать имя проекта (нет спецсимволов)
+- Проверять успешность `npm install`
+
+## Использование
+
+### Инициализация
+
+```bash
+npx create-marp-presentation my-presentation
+```
+
+### Редактирование
+
+Откройте `presentation.md` и пишите слайды в Markdown.
+
+### Live-предпросмотр
+
+```bash
+npm run dev
+```
+
+### Сборка
+
+```bash
+npm run build:html    # HTML
+npm run build:pdf     # PDF
+npm run build:pptx    # PowerPoint
+npm run build:all     # Все форматы
+```
+
+### Очистка
+
+```bash
+npm run clean
+```
+
+## Зависимости
+
+| Пакет | Версия | Описание |
+|-------|--------|----------|
+| `@marp-team/marp-cli` | ^4.1.2 | CLI для Marp (требует Node.js 18+) |
+| `fast-glob` | ^3.3.3 | Быстрый glob для поиска файлов |
+| `rimraf` | ^6.0.0 | Кроссплатформенное удаление папок (требует Node.js 20+) |
+
+### Требования к Node.js
+
+**Node.js >= 20.0.0** - обусловлено версией rimraf v6
+
+### Источники
+
+- [@marp-team/marp-cli на npm](https://www.npmjs.com/package/@marp-team/marp-cli)
+- [fast-glob на npm](https://www.npmjs.com/package/fast-glob)
+
+## Тестирование
+
+- Юнит-тесты для copy-static.js
+- Интеграционные тесты для CLI инициализатора
+- Тесты обработки ошибок