job-forge 2.14.21 → 2.14.23

package/lib/jobforge-cache.mjs

@@ -0,0 +1,105 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import {
+  cacheKey,
+  hasCacheEntry,
+  listCacheEntries,
+  pruneCache,
+  putCacheEntry,
+  readCacheContent,
+  resolveCacheDir,
+  verifyCache,
+} from '@razroo/iso-cache';
+
+export const CACHE_DIR = '.jobforge-cache';
+export const JD_CACHE_NAMESPACE = 'jobforge.jd';
+export const JD_CACHE_VERSION = '1';
+export const JD_CACHE_KIND = 'jd';
+export const DEFAULT_JD_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeCacheDir(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_CACHE || join(projectDir, CACHE_DIR);
+}
+
+export function jobForgeCacheSummary(projectDir = resolveProjectDir()) {
+  const root = resolveCacheDir(jobForgeCacheDir(projectDir));
+  const entries = listCacheEntries(root, { includeExpired: true });
+  return {
+    root,
+    exists: existsSync(root),
+    entries: entries.length,
+    active: entries.filter((entry) => !entry.expiresAt || new Date(entry.expiresAt).getTime() > Date.now()).length,
+  };
+}
+
+export function jobDescriptionCacheKey(url) {
+  return cacheKey({
+    namespace: JD_CACHE_NAMESPACE,
+    version: JD_CACHE_VERSION,
+    parts: { url: normalizeJobUrl(url) },
+  });
+}
+
+export function putJobDescriptionCache(url, content, options = {}, projectDir = resolveProjectDir()) {
+  const normalizedUrl = normalizeJobUrl(url);
+  return putCacheEntry(
+    jobForgeCacheDir(projectDir),
+    jobDescriptionCacheKey(normalizedUrl),
+    content,
+    {
+      kind: options.kind || JD_CACHE_KIND,
+      contentType: options.contentType || 'text/markdown',
+      ttlMs: options.expiresAt ? undefined : (options.ttlMs ?? DEFAULT_JD_TTL_MS),
+      expiresAt: options.expiresAt,
+      metadata: {
+        url: normalizedUrl,
+        source: options.source || 'job-forge',
+        ...(options.metadata || {}),
+      },
+    },
+  );
+}
+
+export function readJobDescriptionCache(url, options = {}, projectDir = resolveProjectDir()) {
+  return readCacheContent(jobForgeCacheDir(projectDir), jobDescriptionCacheKey(url), options);
+}
+
+export function hasJobDescriptionCache(url, options = {}, projectDir = resolveProjectDir()) {
+  return hasCacheEntry(jobForgeCacheDir(projectDir), jobDescriptionCacheKey(url), options);
+}
+
+export function readJobForgeCache(key, options = {}, projectDir = resolveProjectDir()) {
+  return readCacheContent(jobForgeCacheDir(projectDir), key, options);
+}
+
+export function putJobForgeCache(key, content, options = {}, projectDir = resolveProjectDir()) {
+  return putCacheEntry(jobForgeCacheDir(projectDir), key, content, options);
+}
+
+export function listJobForgeCache(options = {}, projectDir = resolveProjectDir()) {
+  return listCacheEntries(jobForgeCacheDir(projectDir), options);
+}
+
+export function verifyJobForgeCache(projectDir = resolveProjectDir()) {
+  return verifyCache(jobForgeCacheDir(projectDir));
+}
+
+export function pruneJobForgeCache(options = {}, projectDir = resolveProjectDir()) {
+  return pruneCache(jobForgeCacheDir(projectDir), options);
+}
+
+export function normalizeJobUrl(url) {
+  const text = String(url || '').trim();
+  if (!text) throw new Error('url is required');
+  try {
+    const parsed = new URL(text);
+    parsed.hash = '';
+    return parsed.toString();
+  } catch {
+    return text;
+  }
+}

