create-marp-presentation 1.1.0 → 1.2.1

package/docs/theme-management.md

@@ -0,0 +1,261 @@
+# Theme Management Guide
+
+This guide explains how to use the theme management system in your Marp presentation project.
+
+## Overview
+
+The theme management system provides a simple way to:
+- Add pre-built themes to your project
+- List available and installed themes
+- Switch between themes
+- Create custom themes
+- Integrate with VSCode for live preview
+
+## Available Themes
+
+The following themes are available in the template:
+
+- **beam** - Clean, modern theme with progress bar
+- **default-clean** - Minimal variation of default theme
+- **gaia-dark** - Dark version of the Gaia theme
+- **marpx** - Extended version of Marp's default theme
+- **socrates** - Educational theme with clear typography
+- **uncover-minimal** - Minimal reveal-style theme
+
+### System Themes
+
+These built-in Marp themes are always available:
+- **default** - Marp's default theme
+- **gaia** - Clean, professional theme
+- **uncover** - Slide-by-slide reveal theme
+
+## Commands
+
+### List Themes
+
+```bash
+npm run theme:list
+```
+
+This shows:
+- Available themes in the theme library
+- Installed themes in your project's `themes/` directory
+- Dependencies for each theme
+
+### Add Themes
+
+```bash
+npm run theme:add
+```
+
+You'll be prompted to:
+1. Select themes from the available list
+2. Resolve any conflicts (if themes with the same name exist)
+3. Confirm the selection
+
+The command will:
+- Copy theme files to your `themes/` directory
+- Resolve dependencies automatically
+- Update VSCode settings
+- Skip themes that would conflict (unless using `--force`)
+
+**Options:**
+```bash
+npm run theme add --force      # Overwrite existing themes
+npm run theme add --no-vscode  # Skip VSCode settings update
+```
+
+### Set Active Theme
+
+```bash
+npm run theme:set <theme-name>
+```
+
+This will:
+- Update the `theme` value in `presentation.md` frontmatter
+- Add the theme to VSCode settings (for custom themes)
+- Warn if the theme is not installed
+
+**Examples:**
+```bash
+npm run theme:set beam
+npm run theme:set default
+npm run theme:set gaia
+```
+
+### Create Custom Theme
+
+```bash
+npm run theme:create <theme-name>
+```
+
+You'll be prompted to:
+1. Select a parent theme to base your theme on
+2. Choose a directory location (root, subfolder, or new folder)
+
+The command will:
+- Create a new CSS file in the appropriate location
+- Add the theme directive and parent import
+- Update VSCode settings if needed
+
+**Example:**
+```bash
+npm run theme:create my-brand
+# Select parent: beam
+# Select location: root
+# Creates: themes/my-brand.css
+```
+
+## Theme File Structure
+
+Themes are organized in the `themes/` directory:
+
+```
+my-presentation/
+├── themes/
+│   ├── beam.css
+│   ├── marpx.css
+│   └── custom/
+│       └── my-theme.css
+└── presentation.md
+```
+
+### Theme File Format
+
+Each theme CSS file must include:
+1. A theme directive: `/* @theme theme-name */`
+2. Optional parent imports: `@import "parent-theme";`
+
+**Example:**
+```css
+/* @theme my-custom */
+@import "beam";
+
+:root {
+  --color-primary: #3498db;
+  --color-secondary: #2ecc71;
+}
+
+section {
+  background: linear-gradient(135deg, var(--color-primary), var(--color-secondary));
+}
+```
+
+## VSCode Integration
+
+The theme management system automatically updates VSCode settings for live preview support.
+
+### Settings Location
+
+`.vscode/settings.json`:
+```json
+{
+  "markdown.marp.themes": [
+    "themes/beam/beam.css",
+    "themes/marpx/marpx.css"
+  ]
+}
+```
+
+### How It Works
+
+- When you add themes, they're added to the settings
+- When you set an active theme, it's added to the settings
+- System themes (default, gaia, uncover) are not added (built-in)
+- Use `--no-vscode` to skip this behavior
+
+## Manual Theme Management
+
+You can also manage themes manually:
+
+### Add a Theme Manually
+
+1. Copy your theme CSS file to the `themes/` directory (e.g., `themes/your-theme/your-theme.css`)
+2. Add the theme directive: `/* @theme your-theme-name */`
+3. Update `.vscode/settings.json` if needed:
+   ```json
+   {
+     "markdown.marp.themes": ["themes/your-theme/your-theme.css"]
+   }
+   ```
+
+### Switch Theme Manually
+
+Edit `presentation.md`:
+```yaml
+---
+marp: true
+theme: your-theme-name
+---
+```
+
+## Troubleshooting
+
+### Theme Not Found
+
+If you get a "Theme not found" error:
+1. Check if the theme is installed: `npm run theme:list`
+2. Add the theme if missing: `npm run theme:add`
+3. Verify the theme name matches exactly
+
+### Live Preview Not Working
+
+If VSCode live preview doesn't show your theme:
+1. Check `.vscode/settings.json` exists
+2. Verify the theme path is correct
+3. Reload the VSCode window
+
+### Dependencies Not Found
+
+Warning about missing dependencies is expected for system themes (default, gaia, uncover). These are built into Marp CLI and don't need to be in your project.
+
+## Best Practices
+
+1. **Use Descriptive Names**: Name themes clearly (e.g., `brand-primary`, `presentation-dark`)
+2. **Organize Themes**: Use subfolders for many themes
+3. **Document Dependencies**: Include parent theme imports in comments
+4. **Test Themes**: Always test with `npm run dev` after changing themes
+5. **Version Control**: Commit your custom themes to git
+
+## Advanced Usage
+
+### Creating Theme Variants
+
+Create multiple variants based on the same parent:
+
+```bash
+npm run theme:create brand-light  # Parent: beam
+npm run theme:create brand-dark   # Parent: beam
+```
+
+Edit the themes to differentiate them:
+
+```css
+/* themes/brand-light.css */
+/* @theme brand-light */
+@import "beam";
+:root { --bg-color: #ffffff; }
+
+/* themes/brand-dark.css */
+/* @theme brand-dark */
+@import "beam";
+:root { --bg-color: #1a1a1a; }
+```
+
+### Conditional Themes
+
+Use different themes for different presentations:
+
+```bash
+# For external presentations
+npm run theme:set brand-professional
+
+# For internal workshops
+npm run theme:set brand-casual
+```
+
+## References
+
+- [Marp Theme Documentation](https://marp.app/docs/theming)
+- [Marp CLI GitHub](https://github.com/marp-team/marp-cli)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)

package/index.js

@@ -1,184 +1,131 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const readline = require('readline');
-
-const projectName = process.argv[2];
-
-if (!projectName) {
-  console.error('Please provide a project name:');
-  console.error('  npx create-marp-presentation <project-name>');
-  process.exit(1);
-}
-
-// Валидация имени проекта
-const validName = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
-if (!validName.test(projectName)) {
-  console.error(`Invalid project name: "${projectName}"`);
-  console.error('Project name must be lowercase, contain only letters, numbers, and hyphens.');
-  process.exit(1);
-}
-
-const projectPath = path.join(process.cwd(), projectName);
-
-// Запрос на создание примеров слайдов
-async function askCreateExamples() {
-  return new Promise((resolve) => {
-    // Интерактивный режим — спрашиваем пользователя
-    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 {
-      // Неинтерактивный режим — читаем из stdin если есть данные
-      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 (normalized === '') {
-          resolve(true);
-        } else {
-          resolve(normalized !== 'n' && normalized !== 'no');
-        }
-      });
-
-      // Если stdin не имеет данных сразу, завершаем
-      if (process.stdin.readableLength === 0) {
-        // Даем небольшое время на появление данных
-        setTimeout(() => {
-          if (input === '') {
-            process.stdin.destroy();
-            resolve(true);
-          }
-        }, 10);
-      }
-    }
-  });
-}
+/**
+ * create-marp-presentation - CLI entry point
+ * Supports dual entry points:
+ *   1. npx create-marp-presentation <name> [--path <dir>] - Create new project
+ *   2. npx create-marp-presentation theme:add <path> [themes...] - Add themes to existing project
+ */
 
