@phuthuycoding/markcv 0.1.0

package/dist/core/variants.js

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, basename, dirname, join } from "node:path";
+/** Start a tailored copy from a master file. It only copies; trimming is up to you or the agent. */
+export function newVariant(master, name) {
+    const src = resolve(master);
+    if (!existsSync(src))
+        throw new Error(`Master file not found: ${master}`);
+    const dest = join(dirname(src), `cv-${name}.md`);
+    if (existsSync(dest))
+        throw new Error(`Already exists: ${dest}`);
+    const raw = readFileSync(src, "utf8").replace(/^<!--[\s\S]*?-->\n*/, "");
+    writeFileSync(dest, raw, "utf8");
+    return dest;
+}
+export function listVariants(dir) {
+    return readdirSync(resolve(dir))
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => {
+        const raw = readFileSync(join(resolve(dir), f), "utf8");
+        const lines = raw.split("\n");
+        return {
+            file: f,
+            name: basename(f, ".md"),
+            lines: lines.length,
+            bullets: lines.filter((l) => /^\s*[*-]\s+/.test(l)).length,
+            sections: lines.filter((l) => l.startsWith("## ")).map((l) => l.slice(3).trim()),
+        };
+    });
+}
+/** Compare two versions: which bullets exist on only one side. */
+export function diffVariants(a, b) {
+    const read = (p) => readFileSync(resolve(p), "utf8").split("\n")
+        .filter((l) => /^\s*[*-]\s+/.test(l))
+        .map((l) => l.replace(/^\s*[*-]\s+/, "").replace(/\*\*/g, "").trim());
+    const A = read(a), B = read(b);
+    const setB = new Set(B), setA = new Set(A);
+    return {
+        onlyInA: A.filter((l) => !setB.has(l)),
+        onlyInB: B.filter((l) => !setA.has(l)),
+        shared: A.filter((l) => setB.has(l)).length,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { render, loadTheme, pageBoxFromCss } from "./core/render.js";
+export { analyseFit } from "./core/fit.js";
+export { lint } from "./core/lint.js";
+export { tailor } from "./core/tailor.js";
+export { newVariant, listVariants, diffVariants } from "./core/variants.js";
+export { parseCv, renderBody, buildHtml } from "./core/markdown.js";
+export { photoBlock } from "./core/photo.js";
+export { findChrome } from "./core/browser.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { render, loadTheme, pageBoxFromCss } from "./core/render.js";
+export { analyseFit } from "./core/fit.js";
+export { lint } from "./core/lint.js";
+export { tailor } from "./core/tailor.js";
+export { newVariant, listVariants, diffVariants } from "./core/variants.js";
+export { parseCv, renderBody, buildHtml } from "./core/markdown.js";
+export { photoBlock } from "./core/photo.js";
+export { findChrome } from "./core/browser.js";
+export * from "./types.js";

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { tmpdir } from "node:os";
+import { render } from "../core/render.js";
+import { analyseFit } from "../core/fit.js";
+import { lint } from "../core/lint.js";
+import { tailor } from "../core/tailor.js";
+import { newVariant, listVariants, diffVariants } from "../core/variants.js";
+const server = new McpServer({ name: "markcv", version: "0.1.0" });
+/** Every tool returns JSON so an agent can loop on the result, rather than prose for a human. */
+const json = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+const fail = (message) => ({
+    content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }],
+    isError: true,
+});
+const mdFile = z.string().describe("Path to the CV markdown file");
+server.registerTool("render_cv", {
+    title: "Build a PDF from a markdown CV",
+    description: "Render the CV to PDF (and HTML). Returns the real page count plus layout numbers to verify against.",
+    inputSchema: {
+        file: mdFile,
+        pdf: z.string().optional().describe("Output PDF path; defaults to the .md path with a .pdf extension"),
+        theme: z.enum(["classic", "compact"]).optional(),
+        target_pages: z.number().int().min(1).max(10).optional(),
+    },
+}, async ({ file, pdf, theme, target_pages }) => {
+    if (!existsSync(resolve(file)))
+        return fail(`File not found: ${file}`);
+    const res = await render({
+        input: file,
+        pdf: pdf ?? file.replace(/\.md$/, ".pdf"),
+        theme,
+        targetPages: target_pages,
+    });
+    const fit = analyseFit(res.measure, res.pageBox, res.pdfPages ?? 0, target_pages);
+    return json({
+        pdf: res.pdfPath,
+        pages: res.pdfPages,
+        photo: res.photoFile,
+        photo_warning: res.photoWarning,
+        fit,
+    });
+});
+server.registerTool("check_fit", {
+    title: "Why the CV does not fit",
+    description: "Separates two very different causes: content that is too long, versus bad page breaks. " +
+        "Returns the overflow, the blocks pushed onto a new page, the pixels wasted, and concrete suggestions.",
+    inputSchema: {
+        file: mdFile,
+        target_pages: z.number().int().min(1).max(10).default(2),
+        theme: z.enum(["classic", "compact"]).optional(),
+    },
+}, async ({ file, target_pages, theme }) => {
+    if (!existsSync(resolve(file)))
+        return fail(`File not found: ${file}`);
+    const tmpPdf = join(tmpdir(), `markcv-mcp-${Date.now()}.pdf`);
+    const res = await render({ input: file, pdf: tmpPdf, theme, targetPages: target_pages });
+    return json(analyseFit(res.measure, res.pageBox, res.pdfPages ?? 0, target_pages));
+});
+server.registerTool("lint_cv", {
+    title: "Audit CV content",
+    description: "Finds unverifiable self-praise, UNDERSTATED claims relative to the real work, present-tense " +
+        "bullets on finished jobs, skills with no supporting evidence, duplicate bullets, and IC/manager role mismatch.",
+    inputSchema: { file: mdFile },
+}, async ({ file }) => {
+    if (!existsSync(resolve(file)))
+        return fail(`File not found: ${file}`);
+    const findings = lint(readFileSync(resolve(file), "utf8"));
+    return json({
+        total: findings.length,
+        errors: findings.filter((f) => f.severity === "error").length,
+        warnings: findings.filter((f) => f.severity === "warn").length,
+        findings,
+    });
+});
+server.registerTool("tailor_to_jd", {
+    title: "Compare the CV against a job description",
+    description: "Points out JD requirements with no evidence, keywords that live only under SKILLS, and unrelated " +
+        "bullets (cut those first, before cutting anything valuable).",
+    inputSchema: {
+        file: mdFile,
+        jd_file: z.string().optional().describe("Path to a job-description file"),
+        jd_text: z.string().optional().describe("Job description pasted inline"),
+    },
+}, async ({ file, jd_file, jd_text }) => {
+    if (!existsSync(resolve(file)))
+        return fail(`File not found: ${file}`);
+    const jd = jd_text ?? (jd_file && existsSync(resolve(jd_file)) ? readFileSync(resolve(jd_file), "utf8") : "");
+    if (!jd.trim())
+        return fail("Either jd_file or jd_text is required");
+    return json(tailor(readFileSync(resolve(file), "utf8"), jd));
+});
+server.registerTool("list_variants", {
+    title: "List CV versions",
+    description: "Every .md file in a folder with its line count, bullet count and section list.",
+    inputSchema: { dir: z.string().default(".") },
+}, async ({ dir }) => {
+    if (!existsSync(resolve(dir)))
+        return fail(`Directory not found: ${dir}`);
+    return json(listVariants(dir));
+});
+server.registerTool("new_variant", {
+    title: "Start a tailored version",
+    description: "Copy a master CV to cv-<name>.md so it can be trimmed for one specific role.",
+    inputSchema: { master: mdFile, name: z.string().regex(/^[a-z0-9-]+$/) },
+}, async ({ master, name }) => {
+    try {
+        return json({ created: newVariant(master, name) });
+    }
+    catch (e) {
+        return fail(e.message);
+    }
+});
+server.registerTool("diff_variants", {
+    title: "Compare two CV versions",
+    description: "Which bullets exist on only one side — use it to see what a tailored copy dropped.",
+    inputSchema: { a: mdFile, b: mdFile },
+}, async ({ a, b }) => {
+    if (!existsSync(resolve(a)) || !existsSync(resolve(b)))
+        return fail("One of the two files was not found");
+    return json(diffVariants(a, b));
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+/** Types shared by the CLI and the MCP server. */
+export interface RenderOptions {
+    /** Source markdown file. */
+    input: string;
+    /** Output PDF path. Omit to only produce HTML. */
+    pdf?: string;
+    /** Output HTML path. Omit to use a temp file. */
+    html?: string;
+    /** Theme name under themes/, defaults to "classic". */
+    theme?: string;
+    /** Portrait photo. Omit to auto-detect photo.* next to the markdown file. */
+    photo?: string | null;
+    /** Target page count, used to report pass/fail. */
+    targetPages?: number;
+}
+/** A block pushed onto a new page, with the gap it left behind. */
+export interface CulpritBlock {
+    title: string;
+    tag: string;
+    /** Vertical position in the content flow (px). */
+    top: number;
+    /** Empty space left at the bottom of the previous page (px). */
+    wastedPx: number;
+    page: number;
+}
+export interface FitReport {
+    pages: number;
+    targetPages?: number;
+    fits: boolean;
+    /** Real content height (px, measured at the printable width). */
+    contentHeight: number;
+    /** Usable height of a single page (px). */
+    usablePerPage: number;
+    /** Space left over; negative means the content is too long. */
+    slackPx: number;
+    /** Whether the content would fit if no block were pushed to a new page. */
+    contentWouldFit: boolean;
+    /** Pixels wasted by blocks pushed onto a new page. */
+    wastedByBreaksPx: number;
+    culprits: CulpritBlock[];
+    /** Suggested actions, most effective first. */
+    suggestions: string[];
+}
+export type Severity = "error" | "warn" | "info";
+export interface LintFinding {
+    rule: string;
+    severity: Severity;
+    line: number;
+    /** The text that triggered this finding. */
+    excerpt: string;
+    message: string;
+    suggestion?: string;
+}
+export interface TailorReport {
+    /** JD requirements with no evidence anywhere in the CV. */
+    missing: {
+        keyword: string;
+        hint: string;
+    }[];
+    /** Keywords that appear only under SKILLS, with no experience backing them. */
+    unsupported: {
+        keyword: string;
+        hint: string;
+    }[];
+    /** Bullets unrelated to the JD - cut these before cutting anything valuable. */
+    irrelevant: {
+        line: number;
+        excerpt: string;
+    }[];
+    /** JD keywords the CV genuinely backs up. */
+    covered: {
+        keyword: string;
+        evidenceLine: number;
+    }[];
+    score: number;
+}
+export interface CvDoc {
+    /** Raw markdown. */
+    raw: string;
+    /** Lines, for line-number lookups. */
+    lines: string[];
+    /** Level-2 sections in document order. */
+    sections: {
+        title: string;
+        start: number;
+        end: number;
+    }[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Types shared by the CLI and the MCP server. */
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,13 @@
+export declare const c: {
+    bold: (s: string | number) => string;
+    dim: (s: string | number) => string;
+    red: (s: string | number) => string;
+    green: (s: string | number) => string;
+    yellow: (s: string | number) => string;
+    blue: (s: string | number) => string;
+    cyan: (s: string | number) => string;
+};
+export declare const ok: (s: string) => string;
+export declare const bad: (s: string) => string;
+export declare const warn: (s: string) => string;
+export declare const info: (s: string) => string;

package/dist/ui.js

@@ -0,0 +1,16 @@
+/** Terminal colours, disabled automatically when output is piped elsewhere. */
+const on = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (on ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+export const c = {
+    bold: wrap("1"),
+    dim: wrap("2"),
+    red: wrap("31"),
+    green: wrap("32"),
+    yellow: wrap("33"),
+    blue: wrap("34"),
+    cyan: wrap("36"),
+};
+export const ok = (s) => `${c.green("✓")} ${s}`;
+export const bad = (s) => `${c.red("✗")} ${s}`;
+export const warn = (s) => `${c.yellow("!")} ${s}`;
+export const info = (s) => `${c.dim("·")} ${s}`;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@phuthuycoding/markcv",
+  "version": "0.1.0",
+  "description": "Fit, lint and build a CV from Markdown - CLI + MCP server for AI agents",
+  "type": "module",
+  "bin": {
+    "markcv": "dist/cli.js",
+    "markcv-mcp": "dist/mcp/server.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "themes",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "mcp": "node dist/mcp/server.js",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "cv",
+    "resume",
+    "markdown",
+    "pdf",
+    "mcp",
+    "ats",
+    "lint",
+    "page-fit"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "commander": "^12.1.0",
+    "markdown-it": "^14.1.0",
+    "puppeteer-core": "^23.10.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phuthuycoding/markcv.git"
+  },
+  "bugs": {
+    "url": "https://github.com/phuthuycoding/markcv/issues"
+  },
+  "homepage": "https://github.com/phuthuycoding/markcv#readme",
+  "author": "phuthuycoding",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/themes/classic.css

@@ -0,0 +1,40 @@
+/* classic - the default. Single column, no emoji, real text layer: safe for ATS parsers. */
+@page { size: A4; margin: 11mm 13mm; }
+* { box-sizing: border-box; }
+body {
+  font-family: -apple-system, "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-size: 9pt; line-height: 1.36; color: #1b1b1b; margin: 0;
+  -webkit-font-smoothing: antialiased;
+}
+.header { position: relative; min-height: var(--photo-h, 0); padding-right: var(--photo-gutter, 0); }
+.photo {
+  position: absolute; top: 0; right: 0;
+  width: var(--photo-w, 30mm); height: var(--photo-h, 40mm);
+  object-fit: cover; border-radius: 2px;
+}
+.photo-empty {
+  position: absolute; top: 0; right: 0;
+  width: var(--photo-w, 30mm); height: var(--photo-h, 40mm);
+  border: 1px dashed #c2c2c2; border-radius: 2px; background: #fafafa;
+  display: flex; align-items: center; justify-content: center;
+  color: #a8a8a8; font-size: 7pt; letter-spacing: .04em; text-align: center;
+}
+h1 { font-size: 19pt; font-weight: 700; letter-spacing: -.01em; margin: 0 0 5px; color: #0f0f0f; }
+h2 {
+  font-size: 9.5pt; font-weight: 700; text-transform: uppercase; letter-spacing: .09em;
+  color: #0f0f0f; border-bottom: 1.3px solid #2b2b2b;
+  padding-bottom: 2px; margin: 9px 0 5px; break-after: avoid;
+}
+h3 { font-size: 10pt; font-weight: 700; color: #111; margin: 6px 0 1px; break-after: avoid; }
+p { margin: 0 0 2px; }
+.contacts { margin-bottom: 2px; }
+p.contact { white-space: nowrap; font-size: 8.6pt; color: #333; margin: 0; line-height: 1.5; }
+p.meta { font-size: 8.8pt; color: #444; margin: 0 0 3px; }
+ul { margin: 2px 0 4px; padding-left: 14px; }
+ul ul { margin: 1px 0; }
+li { margin-bottom: 1.4px; break-inside: avoid; }
+strong { font-weight: 600; color: #000; }
+em { font-style: italic; }
+code { font-family: "SF Mono", Menlo, monospace; font-size: 8.8pt; color: #222; }
+hr { display: none; }
+a { color: inherit; text-decoration: none; }

package/themes/compact.css

@@ -0,0 +1,30 @@
+/* compact - same as classic but tighter, for squeezing into fewer pages. */
+@page { size: A4; margin: 10mm 12mm; }
+* { box-sizing: border-box; }
+body {
+  font-family: -apple-system, "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-size: 8.6pt; line-height: 1.32; color: #1b1b1b; margin: 0;
+}
+.header { position: relative; min-height: var(--photo-h, 0); padding-right: var(--photo-gutter, 0); }
+.photo { position: absolute; top: 0; right: 0; width: var(--photo-w, 28mm); height: var(--photo-h, 37mm); object-fit: cover; }
+.photo-empty {
+  position: absolute; top: 0; right: 0; width: var(--photo-w, 28mm); height: var(--photo-h, 37mm);
+  border: 1px dashed #c2c2c2; background: #fafafa; display: flex; align-items: center;
+  justify-content: center; color: #a8a8a8; font-size: 6.5pt;
+}
+h1 { font-size: 17pt; font-weight: 700; margin: 0 0 4px; }
+h2 {
+  font-size: 9pt; font-weight: 700; text-transform: uppercase; letter-spacing: .08em;
+  border-bottom: 1.2px solid #2b2b2b; padding-bottom: 2px; margin: 7px 0 4px; break-after: avoid;
+}
+h3 { font-size: 9.4pt; font-weight: 700; margin: 5px 0 1px; break-after: avoid; }
+p { margin: 0 0 2px; }
+.contacts { margin-bottom: 2px; }
+p.contact { white-space: nowrap; font-size: 8.2pt; color: #333; margin: 0; line-height: 1.45; }
+p.meta { font-size: 8.4pt; color: #444; margin: 0 0 2px; }
+ul { margin: 2px 0 3px; padding-left: 13px; }
+li { margin-bottom: 1px; break-inside: avoid; }
+strong { font-weight: 600; color: #000; }
+code { font-family: "SF Mono", Menlo, monospace; font-size: 8.4pt; }
+hr { display: none; }
+a { color: inherit; text-decoration: none; }