resuml 1.20.1 → 2.0.0

package/DOCS.md

@@ -0,0 +1,314 @@
+# resuml: detailed documentation
+
+> For the short intro, see [README.md](README.md). For the web app, go to [resuml.app](https://resuml.app).
+
+## Table of contents
+
+- [Why YAML](#why-yaml)
+- [Installation](#installation)
+- [CLI commands and options](#cli-commands-and-options)
+- [ATS analysis](#ats-analysis)
+- [Themes](#themes)
+- [Example YAML structure](#example-yaml-structure)
+- [CI/CD integration](#cicd-auto-build-on-push)
+- [AI agent integration (MCP)](#ai-agent-integration-mcp)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Why YAML
+
+| | YAML | JSON |
+|---|---|---|
+| **Comments** | ✅ `# explain your choices` | ❌ Not supported |
+| **Multi-line strings** | ✅ `summary: >-` block syntax | ❌ Escape everything |
+| **Readability** | ✅ Clean, minimal syntax | ⚠️ Brackets & quotes everywhere |
+| **Diffing** | ✅ Clean git diffs | ⚠️ Noisy diffs |
+| **Compatibility** | ✅ Valid JSON Resume schema | ✅ Native |
+
+YAML is a superset of JSON, so your resume stays fully compatible with the [JSON Resume](https://jsonresume.org/) ecosystem.
+
+## Installation
+
+```bash
+npm install -g resuml
+```
+
+Requires Node.js ≥ 20 and npm ≥ 10.
+
+## CLI commands and options
+
+| Command | Description |
+|---------|-------------|
+| `validate` | Validate resume data against the JSON Resume schema |
+| `validate --ats` | Run ATS compatibility analysis |
+| `tojson` | Convert YAML to JSON |
+| `render` | Render the resume to HTML using a theme |
+| `pdf` | Render to PDF |
+| `dev` | Dev server with hot-reload |
+| `mcp` | Start the MCP server for AI agents |
+
+### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--resume` | `-r` | Input YAML file(s) or directory |
+| `--output` | `-o` | Output file path |
+| `--theme` | `-t` | Theme name |
+| `--port` | `-p` | Dev server port (default: 3000) |
+| `--language` | | Locale (default: `en`) |
+| `--debug` | | Detailed errors |
+| `--ats` | | Run ATS analysis (with `validate`) |
+| `--jd` | | Path to job description file (with `--ats`) |
+| `--ats-threshold` | | Minimum score (0-100); exits 1 if below |
+| `--format` | | Output format for validate: `text` or `json` |
+
+### Quick start
+
+```bash
+resuml validate --resume resume.yaml
+resuml tojson   --resume resume.yaml --output resume.json
+resuml render   --resume resume.yaml --theme stackoverflow --output resume.html
+```
+
+## ATS analysis
+
+Deterministic, offline ATS (Applicant Tracking System) checks. No API keys, no LLMs.
+
+```bash
+# Basic ATS score
+resuml validate --resume resume.yaml --ats
+
+# Match against a job description
+resuml validate --resume resume.yaml --ats --jd job-description.txt
+
+# CI gate: fail if below threshold
+resuml validate --resume resume.yaml --ats --ats-threshold 75
+
+# Machine-readable output
+resuml validate --resume resume.yaml --ats --format json
+```
+
+### What it checks
+
+11 deterministic checks across 3 categories.
+
+**Contact information**
+- Complete contact details (name, email, phone, city)
+- LinkedIn profile present
+
+**Content quality**
+- Professional summary (length and presence)
+- Work highlights (≥ 2 per entry)
+- Action verbs (highlights start with strong verbs)
+- Quantified impact (numbers / percentages / metrics)
+- No first-person pronouns
+
+**Resume structure**
+- Date consistency (no unexplained gaps > 6 months)
+- Skills populated (≥ 3 categories with keywords)
+- Education completeness
+- Essential sections present
+
+### Job description matching
+
+Passing `--jd` extracts keywords from the job description using TF-based ranking with stem matching, then compares to your resume. You get:
+
+- **Match percentage**: how many JD keywords appear in your resume
+- **Matched keywords**: what you already cover
+- **Missing keywords**: what to consider adding
+- **Extra keywords**: skills in your resume the JD didn't mention
+
+### Scoring
+
+| Score | Rating | Meaning |
+|-------|--------|---------|
+| 90-100 | Excellent | Well-optimized for ATS |
+| 75-89 | Good | Minor improvements possible |
+| 60-74 | Needs Work | Several issues to address |
+| 0-59 | Poor | Significant improvements needed |
+
+With a JD: final score = 60% generic checks + 40% keyword match.
+
+### Multi-language
+
+Supports English and German (language-specific action verbs and pronouns). Use `--language`:
+
+```bash
+resuml validate --resume lebenslauf.yaml --ats --language de
+```
+
+## Themes
+
+resuml supports any `jsonresume-theme-*` package from npm. Install a theme, then pass its name to `--theme`:
+
+```bash
+npm install jsonresume-theme-stackoverflow
+resuml render --resume resume.yaml --theme stackoverflow
+```
+
+| Theme | Install | Style |
+|-------|---------|-------|
+| [stackoverflow](https://github.com/francoislaberge/jsonresume-theme-stackoverflow) | `npm i jsonresume-theme-stackoverflow` | Clean, professional |
+| [elegant](https://github.com/mudassir0909/jsonresume-theme-elegant) | `npm i jsonresume-theme-elegant` | Modern |
+| [kendall](https://github.com/LinuxBozo/jsonresume-theme-kendall) | `npm i jsonresume-theme-kendall` | Minimal |
+| [flat](https://github.com/erming/jsonresume-theme-flat) | `npm i jsonresume-theme-flat` | Flat |
+| [onepage](https://github.com/aonemd/jsonresume-theme-onepage) | `npm i jsonresume-theme-onepage` | Single-page |
+
+Browse all at [jsonresume.org/themes](https://jsonresume.org/themes/). The web app at [resuml.app](https://resuml.app) bundles 300+ of them and renders live.
+
+## Example YAML structure
+
+```yaml
+basics:
+  name: John Doe
+  label: Software Engineer
+  email: john@example.com
+  summary: Experienced software engineer...
+  location:
+    city: San Francisco
+    countryCode: US
+  profiles:
+    - network: GitHub
+      url: https://github.com/johndoe
+
+work:
+  - name: Tech Corp
+    position: Senior Engineer
+    startDate: 2020-01-15
+    endDate: 2023-12-31
+    summary: Led development of...
+    highlights:
+      - Reduced latency by 40%
+      - Led team of 8 engineers
+
+education:
+  - institution: University
+    area: Computer Science
+    studyType: Bachelor
+    startDate: 2014-09-01
+    endDate: 2018-06-01
+
+skills:
+  - name: Languages
+    level: Expert
+    keywords: [TypeScript, Python, Go]
+```
+
+See [examples/](examples/) for more.
+
+## CI/CD: Auto-build on push
+
+```yaml
+# .github/workflows/resume.yml
+name: Build Resume
+
+on:
+  push:
+    paths: ['resume.yaml', 'resume/*.yaml']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - run: npm install -g resuml
+      - run: npm install jsonresume-theme-stackoverflow
+
+      # Fail the job if ATS score < 75
+      - run: resuml validate --resume resume.yaml --ats --ats-threshold 75
+
+      - run: resuml render --resume resume.yaml --theme stackoverflow --output resume.html
+      - run: resuml tojson --resume resume.yaml --output resume.json
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: resume
+          path: |
+            resume.html
+            resume.json
+```
+
+## AI agent integration (MCP)
+
+resuml ships with a [Model Context Protocol](https://modelcontextprotocol.io/) server so Claude Code, Claude Desktop, Cursor, Copilot, or any MCP-compatible client can use it directly.
+
+### Setup
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "resuml": {
+      "command": "npx",
+      "args": ["resuml", "mcp"]
+    }
+  }
+}
+```
+
+Or run standalone:
+
+```bash
+resuml mcp
+```
+
+### Using it from Claude Code
+
+Once configured, Claude Code can call every resuml capability through natural language. For example:
+
+> "I saved the job ad as `jd.txt`. Tailor my resume at `resume.yaml` to match it, iterate until the ATS score is ≥ 80, render with the stackoverflow theme, and export a PDF."
+
+Claude Code will:
+
+1. Validate the current YAML.
+2. Run the ATS check with the JD.
+3. Edit the YAML to close keyword gaps.
+4. Re-check until the target score is met.
+5. Render the HTML and export the PDF.
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `resuml_init_resume` | Generate a starter YAML template |
+| `resuml_validate` | Validate resume YAML against the JSON Resume schema |
+| `resuml_ats_check` | ATS analysis + JD keyword matching |
+| `resuml_render` | Render to HTML using a theme (supports `locale`) |
+| `resuml_list_themes` | List available themes and install status |
+| `resuml_export_pdf` | Export as PDF (supports `margin`, `locale`) |
+
+### Resources
+
+| URI | Description |
+|-----|-------------|
+| `resuml://schema/json-resume` | Full JSON Resume schema reference |
+| `resuml://docs/ats-scoring` | ATS scoring rubric, checks, weights, and tips |
+| `resuml://themes/catalog` | Available themes with descriptions |
+
+### Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `tailor-resume-to-jd` | Tailor a resume for a specific job description |
+| `optimize-ats-score` | Analyze and improve an existing resume's ATS score |
+| `review-resume` | Comprehensive review + improvement suggestions |
+
+## Troubleshooting
+
+**Validation errors**
+- Check YAML indentation and required fields
+- Run with `--debug` for stack traces
+
+**Theme rendering issues**
+- Ensure the theme is installed (`npm install jsonresume-theme-<name>`)
+- Third-party themes may have their own bugs. Try a different theme.
+- The web app at [resuml.app](https://resuml.app) pre-checks themes and flags broken ones
+
+**Dev server issues**
+- The default port is 3000. Pass `--port` to override.

package/README.md

@@ -66,11 +66,16 @@ Claude will generate the YAML, validate it, iterate until the score clears, and
 ```bash
 npm install -g resuml
 
+# install a theme on demand (any jsonresume-theme-* package)
+npm install -g jsonresume-theme-stackoverflow
+
 resuml validate --resume resume.yaml --ats --jd job.txt
 resuml render   --resume resume.yaml --theme stackoverflow --output resume.html
 resuml pdf      --resume resume.yaml --theme stackoverflow --output resume.pdf
 ```
 
+`resuml pdf` and snapshot rendering need Playwright. Install it once with `npm install -g playwright` (it's an optional peer dep so the base install stays slim).
+
 **Minimal `resume.yaml`:**
 
 ```yaml
@@ -89,14 +94,14 @@ work:
       - Led team of 12 engineers
 ```
 
-Full CLI reference, Node.js API, ATS rubric, CI/CD setup, and every MCP tool live in **[DOCS.md](DOCS.md)**.
+Full CLI reference, ATS rubric, CI/CD setup, and every MCP tool live in **[DOCS.md](DOCS.md)**.
 
 ---
 
 ## Requirements
 
 - Node.js ≥ 20, npm ≥ 10
-- Nothing else. Validation, ATS, rendering, and PDF all run locally
+- Optional: `playwright` for `resuml pdf`
 
 ## Contributing
 

package/dist/{chunk-KRJMZ2RQ.js → chunk-GRIYYG45.js}

@@ -1,3 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/core.ts
 import { parse } from "yaml";
 import merge from "lodash.merge";
@@ -1614,8 +1620,242 @@ function analyzeAts(resume, options = {}) {
   };
 }
 
+// src/utils/themeLoader.ts
+import { execFileSync } from "child_process";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+function installTheme(packageName) {
+  try {
+    execFileSync("npm", ["install", packageName], {
+      stdio: ["inherit", "pipe", "pipe"],
+      encoding: "utf8"
+    });
+  } catch (error) {
+    throw new Error(`Failed to install ${packageName}: ${error.message}`);
+  }
+}
+function loadTheme(themeName, options) {
+  let jsonResumeThemeName;
+  let nativeThemeName;
+  const autoInstall = options?.autoInstall !== false;
+  try {
+    jsonResumeThemeName = themeName.startsWith("jsonresume-theme-") ? themeName : `jsonresume-theme-${themeName}`;
+    try {
+      return require2(jsonResumeThemeName);
+    } catch (_jsonResumeError) {
+      nativeThemeName = `@resuml/theme-${themeName}`;
+      try {
+        return require2(nativeThemeName);
+      } catch (_nativeError) {
+        if (!autoInstall) {
+          throw new Error(
+            `Theme package ${jsonResumeThemeName} or ${nativeThemeName} not found in node_modules.
+Please install the theme package manually.`
+          );
+        }
+        console.log(`\u{1F4E6} Theme ${jsonResumeThemeName} not found. Installing...`);
+        try {
+          installTheme(jsonResumeThemeName);
+          console.log(`\u2705 Successfully installed ${jsonResumeThemeName}`);
+          return require2(jsonResumeThemeName);
+        } catch (installError) {
+          throw new Error(
+            `Failed to auto-install theme ${jsonResumeThemeName}: ${installError.message}`
+          );
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Failed to auto-install")) {
+      throw error;
+    }
+    throw new Error(`Theme package ${themeName} not found`);
+  }
+}
+
+// src/utils/resumeTemplate.ts
+function generateResumeYaml(name, email, label) {
+  return `# =============================================================================
+# Resume - Generated by resuml
+# Documentation: https://github.com/phoinixi/resuml
+# Schema: https://jsonresume.org/schema/
+# =============================================================================
+
+# --- Basic Information ---
+basics:
+  name: '${name}'
+  label: '${label}'
+  # image: 'https://example.com/photo.jpg'
+  email: '${email}'
+  # phone: '+1-555-123-4567'
+  # url: 'https://yourwebsite.com'
+  summary: >-
+    Write a short professional summary here.
+    This supports multi-line strings in YAML.
+  location:
+    # address: '123 Main Street'
+    # postalCode: '12345'
+    city: 'Your City'
+    countryCode: 'US'
+    # region: 'Your State'
+  profiles:
+    - network: 'LinkedIn'
+      username: 'your-username'
+      url: 'https://linkedin.com/in/your-username'
+    - network: 'GitHub'
+      username: 'your-username'
+      url: 'https://github.com/your-username'
+
+# --- Work Experience ---
+work:
+  - name: 'Company Name'
+    position: 'Job Title'
+    url: 'https://company.com'
+    startDate: '2020-01-01'
+    # endDate: '2023-12-31'  # Omit for current position
+    summary: 'Brief description of your role and responsibilities.'
+    highlights:
+      - 'Key achievement or responsibility'
+      - 'Another notable accomplishment'
+
+# --- Education ---
+education:
+  - institution: 'University Name'
+    url: 'https://university.edu'
+    area: 'Field of Study'
+    studyType: 'Bachelor of Science'
+    startDate: '2014-09-01'
+    endDate: '2018-06-01'
+    # score: '3.8'
+    courses:
+      - 'Relevant Course 1'
+      - 'Relevant Course 2'
+
+# --- Skills ---
+skills:
+  - name: 'Programming Languages'
+    level: 'Expert'
+    keywords:
+      - 'JavaScript'
+      - 'TypeScript'
+      - 'Python'
+  - name: 'Frameworks'
+    level: 'Advanced'
+    keywords:
+      - 'React'
+      - 'Node.js'
+
+# --- Projects ---
+# projects:
+#   - name: 'Project Name'
+#     description: 'Brief project description'
+#     highlights:
+#       - 'Key feature or result'
+#     keywords:
+#       - 'Technology Used'
+#     startDate: '2023-01-01'
+#     endDate: '2023-06-30'
+#     url: 'https://github.com/you/project'
+#     roles:
+#       - 'Developer'
+#     type: 'application'
+
+# --- Languages ---
+# languages:
+#   - language: 'English'
+#     fluency: 'Native speaker'
+#   - language: 'Spanish'
+#     fluency: 'Professional working proficiency'
+
+# --- Interests ---
+# interests:
+#   - name: 'Open Source'
+#     keywords:
+#       - 'Contributing'
+#       - 'Community'
+
+# --- References ---
+# references:
+#   - name: 'Jane Smith'
+#     reference: 'It was a pleasure working with...'
+
+# --- Awards ---
+# awards:
+#   - title: 'Award Name'
+#     date: '2023-01-01'
+#     awarder: 'Organization'
+#     summary: 'Description of the award'
+
+# --- Certificates ---
+# certificates:
+#   - name: 'Certificate Name'
+#     date: '2023-01-01'
+#     issuer: 'Issuing Organization'
+#     url: 'https://example.com/cert'
+
+# --- Publications ---
+# publications:
+#   - name: 'Publication Title'
+#     publisher: 'Publisher'
+#     releaseDate: '2023-01-01'
+#     url: 'https://example.com/publication'
+#     summary: 'Brief description'
+
+# --- Volunteer ---
+# volunteers:
+#   - organization: 'Organization Name'
+#     position: 'Volunteer Role'
+#     url: 'https://organization.com'
+#     startDate: '2022-01-01'
+#     summary: 'Description of volunteer work'
+#     highlights:
+#       - 'Notable contribution'
+`;
+}
+
+// src/utils/themeInfo.ts
+import { createRequire as createRequire2 } from "module";
+var KNOWN_THEMES = [
+  { name: "stackoverflow", pkg: "jsonresume-theme-stackoverflow", description: "Stack Overflow inspired theme" },
+  { name: "elegant", pkg: "jsonresume-theme-elegant", description: "Elegant and professional" },
+  { name: "react", pkg: "jsonresume-theme-react", description: "Built with React components" },
+  { name: "even", pkg: "jsonresume-theme-even", description: "Clean and minimal" },
+  { name: "kendall", pkg: "jsonresume-theme-kendall", description: "Simple and clean layout" },
+  { name: "macchiato", pkg: "jsonresume-theme-macchiato", description: "Beautiful and modern" },
+  { name: "flat", pkg: "jsonresume-theme-flat", description: "Flat design theme" },
+  { name: "class", pkg: "jsonresume-theme-class", description: "Classic professional look" },
+  { name: "short", pkg: "jsonresume-theme-short", description: "Compact single-page resume" },
+  { name: "spartan", pkg: "jsonresume-theme-spartan", description: "Minimalist Spartan design" },
+  { name: "paper", pkg: "jsonresume-theme-paper", description: "Paper-like clean design" },
+  { name: "onepage", pkg: "jsonresume-theme-onepage", description: "One page resume layout" }
+];
+function isThemeInstalled(pkg) {
+  try {
+    const req = createRequire2(process.cwd() + "/");
+    req.resolve(pkg);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getInstalledVersion(pkg) {
+  try {
+    const req = createRequire2(process.cwd() + "/");
+    const pkgJson = req(`${pkg}/package.json`);
+    return pkgJson.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export {
+  __export,
   processResumeData,
-  analyzeAts
+  analyzeAts,
+  loadTheme,
+  generateResumeYaml,
+  KNOWN_THEMES,
+  isThemeInstalled,
+  getInstalledVersion
 };
-//# sourceMappingURL=chunk-KRJMZ2RQ.js.map
+//# sourceMappingURL=chunk-GRIYYG45.js.map