@phuthuycoding/markcv 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-09-06
+
+### Fixed
+
+- `markcv --version` reported the version that was hardcoded in the source rather
+  than the one actually installed: 0.1.1 shipped while `--version` still said
+  0.1.0. Both the CLI and the MCP server now read it from `package.json`, and a
+  test fails if the two ever disagree.
+
+## [0.1.1] - 2026-09-06
+
+### Added
+
+- `markcv mcp` subcommand, so MCP clients can use the shape everyone else uses:
+  `npx -y @phuthuycoding/markcv mcp`. With two binaries in the package, the bare
+  `npx` form would otherwise need `--package=…`, which nobody writes from memory.
+
+### Changed
+
+- README now leads with installing from npm, and no longer asks the reader to
+  clone and build. Development setup moved to `CONTRIBUTING.md`.
+- MCP documentation defaults to the `npx` form; the global `markcv-mcp` binary is
+  presented as the faster alternative rather than the only way.
+- `render --no-photo` reports `photo disabled` instead of
+  `photo none (placeholder box)` — not embedding a photo and not finding one are
+  different things.
+
+## [0.1.0] - 2026-09-06
+
+First release.
+
+### Added
+
+- `fit` — explains *why* a CV does not fit a page target, separating content that
+  is genuinely too long from content pushed onto a new page by a bad break, and
+  naming the block responsible with the pixels it wasted.
+- `lint` — audits content rather than formatting: overselling (`spearheaded`,
+  `comprehensive`), **underselling** (`advised on` next to work of real scale),
+  present-tense bullets on finished jobs, skills claimed with no supporting
+  experience, duplicate bullets, IC/manager role mismatch, bullets without a
+  single number, emoji in headings, and over-long bullets.
+- `tailor` — compares a CV against a job description: requirements with no
+  evidence, keywords that appear only under SKILLS, and bullets unrelated to the
+  role.
+- `render` — Markdown to A4 PDF via a system Chrome, with portrait photo
+  auto-detection and a warning when the photo will bloat the PDF.
+- `new`, `list`, `diff`, `build` — master/variant workflow for keeping one content
+  store and cutting tailored copies from it.
+- MCP server exposing seven tools that return structured JSON, so an agent can
+  iterate: edit → `check_fit` → read `culprits` → edit again.
+- Two ATS-safe themes: `classic` and `compact`.
+- Example CVs in `examples/`, with and without a portrait photo.
+
+[Unreleased]: https://github.com/phuthuycoding/markcv/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/phuthuycoding/markcv/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/phuthuycoding/markcv/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/phuthuycoding/markcv/releases/tag/v0.1.0

package/README.md

@@ -19,20 +19,17 @@ Two things set it apart from ordinary markdown→PDF tools:
 ## Install
 
 ```bash
-git clone https://github.com/phuthuycoding/markcv.git
-cd markcv
-npm install          # builds dist/ via the prepare script
-npm link             # puts `markcv` and `markcv-mcp` on your PATH
+npm install -g @phuthuycoding/markcv
 ```
 
-Or from npm:
+The package is scoped; the commands are not. You type `markcv` and `markcv-mcp`.
+
+Or run it without installing:
 
 ```bash
-npm install -g @phuthuycoding/markcv
+npx @phuthuycoding/markcv fit cv.md --pages 2
 ```
 
-The package is scoped, but the commands are not — you still type `markcv` and `markcv-mcp`.
-
 Requires a Chromium-based browser already on your machine (Chrome, Chromium, Edge, Brave). markcv deliberately does **not** download its own Chromium — it uses `puppeteer-core`, so the install stays small. If your browser lives somewhere unusual, point at it with `MARKCV_CHROME=/path/to/chrome`.
 
 ## Usage
@@ -129,61 +126,49 @@ Note what the bullets in those samples have in common: a number, or a before and
 
 Lets an AI agent (Claude Code, Claude Desktop, Cursor…) build and audit CVs on its own.
 