-// Validate path to prevent traversal attacks
-const resolvedPath = path.resolve(projectPath);
-if (!resolvedPath.startsWith(path.resolve(process.cwd()))) {
-  console.error('Invalid project path: path traversal detected.');
-  process.exit(1);
-}
+const path = require('path');
 
-// Проверка существования папки
-if (fs.existsSync(projectPath)) {
-  console.error(`Directory "${projectName}" already exists.`);
-  process.exit(1);
-}
+const { createProject, validateProjectName, parsePathArg } = require('./cli/commands/create-project');
+const { addThemesToExistingProject } = require('./cli/commands/add-themes-cli');
+const { validateOutputPath } = require('./cli/utils/file-utils');
 
-// Получаем путь к template
+// Paths
 const templatePath = path.join(__dirname, 'template');
-
-// Рекурсивное копирование директории
-const 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);
-    }
-  }
-};
-
-// Копирование опциональных файлов
-const copyOptionalFiles = (destPath) => {
-  const optionalPath = path.join(__dirname, 'template-optional');
-
-  // Копируем examples.md
-  const examplesSrc = path.join(optionalPath, 'examples.md');
-  const examplesDest = path.join(destPath, 'examples.md');
-  if (fs.existsSync(examplesSrc)) {
-    fs.copyFileSync(examplesSrc, examplesDest);
+const themesLibraryPath = path.join(__dirname, 'themes');
+
+/**
+ * Show usage information
+ * @param {boolean} isError - If true, write to stderr and exit with error code
+ */
+function showUsage(isError = false) {
+  const output = isError ? console.error : console.log;
+  output('Please provide a project name:');
+  output('  npx create-marp-presentation <project-name> [--path <output-dir>]');
+  output('');
+  output('Or use the theme:add command:');
+  output('  npx create-marp-presentation theme:add <project-path> [theme-names...]');
+  output('');
+  output('Examples:');
+  output('  npx create-marp-presentation my-project');
+  output('  npx create-marp-presentation my-project --path /tmp');
+  output('  npx create-marp-presentation my-project --path ~/projects');
+  output('  npx create-marp-presentation theme:add ./my-project');
+  output('  npx create-marp-presentation theme:add ./my-project beam marpx');
+  output('');
+
+  if (isError) {
+    process.exit(1);
   }
+}
 
-  // Копируем демо-изображение
-  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);
+/**
+ * Handle theme:add command
+ * @param {string[]} args - Command arguments
+ */
+async function handleThemeAdd(args) {
+  const targetPath = args[0];
+  if (!targetPath) {
+    console.error('Usage: npx create-marp-presentation theme:add <project-path> [theme-names...]');
+    process.exit(1);
   }
-};
 
-console.log(`Creating Marp presentation: ${projectName}`);
-console.log();
+  const themeNames = args.slice(1); // Additional arguments are theme names
 
-// Основной async flow
-(async () => {
   try {
-    // Запрашиваем создание примеров
-    const createExamples = await askCreateExamples();
-
-    // Создаём папку проекта
-    fs.mkdirSync(projectPath, { recursive: true });
-
-    // Рекурсивно копируем template
-    copyDir(templatePath, projectPath);
-
-    console.log('✓ Project created');
-
-    // Копируем опциональные файлы
-    if (createExamples) {
-      copyOptionalFiles(projectPath);
-      console.log('✓ Example slides added');
-      console.log('✓ Demo image added to static/');
-    }
-    console.log();
-
-    // Запускаем npm install
-    console.log('Installing dependencies...');
-    const installResult = spawnSync('npm', ['install'], {
-      cwd: projectPath,
-      stdio: 'inherit',
+    await addThemesToExistingProject(targetPath, {
+      themesLibraryPath,
+      themeNames: themeNames.length > 0 ? themeNames : null
     });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
 
-    if (installResult.status !== 0) {
-      console.error();
-      console.error('Failed to install dependencies.');
-      console.error('Please run "cd ' + projectName + ' && npm install" manually.');
+/**
+ * Handle project creation command
+ * @param {string} projectName - Name of the project
+ * @param {string[]} args - Remaining arguments (e.g., --path)
+ */
+async function handleProjectCreation(projectName, args = []) {
+  // Parse --path argument if present
+  const { pathIndex } = parsePathArg(args);
+  let outputPath = process.cwd();
+
+  if (pathIndex !== null) {
+    const pathArg = args[pathIndex + 1];
+    const validation = validateOutputPath(pathArg);
+    if (!validation.valid) {
+      console.error(`Invalid --path: "${pathArg}"`);
+      console.error(validation.error);
       process.exit(1);
     }
+    outputPath = validation.resolvedPath;
+  }
 
-    console.log();
-    console.log('✓ Dependencies installed');
-    console.log();
-    console.log('Next steps:');
-    console.log(`  cd ${projectName}`);
-    console.log('  npm run dev        # Start live preview');
-    if (createExamples) {
-      console.log('  marp examples.md   # Preview example slides');
+  try {
+    await createProject(projectName, {
+      outputPath,
+      templatePath,
+      themesLibraryPath
+    });
+  } catch (error) {
+    if (error.message === 'Invalid project name' || error.message === 'Project directory already exists') {
+      process.exit(1);
     }
-    console.log('  npm run build:all  # Build all formats');
-    console.log();
-
-  } catch (err) {
-    console.error('Error creating project:', err.message);
+    console.error('Error creating project:', error.message);
     process.exit(1);
   }
-})();
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case 'theme:add':
+      await handleThemeAdd(args);
+      break;
+
+    case undefined:
+      showUsage(true); // Exit with error code 1
+      break;
+
+    default:
+      // Treat as project name (backward compatible)
+      await handleProjectCreation(command, args);
+      break;
+  }
+}
+
+// Run
+main().catch(error => {
+  console.error('Unexpected error:', error.message);
+  process.exit(1);
+});