@studyllm/resume-preview 0.0.0-stage → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,335 @@
1
+ /**
2
+ * Route Handlers
3
+ * Single Responsibility: HTTP route handling logic
4
+ * Open/Closed: Easy to add new routes without modifying existing handlers
5
+ */
6
+ import { readFile } from "fs/promises";
7
+ import { join } from "path";
8
+ import { fileURLToPath } from "url";
9
+ import { dirname } from "path";
10
+ import { renderPage } from "./page-renderer.js";
11
+ import { listResumes, deleteResume } from "./resume-service.js";
12
+ import { ROUTES, RESUME_ROUTES, I18N_ROUTES, CONTENT_TYPES, CSP_HEADER, CACHE_CONTROL, TEMPLATE_FILES, ASSET_FILES, I18N_FILE_SUFFIX, } from "./constants.js";
13
+ import { webLogger } from "./logger.js";
14
+ import { getDictionary, isSupportedLocale, resolveLocale } from "./i18n.js";
15
+ const __filename = fileURLToPath(import.meta.url);
16
+ const __dirname = dirname(__filename);
17
+ const PREVIEW_DIR = join(__dirname, "preview");
18
+ /**
19
+ * Serves a static file
20
+ */
21
+ async function serveStaticFile(filePath, contentType, cacheControl = CACHE_CONTROL.NO_STORE) {
22
+ const content = await readFile(filePath, contentType.includes("text") ? "utf-8" : null);
23
+ return { content, contentType, cacheControl };
24
+ }
25
+ /**
26
+ * Reads a query parameter from a raw request URL.
27
+ *
28
+ * @param rawUrl The full request URL, query string included
29
+ * @param name Name of the parameter
30
+ * @returns The value, or undefined when the parameter is absent
31
+ */
32
+ export function getQueryParam(rawUrl, name) {
33
+ if (!rawUrl)
34
+ return undefined;
35
+ const queryStart = rawUrl.indexOf("?");
36
+ if (queryStart === -1)
37
+ return undefined;
38
+ return new URLSearchParams(rawUrl.slice(queryStart + 1)).get(name) ?? undefined;
39
+ }
40
+ /**
41
+ * Gallery Page Handler
42
+ * Renders the main gallery page
43
+ */
44
+ export async function handleGallery(context) {
45
+ const { req, res, port, url } = context;
46
+ try {
47
+ webLogger.debug("Gallery page request");
48
+ const locale = resolveLocale({
49
+ query: getQueryParam(req.url, "lang"),
50
+ acceptLanguage: req.headers["accept-language"],
51
+ });
52
+ const html = await renderPage(TEMPLATE_FILES.GALLERY, { PORT: port }, {
53
+ titleKey: "gallery.pageTitle",
54
+ styles: [ROUTES.SHARED_STYLE, ROUTES.GALLERY_STYLE],
55
+ scripts: [ROUTES.GALLERY_SCRIPT],
56
+ includeNav: false, // Gallery has its own header
57
+ includeFooter: false,
58
+ locale,
59
+ path: url,
60
+ });
61
+ res.writeHead(200, {
62
+ "Content-Type": CONTENT_TYPES.HTML,
63
+ "Content-Security-Policy": CSP_HEADER,
64
+ "Content-Language": locale,
65
+ });
66
+ res.end(html);
67
+ webLogger.info(`Served gallery page (${locale})`);
68
+ }
69
+ catch (error) {
70
+ webLogger.error("Failed to serve gallery page", {
71
+ error: error instanceof Error ? error.message : String(error),
72
+ });
73
+ res.writeHead(500, { "Content-Type": CONTENT_TYPES.PLAIN });
74
+ res.end(`Error loading gallery: ${error instanceof Error ? error.message : String(error)}`);
75
+ }
76
+ }
77
+ /**
78
+ * i18n: serves a locale dictionary to the browser.
79
+ *
80
+ * The locale comes from the URL, so it is checked against the whitelist
81
+ * before it is used — the value never reaches a file path unvalidated.
82
+ */
83
+ export async function handleI18nDictionary(context) {
84
+ const { res, url } = context;
85
+ const raw = url.substring(I18N_ROUTES.DICTIONARY.length);
86
+ if (!raw.endsWith(I18N_FILE_SUFFIX)) {
87
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
88
+ res.end("Not found");
89
+ return;
90
+ }
91
+ const locale = raw.slice(0, -I18N_FILE_SUFFIX.length);
92
+ if (!isSupportedLocale(locale)) {
93
+ webLogger.warn(`Rejected dictionary request for unknown locale: ${locale}`);
94
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
95
+ res.end("Not found");
96
+ return;
97
+ }
98
+ try {
99
+ const dictionary = await getDictionary(locale);
100
+ res.writeHead(200, {
101
+ "Content-Type": CONTENT_TYPES.JSON,
102
+ "Content-Security-Policy": CSP_HEADER,
103
+ "Cache-Control": CACHE_CONTROL.NO_STORE,
104
+ });
105
+ res.end(JSON.stringify(dictionary));
106
+ }
107
+ catch (error) {
108
+ webLogger.error(`Failed to serve dictionary for locale: ${locale}`, {
109
+ error: error instanceof Error ? error.message : String(error),
110
+ });
111
+ res.writeHead(500, { "Content-Type": CONTENT_TYPES.PLAIN });
112
+ res.end("Failed to load dictionary");
113
+ }
114
+ }
115
+ /**
116
+ * API: List Resumes
117
+ * Returns a JSON list of all stored resumes
118
+ */
119
+ export async function handleApiResumes(context) {
120
+ const { res } = context;
121
+ try {
122
+ webLogger.debug("API request: list resumes");
123
+ const resumes = await listResumes();
124
+ const response = {
125
+ resumes,
126
+ count: resumes.length,
127
+ };
128
+ res.writeHead(200, {
129
+ "Content-Type": CONTENT_TYPES.JSON,
130
+ "Cache-Control": CACHE_CONTROL.NO_STORE,
131
+ });
132
+ res.end(JSON.stringify(response));
133
+ webLogger.info(`API: Listed ${resumes.length} resumes`);
134
+ }
135
+ catch (error) {
136
+ webLogger.error("API error: list resumes", {
137
+ error: error instanceof Error ? error.message : String(error),
138
+ });
139
+ res.writeHead(500, { "Content-Type": CONTENT_TYPES.JSON });
140
+ res.end(JSON.stringify({
141
+ error: "Failed to list resumes",
142
+ message: error instanceof Error ? error.message : String(error),
143
+ }));
144
+ }
145
+ }
146
+ /**
147
+ * API: Delete Resume
148
+ * Handles deletion of an individual resume
149
+ */
150
+ export async function handleApiResumeDelete(context) {
151
+ const { req, res, url } = context;
152
+ const deleteMatch = url.match(/^\/api\/resumes\/([^\/]+)$/);
153
+ if (!deleteMatch) {
154
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.JSON });
155
+ res.end(JSON.stringify({ error: "Not found" }));
156
+ return;
157
+ }
158
+ if (req.method !== "DELETE") {
159
+ res.writeHead(405, { "Content-Type": CONTENT_TYPES.JSON });
160
+ res.end(JSON.stringify({ error: "Method not allowed" }));
161
+ return;
162
+ }
163
+ const resumeId = deleteMatch[1];
164
+ try {
165
+ webLogger.debug(`API request: delete resume ${resumeId}`);
166
+ if (!/^[a-zA-Z0-9_-]+$/.test(resumeId)) {
167
+ res.writeHead(400, { "Content-Type": CONTENT_TYPES.JSON });
168
+ res.end(JSON.stringify({ error: "Invalid resume ID" }));
169
+ return;
170
+ }
171
+ await deleteResume(resumeId);
172
+ res.writeHead(200, {
173
+ "Content-Type": CONTENT_TYPES.JSON,
174
+ "Cache-Control": CACHE_CONTROL.NO_STORE,
175
+ });
176
+ res.end(JSON.stringify({ success: true }));
177
+ webLogger.info(`API: Deleted resume ${resumeId}`);
178
+ }
179
+ catch (error) {
180
+ webLogger.error("API error: delete resume", {
181
+ error: error instanceof Error ? error.message : String(error),
182
+ });
183
+ res.writeHead(500, { "Content-Type": CONTENT_TYPES.JSON });
184
+ res.end(JSON.stringify({
185
+ error: "Failed to delete resume",
186
+ message: error instanceof Error ? error.message : String(error),
187
+ }));
188
+ }
189
+ }
190
+ /**
191
+ * Static Asset Handlers
192
+ */
193
+ export async function handleSharedCss(context) {
194
+ const { res } = context;
195
+ try {
196
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.SHARED_STYLE), CONTENT_TYPES.CSS);
197
+ res.writeHead(200, {
198
+ "Content-Type": contentType,
199
+ "Cache-Control": cacheControl,
200
+ });
201
+ res.end(content);
202
+ }
203
+ catch (error) {
204
+ webLogger.error("Failed to serve shared.css", {
205
+ error: error instanceof Error ? error.message : String(error),
206
+ });
207
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
208
+ res.end("Not found");
209
+ }
210
+ }
211
+ export async function handleGalleryCss(context) {
212
+ const { res } = context;
213
+ try {
214
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.GALLERY_STYLE), CONTENT_TYPES.CSS);
215
+ res.writeHead(200, {
216
+ "Content-Type": contentType,
217
+ "Cache-Control": cacheControl,
218
+ });
219
+ res.end(content);
220
+ }
221
+ catch (error) {
222
+ webLogger.error("Failed to serve gallery.css", {
223
+ error: error instanceof Error ? error.message : String(error),
224
+ });
225
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
226
+ res.end("Not found");
227
+ }
228
+ }
229
+ export async function handleGalleryJs(context) {
230
+ const { res } = context;
231
+ try {
232
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.GALLERY_SCRIPT), CONTENT_TYPES.JAVASCRIPT);
233
+ res.writeHead(200, {
234
+ "Content-Type": contentType,
235
+ "Cache-Control": cacheControl,
236
+ });
237
+ res.end(content);
238
+ }
239
+ catch (error) {
240
+ webLogger.error("Failed to serve gallery.js", {
241
+ error: error instanceof Error ? error.message : String(error),
242
+ });
243
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
244
+ res.end("Not found");
245
+ }
246
+ }
247
+ export async function handleResumeCss(context) {
248
+ const { res } = context;
249
+ try {
250
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.RESUME_STYLE), CONTENT_TYPES.CSS);
251
+ res.writeHead(200, {
252
+ "Content-Type": contentType,
253
+ "Cache-Control": cacheControl,
254
+ });
255
+ res.end(content);
256
+ }
257
+ catch (error) {
258
+ webLogger.error("Failed to serve resume.css", {
259
+ error: error instanceof Error ? error.message : String(error),
260
+ });
261
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
262
+ res.end("Not found");
263
+ }
264
+ }
265
+ export async function handleResumeJs(context) {
266
+ const { res } = context;
267
+ try {
268
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.RESUME_SCRIPT), CONTENT_TYPES.JAVASCRIPT);
269
+ res.writeHead(200, {
270
+ "Content-Type": contentType,
271
+ "Cache-Control": cacheControl,
272
+ });
273
+ res.end(content);
274
+ }
275
+ catch (error) {
276
+ webLogger.error("Failed to serve resume.js", {
277
+ error: error instanceof Error ? error.message : String(error),
278
+ });
279
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
280
+ res.end("Not found");
281
+ }
282
+ }
283
+ export async function handleI18nScript(context) {
284
+ const { res } = context;
285
+ try {
286
+ const { content, contentType, cacheControl } = await serveStaticFile(join(PREVIEW_DIR, ASSET_FILES.I18N_SCRIPT), CONTENT_TYPES.JAVASCRIPT);
287
+ res.writeHead(200, {
288
+ "Content-Type": contentType,
289
+ "Cache-Control": cacheControl,
290
+ });
291
+ res.end(content);
292
+ }
293
+ catch (error) {
294
+ webLogger.error("Failed to serve i18n.js", {
295
+ error: error instanceof Error ? error.message : String(error),
296
+ });
297
+ res.writeHead(404, { "Content-Type": CONTENT_TYPES.PLAIN });
298
+ res.end("Not found");
299
+ }
300
+ }
301
+ export const ROUTE_CONFIG = [
302
+ { path: ROUTES.ROOT, exact: true, handler: handleGallery },
303
+ { path: ROUTES.SHARED_STYLE, exact: true, handler: handleSharedCss },
304
+ { path: ROUTES.GALLERY_STYLE, exact: true, handler: handleGalleryCss },
305
+ { path: ROUTES.GALLERY_SCRIPT, exact: true, handler: handleGalleryJs },
306
+ { path: ROUTES.I18N_SCRIPT, exact: true, handler: handleI18nScript },
307
+ { path: I18N_ROUTES.DICTIONARY, handler: handleI18nDictionary },
308
+ // Resume API. The collection is matched exactly and the item route carries
309
+ // its own trailing slash, so "/api/resumesXYZ" cannot reach these handlers.
310
+ { path: RESUME_ROUTES.API, exact: true, handler: handleApiResumes },
311
+ { path: RESUME_ROUTES.API_ITEM, handler: handleApiResumeDelete },
312
+ { path: RESUME_ROUTES.STYLE, exact: true, handler: handleResumeCss },
313
+ { path: RESUME_ROUTES.SCRIPT, exact: true, handler: handleResumeJs },
314
+ ];
315
+ /**
316
+ * Matches a URL to a route configuration
317
+ * @param url Request URL
318
+ * @returns Matched route or null
319
+ */
320
+ export function matchRoute(url) {
321
+ for (const route of ROUTE_CONFIG) {
322
+ if (route.exact) {
323
+ if (url === route.path) {
324
+ return route;
325
+ }
326
+ }
327
+ else {
328
+ if (url.startsWith(route.path)) {
329
+ return route;
330
+ }
331
+ }
332
+ }
333
+ return null;
334
+ }
335
+ //# sourceMappingURL=routes.js.map
package/build/serve.js ADDED
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Standalone server mode (--serve)
3
+ * Starts the live server without the MCP stdio transport,
4
+ * registers the resumes stored on disk, and opens the gallery in the browser.
5
+ */
6
+ import { execFile } from "child_process";
7
+ import { promisify } from "util";
8
+ import { access } from "fs/promises";
9
+ import { ensureLiveServer, addLiveSession } from "./live-server.js";
10
+ import { getResumeFilePath, getOpenCommand } from "./file-utils.js";
11
+ import { listResumes } from "./resume-service.js";
12
+ import { SESSION_NAMESPACES } from "./constants.js";
13
+ const execFileAsync = promisify(execFile);
14
+ /**
15
+ * Registers the stored resumes as live preview sessions so their pages
16
+ * refresh when the file changes.
17
+ */
18
+ async function registerExistingResumes() {
19
+ let registered = 0;
20
+ for (const resume of await listResumes()) {
21
+ const htmlPath = getResumeFilePath(resume.id, "html");
22
+ try {
23
+ await access(htmlPath);
24
+ await addLiveSession(resume.id, htmlPath, SESSION_NAMESPACES.RESUME);
25
+ registered++;
26
+ }
27
+ catch {
28
+ // Skip resumes that have no rendered HTML yet
29
+ }
30
+ }
31
+ return registered;
32
+ }
33
+ export async function startServeMode() {
34
+ const resumeCount = await registerExistingResumes();
35
+ const port = await ensureLiveServer();
36
+ const galleryUrl = `http://localhost:${port}/`;
37
+ console.log(`Serving ${resumeCount} resume(s) at ${galleryUrl}`);
38
+ const { command, args } = getOpenCommand(galleryUrl);
39
+ try {
40
+ await execFileAsync(command, args);
41
+ }
42
+ catch {
43
+ console.warn(`Could not open browser automatically. Open ${galleryUrl} manually.`);
44
+ }
45
+ }
46
+ //# sourceMappingURL=serve.js.map
package/build/types.js ADDED
@@ -0,0 +1,5 @@
1
+ /**
2
+ * TypeScript type definitions for resume-preview
3
+ */
4
+ export {};
5
+ //# sourceMappingURL=types.js.map
package/package.json CHANGED
@@ -1,6 +1,65 @@
1
1
  {
2
2
  "name": "@studyllm/resume-preview",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "3.1.0",
4
+ "description": "MCP server for previewing and exporting resumes in Claude Code",
5
+ "main": "build/index.js",
6
+ "type": "module",
7
+ "bin": {
8
+ "resume-preview": "build/index.js"
9
+ },
10
+ "files": [
11
+ "build/**/*.js",
12
+ "build/**/*.html",
13
+ "build/**/*.css",
14
+ "build/**/*.json",
15
+ "build/**/*.svg"
16
+ ],
17
+ "scripts": {
18
+ "build": "tsc && node scripts/copy-preview.mjs",
19
+ "start": "node build/index.js",
20
+ "dev": "tsc --watch",
21
+ "test": "vitest",
22
+ "test:e2e": "npm run build && node .claude/dev/e2e-mcp.mjs && node .claude/dev/e2e-web.mjs",
23
+ "format": "prettier --write .",
24
+ "format:check": "prettier --check .",
25
+ "prepublishOnly": "npm run build"
26
+ },
27
+ "keywords": [
28
+ "mcp",
29
+ "resume",
30
+ "cv",
31
+ "claude",
32
+ "pdf"
33
+ ],
34
+ "author": "studyllm",
35
+ "license": "MIT",
36
+ "engines": {
37
+ "node": ">=22.13.0"
38
+ },
39
+ "repository": {
40
+ "type": "git",
41
+ "url": "git+https://github.com/studyllm/resume-preview.git"
42
+ },
43
+ "homepage": "https://github.com/studyllm/resume-preview#readme",
44
+ "bugs": {
45
+ "url": "https://github.com/studyllm/resume-preview/issues"
46
+ },
47
+ "publishConfig": {
48
+ "access": "public"
49
+ },
50
+ "dependencies": {
51
+ "@modelcontextprotocol/sdk": "^1.18.2",
52
+ "puppeteer": "^25.16.0",
53
+ "ws": "^8.18.3"
54
+ },
55
+ "overrides": {
56
+ "puppeteer": "^25.16.0"
57
+ },
58
+ "devDependencies": {
59
+ "@types/node": "^26.0.0",
60
+ "@types/ws": "^8.18.1",
61
+ "prettier": "^3.6.2",
62
+ "typescript": "^7.0.2",
63
+ "vitest": "^5.0.5"
64
+ }
65
+ }