package/lib/jobforge-index.mjs

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  buildIndex,
+  hasIndexRecord,
+  loadIndexConfig,
+  parseJson,
+  queryIndex,
+  verifyIndex,
+} from '@razroo/iso-index';
+
+export const INDEX_FILE = '.jobforge-index.json';
+export const INDEX_CONFIG_FILE = 'templates/index.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeIndexPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_INDEX || join(projectDir, INDEX_FILE);
+}
+
+export function jobForgeIndexConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_INDEX_CONFIG || join(projectDir, INDEX_CONFIG_FILE);
+}
+
+export function indexExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeIndexPath(projectDir));
+}
+
+export function readJobForgeIndexConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeIndexConfigPath(projectDir);
+  return loadIndexConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function buildJobForgeIndex(options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeIndexConfig(projectDir);
+  const index = buildIndex(config, { root: projectDir });
+  const out = options.out || jobForgeIndexPath(projectDir);
+  if (options.write !== false) {
+    writeFileSync(out, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+  }
+  return { index, out };
+}
+
+export function readJobForgeIndex(projectDir = resolveProjectDir()) {
+  const path = jobForgeIndexPath(projectDir);
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function ensureJobForgeIndex(options = {}, projectDir = resolveProjectDir()) {
+  if (options.rebuild !== false || !indexExists(projectDir)) {
+    return buildJobForgeIndex({ out: options.out }, projectDir).index;
+  }
+  return readJobForgeIndex(projectDir);
+}
+
+export function queryJobForgeIndex(query = {}, options = {}, projectDir = resolveProjectDir()) {
+  return queryIndex(ensureJobForgeIndex(options, projectDir), query);
+}
+
+export function hasJobForgeIndexRecord(query = {}, options = {}, projectDir = resolveProjectDir()) {
+  return hasIndexRecord(ensureJobForgeIndex(options, projectDir), query);
+}
+
+export function verifyJobForgeIndex(options = {}, projectDir = resolveProjectDir()) {
+  const index = options.index || ensureJobForgeIndex(options, projectDir);
+  return verifyIndex(index);
+}
+
+export function jobForgeIndexSummary(projectDir = resolveProjectDir()) {
+  if (!indexExists(projectDir)) {
+    return {
+      path: jobForgeIndexPath(projectDir),
+      config: jobForgeIndexConfigPath(projectDir),
+      exists: false,
+      records: 0,
+      files: 0,
+      sources: 0,
+    };
+  }
+  const index = readJobForgeIndex(projectDir);
+  return {
+    path: jobForgeIndexPath(projectDir),
+    config: jobForgeIndexConfigPath(projectDir),
+    exists: true,
+    records: index.stats?.records || 0,
+    files: index.stats?.files || 0,
+    sources: index.stats?.sources || 0,
+    configHash: index.configHash,
+  };
+}

package/modes/auto-pipeline.md

@@ -21,7 +21,9 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 
 **If the input is JD text** (not a URL): use it directly, no fetching needed.
 
-**Local artifacts before Step 0 methods:** Grep `reports/` for the URL or stable company+role slug; if a report already embeds the full JD, Read it and skip network fetch entirely. If the pipeline row or `jds/` references `local:jds/{file}`, Read that file first. This stacks with the rule above: one fetch per URL per session, and **zero** if the JD is already on disk.
+**Local artifacts before Step 0 methods:** Grep `reports/` for the URL or stable company+role slug; if a report already embeds the full JD, Read it and skip network fetch entirely. If the pipeline row or `jds/` references `local:jds/{file}`, Read that file first. For URL inputs, run `npx job-forge cache:has --url "{url}"` and then `npx job-forge cache:get --url "{url}"` on a hit; cached JD text is authoritative local content and avoids a browser/network fetch. This stacks with the rule above: one fetch per URL per session, and **zero** if the JD is already on disk or in `.jobforge-cache/`.
+
+**Cache after a successful fetch:** If the JD text is written to `jds/` or embedded in a report, store that exact text with `npx job-forge cache:put --url "{url}" --ttl 14d --input @path/to/jd.md`. Do not refetch just to populate the cache.
 
 ## Step 1 — Run Evaluation A-F
 Execute exactly as in the `offer` mode (read `modes/offer.md` for all blocks A-F).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.21",
+  "version": "2.14.23",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -41,6 +41,20 @@
     "context:plan": "node bin/job-forge.mjs context:plan",
     "context:check": "node bin/job-forge.mjs context:check",
     "context:render": "node bin/job-forge.mjs context:render",
+    "cache:key": "node bin/job-forge.mjs cache:key",
+    "cache:has": "node bin/job-forge.mjs cache:has",
+    "cache:get": "node bin/job-forge.mjs cache:get",
+    "cache:put": "node bin/job-forge.mjs cache:put",
+    "cache:status": "node bin/job-forge.mjs cache:status",
+    "cache:list": "node bin/job-forge.mjs cache:list",
+    "cache:verify": "node bin/job-forge.mjs cache:verify",
+    "cache:prune": "node bin/job-forge.mjs cache:prune",
+    "index:build": "node bin/job-forge.mjs index:build",
+    "index:status": "node bin/job-forge.mjs index:status",
+    "index:query": "node bin/job-forge.mjs index:query",
+    "index:has": "node bin/job-forge.mjs index:has",
+    "index:verify": "node bin/job-forge.mjs index:verify",
+    "index:explain": "node bin/job-forge.mjs index:explain",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -58,7 +72,9 @@
     "bin/",
     "iso/",
     "models.yaml",
-    ".claude/",
+    ".claude/settings.json",
+    ".claude/iso-route.resolved.json",
+    ".claude/agents/",
     ".cursor/mcp.json",
     ".cursor/rules/",
     ".cursor/iso-route.md",
@@ -106,9 +122,11 @@
   },
   "dependencies": {
     "@razroo/iso-capabilities": "^0.1.0",
+    "@razroo/iso-cache": "^0.1.0",
     "@razroo/iso-context": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",
+    "@razroo/iso-index": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",

package/scripts/cache.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'fs';
+import {
+  formatCacheEntries,
+  formatPruneResult,
+  formatVerifyResult,
+} from '@razroo/iso-cache';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  DEFAULT_JD_TTL_MS,
+  JD_CACHE_KIND,
+  jobDescriptionCacheKey,
+  jobForgeCacheDir,
+  jobForgeCacheSummary,
+  listJobForgeCache,
+  pruneJobForgeCache,
+  putJobDescriptionCache,
+  putJobForgeCache,
+  readJobDescriptionCache,
+  readJobForgeCache,
+  verifyJobForgeCache,
+} from '../lib/jobforge-cache.mjs';
+
+const USAGE = `job-forge cache - local deterministic artifact cache
+
+Usage:
+  job-forge cache:key --url <url> [--json]
+  job-forge cache:status [--json]
+  job-forge cache:has (--url <url> | --key <key>) [--allow-expired] [--json]
+  job-forge cache:get (--url <url> | --key <key>) [--allow-expired] [--output <file>] [--json]
+  job-forge cache:put (--url <url> | --key <key>) --input <text|@file|-> [--ttl 14d] [--kind <kind>] [--content-type <type>] [--meta <json|@file>] [--json]
+  job-forge cache:list [--kind <kind>] [--include-expired] [--json]
+  job-forge cache:verify [--json]
+  job-forge cache:prune [--expired] [--dry-run] [--json]
+  job-forge cache:path
+
+Default path is .jobforge-cache/ unless JOB_FORGE_CACHE is set. This is local
+project state, not an MCP and not prompt context.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeCacheDir(PROJECT_DIR));
+  } else if (cmd === 'key') {
+    key(opts);
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'has') {
+    has(opts);
+  } else if (cmd === 'get') {
+    get(opts);
+  } else if (cmd === 'put') {
+    put(opts);
+  } else if (cmd === 'list') {
+    list(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'prune') {
+    prune(opts);
+  } else {
+    console.error(`unknown cache command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = {
+    json: false,
+    help: false,
+    allowExpired: false,
+    includeExpired: false,
+    dryRun: false,
+    expired: false,
+    ttlMs: DEFAULT_JD_TTL_MS,
+    metadata: {},
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--url') {
+      opts.url = valueAfter(args, ++i, '--url');
+    } else if (arg.startsWith('--url=')) {
+      opts.url = arg.slice('--url='.length);
+    } else if (arg === '--key') {
+      opts.key = valueAfter(args, ++i, '--key');
+    } else if (arg.startsWith('--key=')) {
+      opts.key = arg.slice('--key='.length);
+    } else if (arg === '--input') {
+      opts.input = valueAfter(args, ++i, '--input');
+    } else if (arg.startsWith('--input=')) {
+      opts.input = arg.slice('--input='.length);
+    } else if (arg === '--output') {
+      opts.output = valueAfter(args, ++i, '--output');
+    } else if (arg.startsWith('--output=')) {
+      opts.output = arg.slice('--output='.length);
+    } else if (arg === '--kind') {
+      opts.kind = valueAfter(args, ++i, '--kind');
+    } else if (arg.startsWith('--kind=')) {
+      opts.kind = arg.slice('--kind='.length);
+    } else if (arg === '--content-type') {
+      opts.contentType = valueAfter(args, ++i, '--content-type');
+    } else if (arg.startsWith('--content-type=')) {
+      opts.contentType = arg.slice('--content-type='.length);
+    } else if (arg === '--ttl') {
+      opts.ttlMs = parseDuration(valueAfter(args, ++i, '--ttl'));
+    } else if (arg.startsWith('--ttl=')) {
+      opts.ttlMs = parseDuration(arg.slice('--ttl='.length));
+    } else if (arg === '--expires-at') {
+      opts.expiresAt = valueAfter(args, ++i, '--expires-at');
+      opts.ttlMs = undefined;
+    } else if (arg.startsWith('--expires-at=')) {
+      opts.expiresAt = arg.slice('--expires-at='.length);
+      opts.ttlMs = undefined;
+    } else if (arg === '--meta') {
+      opts.metadata = parseMetadata(valueAfter(args, ++i, '--meta'));
+    } else if (arg.startsWith('--meta=')) {
+      opts.metadata = parseMetadata(arg.slice('--meta='.length));
+    } else if (arg === '--allow-expired') {
+      opts.allowExpired = true;
+    } else if (arg === '--include-expired') {
+      opts.includeExpired = true;
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true;
+    } else if (arg === '--expired') {
+      opts.expired = true;
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function key(opts) {
+  const keyValue = keyFromOptions(opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ key: keyValue, url: opts.url || null }, null, 2));
+    return;
+  }
+  console.log(keyValue);
+}
+
+function status(opts) {
+  const summary = jobForgeCacheSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(`cache:   ${summary.root}`);
+  console.log(`exists:  ${summary.exists ? 'yes' : 'no'}`);
+  console.log(`entries: ${summary.active} active, ${summary.entries - summary.active} expired`);
+}
+
+function has(opts) {
+  const hit = read(opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ hit: Boolean(hit?.hit), stale: Boolean(hit?.stale), key: keyFromOptions(opts) }, null, 2));
+  } else {
+    console.log(hit?.hit ? `HIT${hit.stale ? ' stale' : ''}` : 'MISS');
+  }
+  process.exit(hit?.hit ? 0 : 1);
+}
+
+function get(opts) {
+  const hit = read(opts);
+  if (!hit?.hit || hit.content === undefined) {
+    if (opts.json) {
+      console.log(JSON.stringify({ hit: false, stale: Boolean(hit?.stale), key: keyFromOptions(opts) }, null, 2));
+    } else {
+      console.log('MISS');
+    }
+    process.exit(1);
+  }
+  if (opts.output) {
+    writeFileSync(opts.output, hit.content, 'utf8');
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ hit: true, stale: hit.stale, entry: hit.entry, content: opts.output ? undefined : hit.content }, null, 2));
+  } else if (opts.output) {
+    console.log(`WROTE ${opts.output}`);
+  } else {
+    process.stdout.write(hit.content);
+    if (!hit.content.endsWith('\n')) process.stdout.write('\n');
+  }
+}
+
+function put(opts) {
+  if (!opts.input) throw new Error('cache:put requires --input <text|@file|->');
+  const content = readInput(opts.input);
+  const entry = opts.url
+    ? putJobDescriptionCache(opts.url, content, {
+      kind: opts.kind || JD_CACHE_KIND,
+      contentType: opts.contentType,
+      ttlMs: opts.ttlMs,
+      expiresAt: opts.expiresAt,
+      metadata: opts.metadata,
+    }, PROJECT_DIR)
+    : putJobForgeCache(requiredKey(opts), content, {
+      kind: opts.kind,
+      contentType: opts.contentType,
+      ttlMs: opts.expiresAt ? undefined : opts.ttlMs,
+      expiresAt: opts.expiresAt,
+      metadata: opts.metadata,
+    }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(entry, null, 2));
+    return;
+  }
+  console.log(`STORED ${entry.key} ${entry.contentHash}`);
+}
+
+function list(opts) {
+  const entries = listJobForgeCache({
+    kind: opts.kind,
+    includeExpired: opts.includeExpired,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  console.log(formatCacheEntries(entries));
+}
+
+function verify(opts) {
+  const result = verifyJobForgeCache(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function prune(opts) {
+  const result = pruneJobForgeCache({
+    expired: opts.expired || undefined,
+    dryRun: opts.dryRun,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatPruneResult(result));
+}
+
+function read(opts) {
+  if (opts.url) {
+    return readJobDescriptionCache(opts.url, { allowExpired: opts.allowExpired }, PROJECT_DIR);
+  }
+  return readJobForgeCache(requiredKey(opts), { allowExpired: opts.allowExpired }, PROJECT_DIR);
+}
+
+function keyFromOptions(opts) {
+  if (opts.url) return jobDescriptionCacheKey(opts.url);
+  return requiredKey(opts);
+}
+
+function requiredKey(opts) {
+  if (!opts.key) throw new Error('expected --url or --key');
+  return opts.key;
+}
+
+function readInput(input) {
+  if (input === '-') return readFileSync(0, 'utf8');
+  if (input.startsWith('@')) return readFileSync(input.slice(1), 'utf8');
+  return input;
+}
+
+function parseMetadata(raw) {
+  const text = raw.startsWith('@') ? readFileSync(raw.slice(1), 'utf8') : raw;
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--meta must be a JSON object');
+  }
+  return parsed;
+}
+
+function parseDuration(raw) {
+  const match = /^(\d+)(ms|s|m|h|d)?$/.exec(String(raw).trim());
+  if (!match) throw new Error('--ttl must be a duration like 14d, 2h, 30m, 10s, or 500ms');
+  const value = Number(match[1]);
+  const unit = match[2] || 'ms';
+  const multipliers = {
+    ms: 1,
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+  return value * multipliers[unit];
+}