job-forge 2.0.0

package/templates/states.yml

@@ -0,0 +1,62 @@
+# JobForge — Canonical States
+# Source of truth for job-forge (writer) and dashboard (reader).
+# Both systems MUST use these exact states.
+#
+# Rule: The status field in applications.md must contain EXACTLY
+# one of these values (case-insensitive). No markdown bold (**),
+# no dates, no extra text. Dates go in the date column.
+
+states:
+  - id: evaluated
+    label: Evaluated
+    aliases: []
+    description: Offer evaluated with report, pending decision
+    dashboard_group: evaluated
+
+  - id: applied
+    label: Applied
+    aliases: [sent]
+    description: Application submitted
+    dashboard_group: applied
+
+  - id: responded
+    label: Responded
+    aliases: []
+    description: Company has responded (not yet interview)
+    dashboard_group: responded
+
+  - id: contacted
+    label: Contacted
+    aliases: []
+    description: Candidate proactively reached out (LinkedIn, email) — not yet a response
+    dashboard_group: contacted
+
+  - id: interview
+    label: Interview
+    aliases: []
+    description: Active interview process
+    dashboard_group: interview
+
+  - id: offer
+    label: Offer
+    aliases: []
+    description: Offer received
+    dashboard_group: offer
+
+  - id: rejected
+    label: Rejected
+    aliases: []
+    description: Rejected by company
+    dashboard_group: rejected
+
+  - id: discarded
+    label: Discarded
+    aliases: []
+    description: Discarded by candidate or offer closed
+    dashboard_group: discarded
+
+  - id: skip
+    label: SKIP
+    aliases: [skip]
+    description: Doesn't fit, don't apply
+    dashboard_group: skip

