resumectl 0.0.0-stage → 0.1.0

package/skills/resumectl/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: resumectl
+description: Write, rewrite, tailor, score, or review résumé/CV bullets, summaries, sections, or a complete résumé against a target role or job description. Use with resumectl to turn verified career evidence into concise LaTeX content and validate the rendered PDF.
+---
+
+# Resume Methodology
+
+## Inputs and evidence
+
+Identify the target role or job description (JD), the candidate's career evidence, and the `.tex` file to edit. Use information already provided. If the JD is missing, proceed with a general review and state that the résumé has not yet been tailored to a specific role.
+
+- Every employer, responsibility, ownership claim, technology and metric must be traceable to the user's materials.
+- Never guess a metric. Use verified scope or observable outcomes; ask the user when an essential fact is missing.
+- Placeholders such as `[N endpoints]` and `[latency %]` belong only in drafts awaiting confirmation. Replace or remove them before delivery.
+- Examples in this skill illustrate writing structure. They are not facts about the candidate.
+- Treat the user-designated `.tex` file and its `\input` files as the content source. Do not maintain a separate Markdown résumé that can drift out of sync.
+
+## Writing workflow
+
+### 1. Map the role requirements
+
+Group the JD into four categories and identify the candidate's evidence for each requirement:
+
+| Category | Extract |
+|---|---|
+| Required capabilities | Technologies, systems skills and domain knowledge |
+| Business problems | Cost, reliability, latency, automation and user experience |
+| Expected proof | Production delivery, scale, personal ownership and customer impact |
+| Interview opportunities | Projects with design decisions, tradeoffs and results the candidate can explain |
+
+Record `JD requirement → available evidence → gap`. Keep unsupported requirements as gaps; do not present them as demonstrated abilities.
+
+### 2. Select the strongest evidence
+
+Evaluate each item by whether it helps a recruiter judge the candidate's fit within 30 seconds:
+
+- Lead with the most relevant accomplishments and clearest evidence of contribution.
+- Remove statements that only describe participation, duties or tools. Rewrite them around outcomes when evidence supports doing so.
+- When two bullets prove the same capability, keep the stronger one.
+- Keep coursework and routine projects only when they fill a gap in evidence for the target role.
+- Do not add weak content just to fill a page.
+
+Choose the emphasis for the role without changing the facts: AI Engineer roles prioritize agents, RAG, evaluations and production reliability; SWE roles prioritize backend systems, system design, performance and engineering quality; Data roles prioritize pipelines, experiments, data quality and decision impact.
+
+### 3. Write verifiable bullets
+
+Default structure: **Action + technical mechanism + result + business or user impact**. Alternatively, compress STAR into context, action and result.
+
+- Start with a concrete action verb: Built, Designed, Shipped, Optimized, Automated, Reduced, Migrated or Instrumented.
+- Use past tense for completed accomplishments. Make personal contributions explicit without implying sole ownership of a team's result.
+- Avoid openings that describe only duties, such as Responsible for, Participated in, Helped or Worked on.
+- Use the JD's terminology when it accurately describes the work. Place relevant keywords in the first five words when natural, without keyword stuffing.
+- Explain the technical choice or mechanism instead of merely listing tools.
+- Support impact with verified metrics, scope or observable results. A missing number is not a reason to invent one.
+
+Example structure, with illustrative numbers:
+
+> Built REST API caching across 12 endpoints, reducing p95 latency 38% and improving checkout reliability.
+
+Compress in this order: preserve the action, mechanism and result → remove empty adjectives and repeated context → use clear technical abbreviations → keep one impact clause. Split a bullet only when the resulting bullets prove distinct capabilities.
+
+**Target 1–2 rendered lines with a sufficiently full final line.** Do not substitute character counts or estimated Times font widths for PDF measurements. Shared defaults allow at most two lines and require at least 80% final-line fill; use the effective configuration for the actual thresholds. Never add unsupported scope, metrics or filler to fill a line.
+
+### 4. Write a role-specific summary
+
+When the user needs a summary, use **Identity → Proof → Target/Vision**:
+
+1. Identity: a role description aligned with the JD.
+2. Proof: the strongest relevant accomplishment or evidence.
+3. Target: the work the candidate wants to continue doing, aligned with the role's business goals.
+
+Template: `[Role identity] with [relevant strengths]; shipped [verified proof]; focused on [JD-aligned goal].`
+
+Use one or two sentences. Remove generic labels such as passionate, fast learner and results-driven. The summary should establish positioning beyond what the experience section already says; suggest omitting it when it adds no such value. Enforce a character limit only when the user requests one. Otherwise, check the SUMMARY section's line and fill limits and the document's page budget. A fixed character count does not imply a fixed rendered length.
+
+### 5. Review and score
+
+Score each bullet from 0 to 2 on each dimension:
+
+| Dimension | 0 | 1 | 2 |
+|---|---|---|---|
+| Role relevance | Generic | Partly relevant | Directly maps to the JD |
+| Ownership | Unclear | Partly explicit | Personal action is explicit |
+| Technical mechanism | Missing | Tool named | Design or implementation explained |
+| Result evidence | Missing | Vague | Concrete number or observable result |
+| Impact | Missing | Implied | Clear user, business or team benefit |
+
+Prioritize bullets scoring 8–10. For a score of 7, address the weakest dimension. Rewrite or remove bullets below 7. Scores help select content; they do not replace fact checking or rendered validation.
+
+## resumectl workflow
+
+Run the CLI as `bunx resumectl@0.1.0 <command>`. Bun downloads it on first use, so nothing needs cloning. Inside the resumectl repository, `bun run resumectl <command>` is equivalent.
+
+### Set up once
+
+Run `bunx resumectl@0.1.0 doctor` before writing anything, and fix failures with the user:
+
+- **`bunx` not found, or Bun below 1.3:** ask the user to install Bun (`curl -fsSL https://bun.sh/install | bash`) or run `bun upgrade`.
+- **`TeX engine` missing:** recommend Tectonic, a ~16 MB program that downloads only the TeX packages it needs. Install it with `brew install tectonic` on macOS, or `curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh` elsewhere ([other options](https://tectonic-typesetting.github.io/install.html)). Ask before installing anything.
+- **`TeX dependencies` missing:** the user already has TeX Live or TinyTeX. Run `tlmgr install titlesec enumitem pgf tex-gyre` with their approval.
+
+Repeat `doctor` until it passes. With Tectonic, the first build needs network access and can take a few minutes while packages download; run it with a timeout of at least 5 minutes. Later builds take seconds.
+
+### Build and revise
+
+For a new résumé, run `bunx resumectl@0.1.0 init <directory> --style sans`, then replace the placeholder content. `init` refuses to overwrite existing résumé source or configuration. Use `--style serif` only if the user asks for it.
+
+```bash
+bunx resumectl@0.1.0 config show path/to/resume.tex --json
+bunx resumectl@0.1.0 build path/to/resume.tex --json
+bunx resumectl@0.1.0 check path/to/resume.tex --json
+```
+
+Read `config show` before editing:
+
+- `sections.<title>.editable: true` permits rewriting that section's body while preserving facts.
+- `false` or an unlisted section provides no editing permission through configuration. Edit it only when the user explicitly authorizes the change.
+- `checks: false` disables that section's length checks; it does not grant editing permission.
+- Do not lower thresholds, shrink fonts or change the page budget merely to make checks pass without the user's authorization.
+
+List items are measured automatically. Wrap standalone paragraphs and `tabularx` X-column descriptions in `\resumeentry{...}`. Do not wrap `\item` again or nest lists or entries.
+
+Rebuild after every content or layout change. Use each failing entry's `section`, `index`, `lines`, `lastLineFill` and `status` to guide revision:
+
+1. Too many lines: follow the compression order and preserve the strongest evidence.
+2. Sparse final line: first try compressing to one line. Alternatively, add a mechanism or result already supported by the user's materials; never invent content.
+3. Overflow or excess pages: remove weaker content and inspect long links, unbreakable text and tables. Do not make the résumé difficult to read just to pass.
+4. Private-use character mappings: inspect the font or template; do not ignore broken text copying.
+5. Missing measurements or mismatched hashes: rebuild rather than editing `.resumectl.json` by hand.
+
+All three quality gates must pass: actual rendered content length and overflow, page count, and PDF private-use character mappings. `check` uses the existing PDF and its matching `.resumectl.json` manifest. Content or layout changes require a rebuild; changes only to checking thresholds can be rechecked directly.
+
+## Delivery checks
+
+- Support the role's priorities with real evidence and list any unresolved factual gaps.
+- Give each bullet an action, mechanism and result, with the strongest evidence first.
+- Do not alter dates, job titles, schools or other facts to make the layout fit.
+- Remove all draft placeholders from the final file.
+- Require a fresh build with exit code 0 and all three gates reporting PASS. Record the PDF path and verification result.
+- Inspect the actual PDF for hierarchy, spacing, reading order, and the final-line fill of one- or two-line bullets. If no visual inspection was performed, state that explicitly.
+- Deliver the main changes, factual gaps and generated files. Passing the gates does not guarantee acceptance or compatibility with every ATS parser.
+
+[Source](https://www.youtube.com/watch?v=4eYzTGxZazw)

package/src/cli/main.ts

@@ -0,0 +1,108 @@
+import { parseArgs } from "node:util";
+import { basename, join, resolve } from "node:path";
+import { cleanIntermediates, compile, tectonicCacheReady, texEngine } from "../rendering/compile.ts";
+import { resolveConfig, type ConfigInput } from "../project/config.ts";
+import { formatReport, runGates } from "../quality/gates.ts";
+import { InputError } from "../errors.ts";
+import { initConfig, initProject } from "../project/init.ts";
+import { doctor, formatDoctor } from "../project/doctor.ts";
+
+const USAGE = `resumectl — configure, render and check a résumé
+
+Usage
+  resumectl init [directory] [--style <serif|sans>] [--paper <a4|letter>] [--json]
+  resumectl doctor [--json]
+  resumectl config init [--config <path>]
+  resumectl config show [resume.tex] [--config <path>] [--json]
+  resumectl build <resume.tex> [options]
+  resumectl check <resume.tex> [options]
+
+Options
+  --config <path>             use this YAML config; otherwise discover resume.config.yaml
+  --style <serif|sans>        override the rendered style
+  --paper <a4|letter>         override the paper size
+  --section <name>            check only this section (default: all configured sections)
+  --max-lines <n>             override maximum rendered lines for selected sections
+  --min-last-line-fill <0–1>   override minimum last-line fill for selected sections
+  --max-pages <n>             page limit (default: 1)
+  --out-dir <dir>             output directory, relative to the current directory
+  --pdf <path>                existing PDF to check (check only)
+  --keep-logs                 keep compiler intermediates after a passing build
+  --no-keep-logs              override keepLogs: true from config
+  --json                     machine-readable report, including effective config
+  -h, --help
+
+Precedence: CLI > config > documentclass > defaults.
+Exit codes: 0 success · 1 quality/compile/dependency failure · 2 invalid input.`;
+
+export async function main(args: string[]): Promise<number> {
+  const { values: v, positionals } = parseArgs({
+    args, allowPositionals: true,
+    options: {
+      config: { type: "string" }, pdf: { type: "string" }, "out-dir": { type: "string" },
+      style: { type: "string" }, paper: { type: "string" }, section: { type: "string" },
+      "max-lines": { type: "string" }, "min-last-line-fill": { type: "string" }, "max-pages": { type: "string" },
+      "keep-logs": { type: "boolean" }, "no-keep-logs": { type: "boolean" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+    },
+  });
+  const [command, arg, texArg] = positionals;
+  if (v.help || !command) { console.log(USAGE); return v.help ? 0 : 2; }
+  if (v["keep-logs"] && v["no-keep-logs"]) throw new InputError("choose either --keep-logs or --no-keep-logs");
+  if (command === "init") {
+    if (positionals.length > 2 || Object.keys(v).some(k => !["style", "paper", "json"].includes(k))) {
+      throw new InputError("init accepts a directory, --style, --paper and --json");
+    }
+    const result = await initProject(arg, {
+      ...(v.style !== undefined ? { style: v.style as "serif" | "sans" } : {}),
+      ...(v.paper !== undefined ? { paper: v.paper as "a4" | "letter" } : {}),
+    });
+    console.log(v.json ? JSON.stringify(result, null, 2)
+      : `Created ${result.texPath} and ${result.configPath}\nReplace the placeholders, then run resumectl build "${result.texPath}".`);
+    return 0;
+  }
+  if (command === "doctor") {
+    if (positionals.length > 1 || Object.keys(v).some(k => k !== "json")) throw new InputError("doctor accepts only --json");
+    const report = await doctor();
+    console.log(v.json ? JSON.stringify(report, null, 2) : formatDoctor(report));
+    return report.pass ? 0 : 1;
+  }
+  if (command === "config" && arg === "init") {
+    if (positionals.length > 2 || Object.keys(v).some(k => !["config", "json"].includes(k))) throw new InputError("config init accepts only --config and --json");
+    const result = await initConfig(v.config);
+    console.log(v.json ? JSON.stringify(result, null, 2) : `Created ${result.configPath}`);
+    return 0;
+  }
+  const show = command === "config" && arg === "show";
+  if (!show && command !== "build" && command !== "check") throw new InputError(`unknown command; use --help`);
+  if (positionals.length > (show ? 3 : 2)) throw new InputError("too many positional arguments");
+  const texPath = show ? texArg : arg;
+  if (!show && !texPath) throw new InputError(`${command} needs a .tex file`);
+  if (v.pdf && command !== "check") throw new InputError("--pdf is only supported by check");
+  const overrides: ConfigInput = { layout: {}, checks: { bullets: {} }, build: {} };
+  if (v.style !== undefined) overrides.layout!.style = v.style as "serif" | "sans";
+  if (v.paper !== undefined) overrides.layout!.paper = v.paper as "a4" | "letter";
+  if (v.section !== undefined) overrides.checks!.section = v.section;
+  if (v["max-pages"] !== undefined) overrides.checks!.maxPages = Number(v["max-pages"]);
+  if (v["max-lines"] !== undefined) overrides.checks!.bullets!.maxLines = Number(v["max-lines"]);
+  if (v["min-last-line-fill"] !== undefined) overrides.checks!.bullets!.minLastLineFill = v["min-last-line-fill"].trim() ? Number(v["min-last-line-fill"]) : NaN;
+  if (v["out-dir"] !== undefined) overrides.build!.outDir = v["out-dir"];
+  if (v["keep-logs"] !== undefined) overrides.build!.keepLogs = v["keep-logs"];
+  if (v["no-keep-logs"]) overrides.build!.keepLogs = false;
+  const resolved = await resolveConfig({ texPath, configPath: v.config, overrides });
+  if (show) { console.log(JSON.stringify(resolved, null, 2)); return 0; }
+  const { config } = resolved;
+  let pdfPath = v.pdf ? resolve(v.pdf) : join(config.build.outDir!, basename(texPath!).replace(/\.tex$/i, "") + ".pdf");
+  if (command === "build") {
+    const engine = texEngine();
+    if (!v.json) console.log(`[1/2] ${engine ?? "compile"} ${texPath}`);
+    // stderr keeps --json output parseable while telling agents not to time out.
+    if (engine === "tectonic" && !tectonicCacheReady()) console.error("First Tectonic build: downloading TeX packages (about 45 MB). This can take a few minutes.");
+    pdfPath = (await compile(texPath!, { outDir: config.build.outDir, layout: config.layout })).pdfPath;
+    if (!v.json) console.log("[2/2] quality gates\n");
+  }
+  const report = await runGates(texPath!, pdfPath, { ...config.checks, sections: config.sections }, config.layout);
+  console.log(v.json ? JSON.stringify({ pdf: pdfPath, ...resolved, ...report }, null, 2) : formatReport(report));
+  if (command === "build" && report.pass && !config.build.keepLogs) await cleanIntermediates(pdfPath);
+  if (command === "build" && report.pass && !v.json) console.log(`\nresumectl: built ${pdfPath}`);
+  return report.pass ? 0 : 1;
+}

package/src/cli.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+import { main } from "./cli/main.ts";
+import { BuildError } from "./rendering/compile.ts";
+import { InputError } from "./errors.ts";
+
+try { process.exit(await main(Bun.argv.slice(2))); }
+catch (error) {
+  const code = (error as NodeJS.ErrnoException).code;
+  const message = code === "ENOENT" ? `file or executable not found: ${(error as Error).message}. Run resumectl doctor to check the TeX engine.` : (error as Error).message;
+  console.error(`resumectl: ${message}`);
+  if (error instanceof BuildError) process.exit(1);
+  if (error instanceof InputError || code === "ENOENT" || code?.startsWith("ERR_PARSE_ARGS")) process.exit(2);
+  throw error;
+}

package/src/content/tex.ts

@@ -0,0 +1,107 @@
+// Reading the parts of a résumé .tex the gates care about.
+import { dirname, join } from "node:path";
+import { InputError } from "../errors.ts";
+
+export type Style = "serif" | "sans";
+
+export interface ClassOptions {
+  style: Style;
+  /** Font scale relative to the 11pt body (sans only; serif is always 1). */
+  scale: number;
+  /** Letter spacing in % of the em (sans only; serif is always 0). */
+  tracking: number;
+}
+
+export const DEFAULT_CLASS_OPTIONS: ClassOptions = { style: "serif", scale: 1, tracking: 0 };
+export const sectionKey = (s: string) => stripToVisible(s).replace(/\s+/g, " ").trim().toUpperCase();
+const SANS_DEFAULTS = { scale: 0.86, tracking: -1.5 };
+
+export function stripComments(tex: string): string {
+  return tex.replace(/(^|[^\\])%[^\n]*/g, "$1");
+}
+
+/** Inline \input{x} / \include{x} relative to the including file, so split sources check as one. */
+export async function resolveInputs(tex: string, texPath: string, depth = 0): Promise<string> {
+  if (depth > 8) throw new InputError(`\\input nesting deeper than 8 levels in ${texPath}`);
+  const src = stripComments(tex);
+  let out = "";
+  let last = 0;
+  for (const m of src.matchAll(/\\(?:input|include)\s*\{([^}]+)\}/g)) {
+    const name = m[1].trim();
+    const path = join(dirname(texPath), name.endsWith(".tex") ? name : `${name}.tex`);
+    const file = Bun.file(path);
+    if (!await file.exists()) throw new InputError(`\\input target not found: ${path}`);
+    out += src.slice(last, m.index) + await resolveInputs(await file.text(), path, depth + 1);
+    last = m.index! + m[0].length;
+  }
+  return out + src.slice(last);
+}
+
+/** Read style/scale/tracking from \documentclass[...]{resume}. Missing keys fall back to the class defaults. */
+export function readClassOptions(tex: string): ClassOptions {
+  const m = stripComments(tex).match(/\\documentclass\s*(?:\[([^\]]*)\])?\s*\{\s*resume\s*\}/);
+  if (!m) return { ...DEFAULT_CLASS_OPTIONS };
+  const kv = new Map<string, string>();
+  for (const part of (m[1] ?? "").split(",")) {
+    const [k, v] = part.split("=").map(s => s?.trim());
+    if (k) kv.set(k, v ?? "");
+  }
+  if (kv.get("style") !== "sans") return { ...DEFAULT_CLASS_OPTIONS };
+  const num = (key: "scale" | "tracking") => {
+    const raw = kv.get(key);
+    const n = raw === undefined ? NaN : Number(raw);
+    return Number.isFinite(n) ? n : SANS_DEFAULTS[key];
+  };
+  return { style: "sans", scale: num("scale"), tracking: num("tracking") };
+}
+
+/** Raw \item bodies of the named \section, up to the next \section. */
+export function extractSectionItems(tex: string, section: string): string[] {
+  const block = sectionBody(tex, section);
+  const itemRe = /\\item\b([\s\S]*?)(?=\\item\b|\\end\{(?:itemize|plainlist)\}|\\datedsubsection|$)/g;
+  return [...block.matchAll(itemRe)].map(m => m[1].trim());
+}
+function sectionBody(tex: string, section: string): string {
+  tex = stripComments(tex);
+  const headings = [...tex.matchAll(/\\section\*?\s*(?:\[[^\]]*\])?\s*\{((?:[^{}]|\{[^{}]*\})*)\}/g)];
+  return headings.flatMap((h, i) => sectionKey(h[1]) === sectionKey(section)
+    ? [tex.slice(h.index! + h[0].length, headings[i + 1]?.index)] : []).join("\n");
+}
+/** Source snippets for measured lists and explicit paragraph/table entries, in render order. */
+export function extractSectionEntries(tex: string, section: string): string[] {
+  const block = sectionBody(tex, section);
+  const entries = [...block.matchAll(/\\item\b([\s\S]*?)(?=\\item\b|\\end\{(?:itemize|plainlist)\}|\\datedsubsection|$)/g)]
+    .map(m => ({ index: m.index!, text: m[1].trim() }));
+  for (const m of block.matchAll(/\\resumeentry\s*\{/g)) {
+    const start = m.index! + m[0].length;
+    let depth = 1, end = start;
+    for (; end < block.length && depth > 0; end++) {
+      if (block[end] === "\\") { end++; continue; }
+      if (block[end] === "{") depth++;
+      if (block[end] === "}") depth--;
+    }
+    if (depth === 0) entries.push({ index: m.index!, text: block.slice(start, end - 1) });
+  }
+  return entries.sort((a, b) => a.index - b.index).map(e => e.text);
+}
+
+const MATH_SYMBOLS: Record<string, string> = { rightarrow: "→", to: "→", leftarrow: "←", times: "×", pm: "±", approx: "≈", leq: "≤", geq: "≥", sim: "~" };
+
+/** Reduce LaTeX markup to the characters that end up on the page. */
+export function stripToVisible(raw: string): string {
+  let s = raw
+    .replace(/\$\\(\w+)\$/g, (_, cmd: string) => MATH_SYMBOLS[cmd] ?? "")
+    .replace(/\\href\s*\{[^}]*\}\s*\{([^}]*)\}/g, "$1")
+    .replace(/\\([%&$_#{}])/g, "$1")
+    .replace(/---/g, "—")
+    .replace(/--/g, "–")
+    .replace(/(^|[^\\])~/g, "$1 ");
+  const cmdBrace = /\\[a-zA-Z@]+\*?\s*(?:\[[^\]]*\])?\s*\{([^{}]*)\}/g;
+  while (cmdBrace.test(s)) s = s.replace(cmdBrace, "$1");
+  return s
+    .replace(/\\\\/g, "")
+    .replace(/\\[a-zA-Z@]+\*?/g, "")
+    .replace(/[{}$]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/src/errors.ts

@@ -0,0 +1,3 @@
+// Errors in what the user handed us (a missing file, a section with no bullets), as
+// opposed to a failed compile. The CLI maps these to exit code 2.
+export class InputError extends Error {}

package/src/index.ts

@@ -0,0 +1,22 @@
+export { compile, cleanIntermediates, BuildError, TEMPLATE_DIR, FONT_DIR, type BuildResult, type BuildOptions } from "./rendering/compile.ts";
+export { resolveConfig, validateConfig, DEFAULT_CHECKS, DEFAULT_LAYOUT, type ResumeConfig, type ConfigInput, type LayoutOptions, type CheckOptions, type BulletOptions, type SectionOptions, type SectionInput, type ResolvedConfig } from "./project/config.ts";
+export {
+  runGates,
+  checkBullets,
+  formatReport,
+  parseLogPageCount,
+  DEFAULT_GATE_OPTIONS,
+  type GateOptions,
+  type GateOverrides,
+  type GateReport,
+  type BulletResult,
+  type SectionResult,
+} from "./quality/gates.ts";
+export { InputError } from "./errors.ts";
+export { type RenderedBullet, type BuildManifest } from "./rendering/measurements.ts";
+export { countPdfPages } from "./quality/pdf.ts";
+export { readClassOptions, extractSectionItems, extractSectionEntries, stripToVisible, resolveInputs, type ClassOptions, type Style } from "./content/tex.ts";
+
+export { typographicWidth } from "./rendering/font-width.ts";
+export { initConfig, initProject } from "./project/init.ts";
+export { doctor, formatDoctor, type DoctorReport, type Diagnostic } from "./project/doctor.ts";