-Install it first (see [Install](#install) above), then point a client at `markcv-mcp`.
-
-Check the server starts (it waits for JSON-RPC on stdin and prints nothing — that is
-correct; Ctrl+C to quit):
-
-```bash
-markcv-mcp
-```
+Nothing to install: `npx` fetches the package on first use and caches it.
 
 ### Register it with a client
 
-After `npm link` the command is simply `markcv-mcp`. Without it, use an **absolute path**
-to `dist/mcp/server.js`. The repo ships `.mcp.json.example` to copy from.
-
-**Claude Code** — add to `.mcp.json` in your project (shared with the team), or `~/.claude.json` (just you):
+**Claude Code** — add to `.mcp.json` in your project (shared with the team), or
+`~/.claude.json` (just you):
 
 ```json
 {
   "mcpServers": {
     "markcv": {
-      "command": "markcv-mcp",
+      "command": "npx",
+      "args": ["-y", "@phuthuycoding/markcv", "mcp"],
       "cwd": "/path/to/your/cv/folder"
     }
   }
 }
 ```
 
-Or add it from the command line:
+Or from the command line:
 
 ```bash
-claude mcp add markcv -- markcv-mcp
+claude mcp add markcv -- npx -y @phuthuycoding/markcv mcp
 claude mcp list          # confirm it connected
 ```
 
 Restart the client afterwards so it picks the server up.
 
-**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), same `mcpServers` shape, then restart the app.
+If you installed the package globally, `"command": "markcv-mcp"` with no `args`
+works too and starts marginally faster. The repo ships `.mcp.json.example` with
+both shapes.
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), same shape,
+then restart the app.
 
 **Cursor** — `.cursor/mcp.json` in the project, same shape.
 
 ### File paths in tool arguments
 
-Every tool takes a file path. Relative paths resolve against the **server process's working directory**, so either pass absolute paths or give the server a `cwd`:
-
-```json
-{
-  "mcpServers": {
-    "markcv": {
-      "command": "node",
-      "args": ["/path/to/markcv/dist/mcp/server.js"],
-      "cwd": "/path/to/your/cv/folder"
-    }
-  }
-}
-```
+Every tool takes a file path, and relative paths resolve against the **server
+process's working directory** — hence the `cwd` above. Without it, pass absolute
+paths instead.
 
 ### Tools
 
@@ -201,7 +186,8 @@ Every tool returns **structured JSON**, not prose — so an agent can loop on it
 
 ### Requirements
 
-Node >= 18 and a Chromium-based browser. If it is in a non-standard location:
+Node >= 18 and a Chromium-based browser (only `render` and `check_fit` need it).
+If it is in a non-standard location:
 
 ```json
 { "mcpServers": { "markcv": { "command": "node", "args": ["..."],

package/dist/cli.js

@@ -8,8 +8,9 @@ import { lint } from "./core/lint.js";
 import { tailor } from "./core/tailor.js";
 import { newVariant, listVariants, diffVariants } from "./core/variants.js";
 import { c, ok, bad, warn, info } from "./ui.js";
+import { VERSION } from "./version.js";
 const program = new Command();
-program.name("markcv").description("Build, fit and audit a CV written in Markdown").version("0.1.0");
+program.name("markcv").description("Build, fit and audit a CV written in Markdown").version(VERSION);
 const pdfNameFor = (md) => md.replace(/\.md$/, ".pdf");
 function printFit(r) {
     const head = r.fits ? ok(`${r.pages} page(s)`) : bad(`${r.pages} pages (target ${r.targetPages})`);
@@ -185,4 +186,13 @@ program
         console.log(`${mark} ${f.padEnd(34)} ${fit.pages} page(s)  ${c.dim(fit.fits ? "" : fit.suggestions[0] ?? "")}`);
     }
 });
+program
+    .command("mcp")
+    .description("Start the MCP server on stdio (for AI agent clients)")
+    .action(async () => {
+    // Importing the server starts it: it connects to stdio and stays there.
+    // Having it as a subcommand is what lets `npx @scope/pkg mcp` work without
+    // the --package dance a second binary would need.
+    await import("./mcp/server.js");
+});
 program.parseAsync(process.argv);

package/dist/mcp/server.js

@@ -10,7 +10,8 @@ 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" });
+import { VERSION } from "../version.js";
+const server = new McpServer({ name: "markcv", version: VERSION });
 /** 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) }],

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Read the version from package.json instead of hardcoding it.
+ * A hardcoded copy silently goes stale the moment a release is cut, and then
+ * `--version` reports one thing while the installed code is another.
+ */
+function readVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const rel of ["../package.json", "../../package.json"]) {
+        try {
+            return JSON.parse(readFileSync(join(here, rel), "utf8")).version;
+        }
+        catch {
+            // try the next candidate: dist/ is one level deeper than src/
+        }
+    }
+    return "0.0.0";
+}
+export const VERSION = readVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuthuycoding/markcv",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Fit, lint and build a CV from Markdown - CLI + MCP server for AI agents",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "dist",
     "themes",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
@@ -26,7 +27,8 @@
     "mcp": "node dist/mcp/server.js",
     "test": "node --test test/*.test.js",
     "prepublishOnly": "npm run build",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "changelog": "node scripts/changelog.mjs"
   },
   "keywords": [
     "cv",