package/tracker-lib.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * tracker-lib.mjs — Shared helper for reading/writing day-based application tracker files.
+ *
+ * Layout:
+ *   data/applications/YYYY-MM-DD.md  — one markdown table per day (preferred)
+ *   data/applications.md              — legacy single-file (fallback)
+ *
+ * The directory `data/applications/` takes priority. If it exists and has .md files,
+ * all reads/writes go through day files. If not, scripts fall back to the single file.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from 'fs';
+import { join, relative } from 'path';
+
+// Resolve the consumer's project directory. When installed as a package, the
+// scripts live in node_modules/ but should operate on the consumer's cwd.
+// JOB_FORGE_PROJECT env var overrides for tooling/tests.
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
+export const DATA_APPS_DIR = join(PROJECT_DIR, 'data', 'applications');
+export const DATA_APPS_FILE = join(PROJECT_DIR, 'data', 'applications.md');
+export const ROOT_APPS_FILE = join(PROJECT_DIR, 'applications.md');
+
+const TABLE_HEADER = [
+  '# Applications Tracker',
+  '',
+  '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |',
+  '|---|------|---------|------|-------|--------|-----|--------|-------|',
+].join('\n');
+
+// ---------- Day file helpers ----------
+
+/** Return YYYY-MM-DD from a Date object. */
+function toDateStr(d) {
+  return d.toISOString().slice(0, 10);
+}
+
+/** List all day .md files in data/applications/, sorted by filename (chronological). */
+export function listDayFiles() {
+  if (!existsSync(DATA_APPS_DIR)) return [];
+  return readdirSync(DATA_APPS_DIR)
+    .filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
+    .sort();
+}
+
+/** Path for a specific day file. */
+export function dayFilePath(date) {
+  return join(DATA_APPS_DIR, `${date}.md`);
+}
+
+/** Check whether the day-based directory layout is active (has at least one .md day file). */
+export function usesDayFiles() {
+  if (!existsSync(DATA_APPS_DIR)) return false;
+  return listDayFiles().length > 0;
+}
+
+/**
+ * Resolve the tracker layout: 'day' if data/applications/ with day files,
+ * 'single' if a single-file tracker exists, or 'none'.
+ */
+export function resolveLayout() {
+  if (usesDayFiles()) return 'day';
+  if (existsSync(DATA_APPS_FILE)) return 'single-data';
+  if (existsSync(ROOT_APPS_FILE)) return 'single-root';
+  return 'none';
+}
+
+/**
+ * Get the display path for the active tracker (for log messages).
+ */
+export function displayPath() {
+  const layout = resolveLayout();
+  if (layout === 'day') return relative(PROJECT_DIR, DATA_APPS_DIR);
+  if (layout === 'single-data') return relative(PROJECT_DIR, DATA_APPS_FILE);
+  if (layout === 'single-root') return relative(PROJECT_DIR, ROOT_APPS_FILE);
+  return '(no tracker)';
+}
+
+// ---------- Reading ----------
+
+/**
+ * Parse a markdown table line into an app object.
+ * Returns null for non-data lines (headers, separators, etc.)
+ */
+export function parseAppLine(line) {
+  const parts = line.split('|').map(s => s.trim());
+  if (parts.length < 9) return null;
+  const num = parseInt(parts[1]);
+  if (isNaN(num) || num === 0) return null;
+  return {
+    num, date: parts[2], company: parts[3], role: parts[4],
+    score: parts[5], status: parts[6], pdf: parts[7], report: parts[8],
+    notes: parts[9] || '', raw: line,
+  };
+}
+
+/**
+ * Read all application entries from either day files or the single-file tracker.
+ * Returns { entries: App[], maxNum: number, source: 'day'|'single' }
+ */
+export function readAllEntries() {
+  const layout = resolveLayout();
+  const entries = [];
+  let maxNum = 0;
+
+  if (layout === 'day') {
+    for (const file of listDayFiles()) {
+      const content = readFileSync(join(DATA_APPS_DIR, file), 'utf-8');
+      for (const line of content.split('\n')) {
+        const app = parseAppLine(line);
+        if (app) {
+          app._sourceFile = file;
+          entries.push(app);
+          if (app.num > maxNum) maxNum = app.num;
+        }
+      }
+    }
+    return { entries, maxNum, source: 'day' };
+  }
+
+  const filePath = layout === 'single-data' ? DATA_APPS_FILE : ROOT_APPS_FILE;
+  if (layout === 'none') return { entries: [], maxNum: 0, source: 'none' };
+
+  const content = readFileSync(filePath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const app = parseAppLine(line);
+    if (app) {
+      app._sourceFile = filePath;
+      entries.push(app);
+      if (app.num > maxNum) maxNum = app.num;
+    }
+  }
+  return { entries, maxNum, source: 'single' };
+}
+
+/**
+ * Read all lines (including headers and blank lines) from either source.
+ * For day files, returns { date, lines }[] array.
+ * For single file, returns the file content split into lines.
+ */
+export function readAllRawLines() {
+  const layout = resolveLayout();
+  if (layout === 'day') {
+    const result = [];
+    for (const file of listDayFiles()) {
+      const content = readFileSync(join(DATA_APPS_DIR, file), 'utf-8');
+      result.push({ date: file.replace('.md', ''), lines: content.split('\n') });
+    }
+    return { type: 'day', days: result };
+  }
+  if (layout === 'none') return { type: 'none', lines: [] };
+  const filePath = layout === 'single-data' ? DATA_APPS_FILE : ROOT_APPS_FILE;
+  const content = readFileSync(filePath, 'utf-8');
+  return { type: 'single', lines: content.split('\n'), path: filePath };
+}
+
+// ---------- Writing ----------
+
+/**
+ * Ensure the day-based directory exists and has the initial structure.
+ * Creates data/applications/ if needed.
+ */
+export function ensureDayDir() {
+  if (!existsSync(DATA_APPS_DIR)) {
+    mkdirSync(DATA_APPS_DIR, { recursive: true });
+  }
+  const gitkeep = join(DATA_APPS_DIR, '.gitkeep');
+  if (!existsSync(gitkeep)) {
+    writeFileSync(gitkeep, '', 'utf-8');
+  }
+}
+
+const HEADER_LINES = [
+  '# Applications Tracker',
+  '',
+  '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |',
+  '|---|------|---------|------|-------|--------|-----|--------|-------|',
+];
+
+/**
+ * Get the day-file header (same format as the single-file header).
+ */
+export function getHeader() {
+  return HEADER_LINES.join('\n');
+}
+
+/**
+ * Format an app object as a markdown table row.
+ */
+export function formatAppLine(app) {
+  return `| ${app.num} | ${app.date} | ${app.company} | ${app.role} | ${app.score} | ${app.status} | ${app.pdf} | ${app.report} | ${app.notes} |`;
+}
+
+/**
+ * Initialize the tracker. If using day-based layout, creates the directory.
+ * If using single-file layout, creates data/applications.md with empty header.
+ * Returns 'day' or 'single' indicating which layout was initialized.
+ */
+export function initTracker() {
+  if (usesDayFiles()) {
+    ensureDayDir();
+    return 'day';
+  }
+  // If no tracker exists at all, default to day-based layout
+  if (!existsSync(DATA_APPS_FILE) && !existsSync(ROOT_APPS_FILE)) {
+    ensureDayDir();
+    return 'day';
+  }
+  // Single-file mode: an existing single-file tracker is present
+  return 'single';
+}
+
+/**
+ * Write entries to day files. Takes an array of app objects and distributes them
+ * into the correct YYYY-MM-DD.md file based on app.date.
+ * If a day file doesn't exist, it's created with the header.
+ * Existing day files are rewritten with the provided entries plus any entries
+ * not in the provided array (those are preserved).
+ */
+export function writeToDayFiles(entries) {
+  ensureDayDir();
+
+  // Group entries by date
+  const byDate = new Map();
+  for (const app of entries) {
+    const date = app.date || toDateStr(new Date());
+    if (!byDate.has(date)) byDate.set(date, []);
+    byDate.get(date).push(app);
+  }
+
+  // Merge with existing entries in each day file
+  for (const [date, dayEntries] of byDate) {
+    const path = dayFilePath(date);
+    const existing = existsSync(path) ? readFileSync(path, 'utf-8').split('\n') : [];
+    const existingNums = new Set(dayEntries.map(e => e.num));
+
+    // Collect entries from file that aren't in the new set
+    const preserved = [];
+    for (const line of existing) {
+      const app = parseAppLine(line);
+      if (app && !existingNums.has(app.num)) {
+        preserved.push(app);
+      }
+    }
+
+    const allEntries = [...dayEntries, ...preserved].sort((a, b) => a.num - b.num);
+    const lines = [
+      ...HEADER_LINES,
+      ...allEntries.map(formatAppLine),
+    ];
+    writeFileSync(path, lines.join('\n') + '\n', 'utf-8');
+  }
+}
+
+// ---------- Utility ----------
+
+export { PROJECT_DIR, TABLE_HEADER };

