job-forge 2.14.14 → 2.14.16

package/lib/jobforge-ledger.mjs

@@ -0,0 +1,214 @@
+import { existsSync } from 'fs';
+import { isAbsolute, join, relative } from 'path';
+import {
+  appendEvent,
+  hasEvent,
+  materializeLedger,
+  queryEvents,
+  readLedger,
+  verifyLedger,
+} from '@razroo/iso-ledger';
+
+export const LEDGER_DIR = '.jobforge-ledger';
+export const LEDGER_FILE = 'events.jsonl';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeLedgerPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_LEDGER || join(projectDir, LEDGER_DIR, LEDGER_FILE);
+}
+
+export function jobForgeLedgerOptions(projectDir = resolveProjectDir()) {
+  return { path: jobForgeLedgerPath(projectDir) };
+}
+
+export function ledgerExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeLedgerPath(projectDir));
+}
+
+export function readJobForgeLedger(projectDir = resolveProjectDir()) {
+  if (!ledgerExists(projectDir)) return [];
+  return readLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function verifyJobForgeLedger(projectDir = resolveProjectDir()) {
+  return verifyLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function queryJobForgeLedger(options = {}, projectDir = resolveProjectDir()) {
+  return queryEvents(readJobForgeLedger(projectDir), options);
+}
+
+export function hasJobForgeEvent(options = {}, projectDir = resolveProjectDir()) {
+  return hasEvent(readJobForgeLedger(projectDir), options);
+}
+
+export function jobForgeLedgerSummary(projectDir = resolveProjectDir()) {
+  const events = readJobForgeLedger(projectDir);
+  const materialized = materializeLedger(events);
+  return {
+    path: jobForgeLedgerPath(projectDir),
+    exists: ledgerExists(projectDir),
+    events: events.length,
+    entities: materialized.entityCount,
+    latest: events.at(-1) || null,
+  };
+}
+
+export function appendJobForgeEvent(input, projectDir = resolveProjectDir()) {
+  return appendEvent(jobForgeLedgerOptions(projectDir), input);
+}
+
+export function recordTrackerAdditionWritten(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  return appendJobForgeEvent(buildApplicationEvent('jobforge.tracker_addition.written', addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: 'tracker-addition-written',
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function recordTrackerMergeResult(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const outcome = options.outcome || 'processed';
+  return appendJobForgeEvent(buildApplicationEvent(`jobforge.tracker_merge.${outcome}`, addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: `tracker-merge-${outcome}`,
+    data: {
+      outcome,
+      duplicateNum: jsonValue(options.duplicateNum),
+      reason: jsonValue(options.reason),
+    },
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function buildApplicationEvent(type, app, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = companyRoleKey(app.company, app.role);
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : '';
+  const idempotencyParts = [
+    options.idempotencyPrefix || type,
+    sourceFile,
+    app.num,
+    app.date,
+    key,
+    app.status,
+    app.score,
+  ].filter((value) => value !== undefined && value !== null && String(value).length > 0);
+
+  return {
+    type,
+    key,
+    subject: applicationSubject(app.company, app.role),
+    idempotencyKey: idempotencyParts.join(':'),
+    data: compactObject({
+      num: numberOrString(app.num),
+      date: stringOrEmpty(app.date),
+      company: stringOrEmpty(app.company),
+      role: stringOrEmpty(app.role),
+      score: stringOrEmpty(app.score),
+      status: stringOrEmpty(app.status),
+      pdf: stringOrEmpty(app.pdf),
+      report: stringOrEmpty(app.report),
+      notes: stringOrEmpty(app.notes),
+      sourceFile,
+      ...compactObject(options.data || {}),
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function buildPipelineEvent(item, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = item.url ? urlKey(item.url) : `pipeline:${item.lineNumber || 'unknown'}`;
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : 'data/pipeline.md';
+  const state = item.checked ? 'processed' : 'pending';
+
+  return {
+    type: 'jobforge.pipeline.item',
+    key,
+    subject: key,
+    idempotencyKey: `pipeline:${state}:${item.url || item.lineNumber || item.line || 'unknown'}`,
+    data: compactObject({
+      state,
+      checked: Boolean(item.checked),
+      url: stringOrEmpty(item.url),
+      company: stringOrEmpty(item.company),
+      role: stringOrEmpty(item.role),
+      line: stringOrEmpty(item.line),
+      lineNumber: numberOrString(item.lineNumber),
+      sourceFile,
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function companyRoleKey(company, role) {
+  return `company-role:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function applicationSubject(company, role) {
+  return `application:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function urlKey(url) {
+  return `url:${String(url || '').trim()}`;
+}
+
+export function slugPart(value) {
+  const slug = String(value || 'unknown')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'unknown';
+}
+
+function relativePath(projectDir, value) {
+  const text = String(value || '');
+  if (!text) return '';
+  const rel = relative(projectDir, text);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replace(/\\/g, '/');
+  return text.replace(/\\/g, '/');
+}
+
+function compactObject(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj || {})) {
+    const clean = jsonValue(value);
+    if (clean !== undefined) out[key] = clean;
+  }
+  return out;
+}
+
+function jsonValue(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.map(jsonValue).filter((item) => item !== undefined);
+  if (typeof value === 'object') return compactObject(value);
+  return String(value);
+}
+
+function stringOrEmpty(value) {
+  if (value === undefined || value === null) return undefined;
+  const text = String(value);
+  return text.length > 0 ? text : undefined;
+}
+
+function numberOrString(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && String(value).trim() !== '' ? number : String(value);
+}

package/merge-tracker.mjs

@@ -29,6 +29,7 @@ import {
 import {
   DEFAULT_STATES, loadCanonicalStates, buildStatusDetectionRegex,
 } from './lib/canonical-states.mjs';
+import { recordTrackerMergeResult } from './lib/jobforge-ledger.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const MERGED_DIR = join(ADDITIONS_DIR, 'merged');
@@ -288,6 +289,7 @@ let added = 0;
 let updated = 0;
 let skipped = 0;
 const newEntries = [];
+const ledgerRecords = [];
 
 for (const file of tsvFiles) {
   const content = readFileSync(join(ADDITIONS_DIR, file), 'utf-8').trim();
@@ -359,12 +361,15 @@ for (const file of tsvFiles) {
         }
       }
       updated++;
+      ledgerRecords.push({ addition, outcome: 'updated', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason });
     } else if (statusRegresses) {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} status ${duplicate.status} outranks new ${addition.status})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'status-regression' });
     } else {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} ${oldScore} >= new ${newScore})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'no-improvement' });
     }
   } else {
     const entryNum = addition.num > maxNum ? addition.num : ++maxNum;
@@ -376,6 +381,7 @@ for (const file of tsvFiles) {
     });
     added++;
     console.log(`➕ Add #${entryNum}: ${addition.company} — ${addition.role} (${addition.score})`);
+    ledgerRecords.push({ addition: { ...addition, num: entryNum }, outcome: 'added', sourceFile: join(ADDITIONS_DIR, file), reason: 'new-entry' });
   }
 }
 
@@ -410,6 +416,23 @@ if (!DRY_RUN) {
     renameSync(join(ADDITIONS_DIR, file), join(MERGED_DIR, file));
   }
   console.log(`\n✅ Moved ${tsvFiles.length} TSVs to merged/`);
+
+  let ledgerEvents = 0;
+  for (const record of ledgerRecords) {
+    try {
+      const result = recordTrackerMergeResult(record.addition, {
+        projectDir: PROJECT_DIR,
+        sourceFile: record.sourceFile,
+        outcome: record.outcome,
+        duplicateNum: record.duplicateNum,
+        reason: record.reason,
+      });
+      if (result.appended) ledgerEvents++;
+    } catch (error) {
+      console.warn(`⚠️  Could not append ledger event for ${record.sourceFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.log(`🧾 Ledger: ${ledgerEvents} event(s) appended`);
 }
 
 console.log(`\n📊 Summary: +${added} added, 🔄${updated} updated, ⏭️${skipped} skipped`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.14",
+  "version": "2.14.16",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -25,6 +25,13 @@
     "telemetry:status": "node bin/job-forge.mjs telemetry:status",
     "telemetry:show": "node bin/job-forge.mjs telemetry:show",
     "telemetry:watch": "node bin/job-forge.mjs telemetry:watch",
+    "guard:audit": "node bin/job-forge.mjs guard:audit",
+    "guard:explain": "node bin/job-forge.mjs guard:explain",
+    "ledger:status": "node bin/job-forge.mjs ledger:status",
+    "ledger:rebuild": "node bin/job-forge.mjs ledger:rebuild",
+    "ledger:verify": "node bin/job-forge.mjs ledger:verify",
+    "ledger:has": "node bin/job-forge.mjs ledger:has",
+    "ledger:query": "node bin/job-forge.mjs ledger:query",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -89,6 +96,8 @@
     "node": ">=20.6.0"
   },
   "dependencies": {
+    "@razroo/iso-guard": "^0.1.0",
+    "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"