package/verify-pipeline.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * verify-pipeline.mjs — Health check for job-forge pipeline integrity
+ *
+ * Supports both layouts:
+ *   - Day-based: data/applications/YYYY-MM-DD.md (preferred)
+ *   - Single-file: data/applications.md or applications.md (legacy)
+ *
+ * Checks:
+ * 1. All statuses are canonical (from templates/states.yml when present, else built-in list)
+ * 2. No duplicate company+role entries
+ * 3. All report links point to existing files
+ * 4. Scores match format X.XX/5 or N/A or DUP
+ * 5. All rows have proper pipe-delimited format
+ * 6. No pending TSVs in tracker-additions/ (runs even when tracker file is missing)
+ * 7. No markdown bold in score column
+ * 8. Drift warning if states.yml ids differ from the built-in fallback list
+ *
+ * Run: node verify-pipeline.mjs   (from repo root; same as npm run verify)
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, relative, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  PROJECT_DIR, DATA_APPS_DIR, DATA_APPS_FILE, ROOT_APPS_FILE,
+  usesDayFiles, readAllEntries, listDayFiles, dayFilePath,
+} from './tracker-lib.mjs';
+
+const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
+const STATES_FILE = existsSync(join(PROJECT_DIR, 'templates/states.yml'))
+  ? join(PROJECT_DIR, 'templates/states.yml')
+  : join(PROJECT_DIR, 'states.yml');
+
+const appsDisplay = usesDayFiles()
+  ? relative(PROJECT_DIR, DATA_APPS_DIR)
+  : existsSync(DATA_APPS_FILE)
+    ? relative(PROJECT_DIR, DATA_APPS_FILE)
+    : relative(PROJECT_DIR, ROOT_APPS_FILE);
+
+const CANONICAL_STATUSES = [
+  'evaluated', 'applied', 'contacted', 'responded', 'interview',
+  'offer', 'rejected', 'discarded', 'skip',
+];
+
+const ALIASES = {
+  'sent': 'applied',
+};
+
+function loadStatesFromYaml(filePath) {
+  if (!existsSync(filePath)) return null;
+  const text = readFileSync(filePath, 'utf-8');
+  const ids = new Set();
+  const aliasToId = new Map();
+  let currentId = null;
+  for (const line of text.split('\n')) {
+    const idLine = line.match(/^\s+- id:\s*(\S+)/);
+    if (idLine) {
+      currentId = idLine[1].toLowerCase();
+      ids.add(currentId);
+      continue;
+    }
+    const aliasLine = line.match(/^\s+aliases:\s*\[(.*)\]\s*$/);
+    if (aliasLine && currentId) {
+      const inner = aliasLine[1].trim();
+      if (inner) {
+        for (let raw of inner.split(',')) {
+          raw = raw.trim().replace(/^['"]|['"]$/g, '');
+          if (raw) aliasToId.set(raw.toLowerCase(), currentId);
+        }
+      }
+    }
+  }
+  if (ids.size === 0) return null;
+  return { ids, aliasToId };
+}
+
+const statesMeta = loadStatesFromYaml(STATES_FILE);
+
+function statusIsAllowed(statusOnlyLower) {
+  if (statesMeta) {
+    if (statesMeta.ids.has(statusOnlyLower)) return true;
+    if (statesMeta.aliasToId.has(statusOnlyLower)) return true;
+    return false;
+  }
+  return CANONICAL_STATUSES.includes(statusOnlyLower) || Boolean(ALIASES[statusOnlyLower]);
+}
+
+let errors = 0;
+let warnings = 0;
+
+function error(msg) { console.log(`❌ ${msg}`); errors++; }
+function warn(msg) { console.log(`⚠️  ${msg}`); warnings++; }
+function ok(msg) { console.log(`✅ ${msg}`); }
+
+function checkPendingTrackerAdditions() {
+  let pendingTsvs = 0;
+  if (existsSync(ADDITIONS_DIR)) {
+    const files = readdirSync(ADDITIONS_DIR).filter(f => f.endsWith('.tsv'));
+    pendingTsvs = files.length;
+    if (pendingTsvs > 0) {
+      warn(`${pendingTsvs} pending TSVs in tracker-additions/ (not merged)`);
+    }
+  }
+  if (pendingTsvs === 0) ok('No pending TSVs');
+}
+
+function verifyStatesYamlDrift() {
+  let stateDrift = 0;
+  if (statesMeta) {
+    const builtin = new Set(CANONICAL_STATUSES);
+    for (const id of statesMeta.ids) {
+      if (!builtin.has(id)) {
+        warn(`states.yml defines id "${id}" not in verify built-in list — extend CANONICAL_STATUSES if intentional`);
+        stateDrift++;
+      }
+    }
+    for (const id of builtin) {
+      if (!statesMeta.ids.has(id)) {
+        warn(`Built-in status "${id}" missing from ${STATES_FILE} — files may be out of sync`);
+        stateDrift++;
+      }
+    }
+    if (stateDrift === 0) ok('states.yml ids match verify built-in fallback list');
+  } else if (existsSync(STATES_FILE)) {
+    warn(`Could not parse state ids from ${STATES_FILE} — using built-in status list only`);
+  }
+}
+
+// --- Read entries ---
+const { entries, source } = readAllEntries();
+
+if (entries.length === 0) {
+  console.log('\n📊 No tracker entries found (expected data/applications/YYYY-MM-DD.md or data/applications.md).');
+  console.log('   This is normal for a fresh setup.\n');
+  checkPendingTrackerAdditions();
+  verifyStatesYamlDrift();
+  console.log('\n' + '='.repeat(50));
+  console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);
+  if (errors === 0 && warnings === 0) console.log('🟢 Pipeline is clean!');
+  else if (errors === 0) console.log('🟡 Pipeline OK with warnings');
+  else console.log('🔴 Pipeline has errors — fix before proceeding');
+  process.exit(errors > 0 ? 1 : 0);
+}
+
+console.log(`\n📊 Checking ${entries.length} entries from ${source === 'day' ? 'day files' : 'single file'}\n`);
+
+// --- Check 1: Canonical statuses ---
+let badStatuses = 0;
+for (const e of entries) {
+  const clean = e.status.replace(/\*\*/g, '').trim().toLowerCase();
+  const statusOnly = clean.replace(/\s+\d{4}-\d{2}-\d{2}.*$/, '').trim();
+
+  if (!statusIsAllowed(statusOnly)) {
+    error(`#${e.num}: Non-canonical status "${e.status}"`);
+    badStatuses++;
+  }
+
+  if (e.status.includes('**')) {
+    error(`#${e.num}: Status contains markdown bold: "${e.status}"`);
+    badStatuses++;
+  }
+
+  if (/\d{4}-\d{2}-\d{2}/.test(e.status)) {
+    error(`#${e.num}: Status contains date: "${e.status}" — dates go in date column`);
+    badStatuses++;
+  }
+}
+if (badStatuses === 0) ok('All statuses are canonical');
+
+// --- Check 2: Duplicates ---
+const companyRoleMap = new Map();
+let dupes = 0;
+for (const e of entries) {
+  const key = e.company.toLowerCase().replace(/[^a-z0-9]/g, '') + '::' +
+    e.role.toLowerCase().replace(/[^a-z0-9 ]/g, '');
+  if (!companyRoleMap.has(key)) companyRoleMap.set(key, []);
+  companyRoleMap.get(key).push(e);
+}
+for (const [key, group] of companyRoleMap) {
+  if (group.length > 1) {
+    warn(`Possible duplicates: ${group.map(e => `#${e.num}`).join(', ')} (${group[0].company} — ${group[0].role})`);
+    dupes++;
+  }
+}
+if (dupes === 0) ok('No exact duplicates found');
+
+// --- Check 3: Report links ---
+let brokenReports = 0;
+for (const e of entries) {
+  const match = e.report.match(/\]\(([^)]+)\)/);
+  if (!match) continue;
+  const reportPath = join(PROJECT_DIR, match[1]);
+  if (!existsSync(reportPath)) {
+    error(`#${e.num}: Report not found: ${match[1]}`);
+    brokenReports++;
+  }
+}
+if (brokenReports === 0) ok('All report links valid');
+
+// --- Check 4: Score format ---
+let badScores = 0;
+for (const e of entries) {
+  const s = e.score.replace(/\*\*/g, '').trim();
+  if (!/^\d+\.?\d*\/5$/.test(s) && s !== 'N/A' && s !== 'DUP') {
+    error(`#${e.num}: Invalid score format: "${e.score}"`);
+    badScores++;
+  }
+}
+if (badScores === 0) ok('All scores valid');
+
+// --- Check 5: Row format ---
+let badRows = 0;
+// Re-read raw lines for format check
+if (source === 'day') {
+  for (const file of listDayFiles()) {
+    const content = readFileSync(join(DATA_APPS_DIR, file), 'utf-8');
+    for (const line of content.split('\n')) {
+      if (!line.startsWith('|')) continue;
+      if (line.includes('---') || line.includes('Company')) continue;
+      const parts = line.split('|');
+      if (parts.length < 9) {
+        error(`Row with <9 columns in ${file}: ${line.substring(0, 80)}...`);
+        badRows++;
+      }
+    }
+  }
+} else {
+  const filePath = existsSync(DATA_APPS_FILE) ? DATA_APPS_FILE : ROOT_APPS_FILE;
+  const content = readFileSync(filePath, 'utf-8');
+  for (const line of content.split('\n')) {
+    if (!line.startsWith('|')) continue;
+    if (line.includes('---') || line.includes('Company')) continue;
+    const parts = line.split('|');
+    if (parts.length < 9) {
+      error(`Row with <9 columns: ${line.substring(0, 80)}...`);
+      badRows++;
+    }
+  }
+}
+if (badRows === 0) ok('All rows properly formatted');
+
+// --- Check 6: Pending TSVs ---
+checkPendingTrackerAdditions();
+
+// --- Check 7: Bold in scores ---
+let boldScores = 0;
+for (const e of entries) {
+  if (e.score.includes('**')) {
+    warn(`#${e.num}: Score has markdown bold: "${e.score}"`);
+    boldScores++;
+  }
+}
+if (boldScores === 0) ok('No bold in scores');
+
+verifyStatesYamlDrift();
+
+console.log('\n' + '='.repeat(50));
+console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);
+if (errors === 0 && warnings === 0) {
+  console.log('🟢 Pipeline is clean!');
+} else if (errors === 0) {
+  console.log('🟡 Pipeline OK with warnings');
+} else {
+  console.log('🔴 Pipeline has errors — fix before proceeding');
+}
+process.exit(errors > 0 ? 1 : 0);