jobhunt-kit 0.4.0 → 0.5.0

package/plugins/jobhunt-kit/schemas/profile.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "jobhunt-kit/profile",
+  "type": "object",
+  "required": ["schema_version", "confirmed_at", "identity", "search", "languages", "experience", "education", "skills", "achievements", "evidence", "answers", "availability", "writing", "hirify_profile_id", "resume"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "confirmed_at": { "type": ["string", "null"], "format": "date-time" },
+    "identity": {
+      "type": "object",
+      "required": ["name", "email", "phone", "city", "country", "timezone", "contact_links"],
+      "properties": {
+        "name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] },
+        "phone": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] },
+        "country": { "type": ["string", "null"] }, "timezone": { "type": ["string", "null"] },
+        "contact_links": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "search": {
+      "type": "object",
+      "required": ["roles", "levels", "countries", "work_modes", "employment_types", "industries", "excluded_companies", "excluded_keywords", "work_authorization", "hard_constraints", "preferences", "feed_ids", "queries", "salary"],
+      "properties": {
+        "roles": { "$ref": "#/$defs/strings" }, "levels": { "$ref": "#/$defs/strings" },
+        "countries": { "$ref": "#/$defs/strings" }, "work_modes": { "$ref": "#/$defs/strings" },
+        "employment_types": { "$ref": "#/$defs/strings" }, "industries": { "$ref": "#/$defs/strings" },
+        "excluded_companies": { "$ref": "#/$defs/strings" }, "excluded_keywords": { "$ref": "#/$defs/strings" },
+        "work_authorization": { "$ref": "#/$defs/strings" }, "hard_constraints": { "$ref": "#/$defs/strings" },
+        "preferences": { "$ref": "#/$defs/strings" }, "feed_ids": { "type": "array", "items": { "type": ["string", "integer"] } },
+        "queries": { "$ref": "#/$defs/strings" },
+        "relocation": {}, "travel": {}, "working_hours": {}, "sponsorship": {},
+        "unknown_salary": { "type": "string" }, "unknown_critical_requirement": { "type": "string" },
+        "salary": {
+          "type": "object",
+          "required": ["min", "target", "currency", "period", "tax_basis"],
+          "properties": {
+            "min": { "type": ["number", "null"], "minimum": 0 }, "target": { "type": ["number", "null"], "minimum": 0 },
+            "currency": { "type": ["string", "null"] }, "period": { "type": ["string", "null"] }, "tax_basis": { "type": ["string", "null"] }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "languages": { "type": "array", "items": { "$ref": "#/$defs/object" } },
+    "experience": { "type": "array", "items": { "$ref": "#/$defs/evidenced" } },
+    "education": { "type": "array", "items": { "$ref": "#/$defs/evidenced" } },
+    "skills": { "type": "array", "items": { "$ref": "#/$defs/evidenced" } },
+    "achievements": { "type": "array", "items": { "$ref": "#/$defs/evidenced" } },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "text", "source", "confirmed"],
+        "properties": { "id": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "confirmed": { "type": "boolean" } },
+        "additionalProperties": true
+      }
+    },
+    "answers": { "type": "array", "items": { "$ref": "#/$defs/evidenced" } },
+    "availability": { "$ref": "#/$defs/object" }, "writing": { "$ref": "#/$defs/object" },
+    "hirify_profile_id": { "type": ["integer", "null"], "minimum": 1 },
+    "resume": {
+      "type": "object", "required": ["path", "sha256", "review_status"],
+      "properties": {
+        "path": { "type": ["string", "null"] }, "sha256": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "review_status": { "enum": ["not_reviewed", "needs_changes", "ready"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "strings": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "object": { "type": "object", "additionalProperties": true },
+    "evidenced": {
+      "type": "object",
+      "properties": { "evidence_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } } },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/plugins/jobhunt-kit/schemas/status.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "jobhunt-kit/status",
+  "type": "object",
+  "required": ["slug", "status", "note"],
+  "properties": {
+    "slug": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["dismissed", "needs_user", "submitted_external", "interview", "rejected", "withdrawn", "offer", "accepted", "declined"] },
+    "note": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": true
+}

package/plugins/jobhunt-kit/schemas/vacancy.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "jobhunt-kit/vacancy",
+  "type": "object",
+  "required": ["run_id", "slug", "title", "url", "route", "match"],
+  "properties": {
+    "run_id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" },
+    "title": { "type": "string", "minLength": 1 }, "company": { "type": ["string", "null"] },
+    "url": { "type": "string", "format": "uri" }, "original_url": { "type": "string", "format": "uri" },
+    "apply_url": { "type": "string", "format": "uri" }, "route": { "enum": ["hosted", "external", "unknown"] },
+    "description": { "type": "string" }, "read_at": { "type": "string", "format": "date-time" },
+    "match": {
+      "type": "object", "required": ["verdict"],
+      "properties": {
+        "verdict": { "enum": ["unreviewed", "suitable", "review", "rejected"] },
+        "reasons": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "requirements": {
+          "type": "array", "items": {
+            "type": "object", "required": ["requirement", "result", "evidence"],
+            "properties": { "requirement": { "type": "string", "minLength": 1 }, "result": { "enum": ["pass", "fail", "unknown"] }, "evidence": { "type": "string" } },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/plugins/jobhunt-kit/scripts/commands.mjs

@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util';
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve, join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
@@ -8,27 +8,36 @@ import { readJSON, writeJSON, validateProfile, saveProfile, confirmProfile } fro
 import { importResume, checkResume, recordResumeReview } from './resume.mjs';
 import { cliPath } from './hirify.mjs';
 import { sendPacket } from './send-packet.mjs';
+import { backupData, privacyMap, purgeData, redactData, restoreData, verifyBackup } from './maintenance.mjs';
+import { atomicWrite, atomicWriteJSON, localPath } from './files.mjs';
+import { validateSchema } from './validation.mjs';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const required = (value, name) => { if (!value) throw new Error(`${name} required`); return value; };
 function using(dir, fn) { const s = new Tracker(dir); try { return fn(s); } finally { s.close(); } }
+function persistAttemptPacket(dir, store, attemptId) {
+  const packet = store.attemptPacket(attemptId);
+  const path = localPath(dir, `materials/attempt-${attemptId}.json`);
+  atomicWriteJSON(path, packet, { base: dir });
+  return { packet_path: path, attempt_id: attemptId, sent: false };
+}
 function exportDraft(dir, job) {
   if (!job.draft) throw new Error('Prepare a draft first');
   const version = createHash('sha256').update(JSON.stringify(job.draft)).digest('hex').slice(0, 16);
   const folder = join(dir, 'materials', `application-${job.id}-${version}`);
   mkdirSync(folder, { recursive: true });
-  writeFileSync(join(folder, 'cover-letter.txt'), job.draft.cover_letter);
+  atomicWrite(join(folder, 'cover-letter.txt'), job.draft.cover_letter, { base: dir });
   writeJSON(join(folder, 'answers.json'), job.draft.answers || []);
   writeJSON(join(folder, 'draft.json'), job.draft);
   const destination = job.payload.apply_url || job.payload.original_url || job.payload.url;
-  writeFileSync(join(folder, 'handoff.md'), [
+  atomicWrite(join(folder, 'handoff.md'), [
     '# Материалы отклика', '', `Вакансия: ${job.payload.title}`, `Ссылка: ${destination}`, '',
     `Маршрут: ${job.payload.route}. Статус: ${job.status}.`,
     'Письмо: cover-letter.txt. Ответы: answers.json. Полный снимок: draft.json.', '',
     '## Требует действия', ...(job.draft.unresolved || []).map(x => `- ${x}`), '',
     job.payload.route === 'external' ? 'Отклик отправляет пользователь. Если ссылка на форму ещё не раскрыта, сначала получить её через Hirify reveal.' : 'Перед отправкой проверить профиль Hirify и текущую квоту; требуется действующее согласование.',
     '', 'Экспорт файлов не отправляет отклик.'
-  ].join('\n'));
+  ].join('\n'), { base: dir });
   return { directory: folder, handoff: join(folder, 'handoff.md'), sent: false };
 }
 function searchContext(dir, workspace) {
@@ -37,6 +46,7 @@ function searchContext(dir, workspace) {
     const validation = validateProfile(p.profile);
     if (!validation.valid) throw new Error(validation.errors.join('; '));
     const policy = readJSON(join(dir, 'policy.json'));
+    validateSchema('policy', policy);
     for (const k of ['target', 'max_cards', 'max_reads', 'max_reveals', 'max_minutes']) {
       if (!Number.isInteger(policy.search?.[k]) || policy.search[k] < (k === 'max_reveals' ? 0 : 1)) throw new Error(`Invalid search budget: ${k}`);
     }
@@ -50,7 +60,7 @@ function searchContext(dir, workspace) {
     const task = join(dir, 'materials', 'search-task.md');
     const localPlugin = join(workspace, 'plugins', 'jobhunt-kit');
     const plugin = existsSync(join(localPlugin, 'skills', 'job-search', 'SKILL.md')) ? localPlugin : ROOT;
-    writeFileSync(task, `Use job-search at ${join(plugin, 'skills', 'job-search', 'SKILL.md')}.\nRead ${path} and ${join(dir, 'profile.json')}.\nCheck live Hirify quotas and filter guide, preview filters, then search. Record runs and observations using the CLI.\nNo live search has been performed by this context command.\n`);
+    atomicWrite(task, `Use job-search at ${join(plugin, 'skills', 'job-search', 'SKILL.md')}.\nRead ${path} and ${join(dir, 'profile.json')}.\nCheck live Hirify quotas and filter guide, preview filters, then search. Record runs and observations using the CLI.\nNo live search has been performed by this context command.\n`, { base: dir });
     return { ...context, context_path: path, task_path: task };
   });
 }
@@ -69,7 +79,7 @@ function scheduleTemplate(dir, workspace, input) {
     '<абсолютный workspace>': workspace, '<абсолютный путь плагина>': plugin,
     '<абсолютный путь локальных данных>': dir, '<search / prepare / auto>': input.mode })) prompt = prompt.replaceAll(key, String(value));
   const path = join(dir, 'materials', 'scheduled-search.md');
-  writeFileSync(path, prompt);
+  atomicWrite(path, prompt, { base: dir });
   return { path, scheduled: false, auto_permission_granted: false, next: 'Review prompt and create a task using your agent scheduler' };
 }
 export function runCommand(args, { cwd = process.cwd(), transport } = {}) {
@@ -85,12 +95,29 @@ export function runCommand(args, { cwd = process.cwd(), transport } = {}) {
     let cli; try { cli = { available: true, path: cliPath(dir), version: '0.4.5' }; }
     catch (e) { cli = { available: false, reason: e.message }; }
     const initialized = existsSync(join(dir, 'profile.json'));
+    let integrity = null;
+    let profile = null;
+    if (initialized) {
+      try { integrity = using(dir, store => store.integrity()); }
+      catch (error) { integrity = { database_ok: false, error: error.message }; }
+      try { profile = validateProfile(readJSON(join(dir, 'profile.json'))); }
+      catch (error) { profile = { valid: false, errors: [error.message], warnings: [] }; }
+    }
     return { node: process.versions.node, workspace, data: dir, initialized, cli,
-      profile: initialized ? validateProfile(readJSON(join(dir, 'profile.json'))) : null, network_checked: false,
+      profile, integrity, network_checked: false,
       next: initialized ? 'profile check' : 'profile init' };
   }
   if (command === 'profile' && argument) throw new Error('Unexpected profile argument; use --input or --note');
   if (command === 'profile' && action === 'init') return initData(dir);
+  if (command === 'backup-verify') {
+    if (!action || argument) throw new Error('backup-verify requires one backup directory');
+    return verifyBackup(resolve(cwd, action));
+  }
+  if (command === 'restore') {
+    if (action || argument) throw new Error('restore uses --input with source and confirmation');
+    const request = input();
+    return restoreData(dir, resolve(cwd, required(request.source, 'source')), request.confirmation);
+  }
   if (!existsSync(join(dir, 'profile.json'))) throw new Error(`No profile at ${dir}. Run profile init first.`);
   if (command === 'profile') {
     if (argument) throw new Error('Unexpected profile argument; use --input or --note');
@@ -115,7 +142,6 @@ export function runCommand(args, { cwd = process.cwd(), transport } = {}) {
     const methods = { start: 'runStart', event: 'runEvent', record: 'put', finish: 'runFinish' };
     if (!methods[action]) throw new Error('search: plan | start | event | record | finish (JSON via --input)');
     return using(dir, s => {
-      if (action === 'start' && s.runs().some(r => r.status === 'running')) throw new Error('Finish or resolve the previous running search before starting another');
       return s[methods[action]](input());
     });
   }
@@ -125,9 +151,8 @@ export function runCommand(args, { cwd = process.cwd(), transport } = {}) {
     if (action === 'export') return using(dir, s => exportDraft(dir, s.job(required(argument, 'slug'))));
     if (action === 'begin') return using(dir, s => {
       const packet = s.begin({ slug: required(argument, 'slug') });
-      const path = join(dir, 'materials', `attempt-${packet.attempt_id}.json`);
-      writeJSON(path, packet);
-      return { packet_path: path, attempt_id: packet.attempt_id, sent: false };
+      try { return persistAttemptPacket(dir, s, packet.attempt_id); }
+      catch (error) { throw new Error(`Attempt reserved but packet write failed. Recover with: recover packet ${packet.attempt_id}. ${error.message}`); }
     });
     const methods = { prepare: 'prepare', approve: 'approve', finish: 'finish', resolve: 'resolveUnknown' };
     if (methods[action]) return using(dir, s => s[methods[action]](input()));
@@ -146,6 +171,27 @@ export function runCommand(args, { cwd = process.cwd(), transport } = {}) {
     if (action) throw new Error(`${command} takes no positional arguments`);
     return using(dir, s => s[command]());
   }
+  if (command === 'backup') {
+    if (!action || argument) throw new Error('backup requires one destination directory');
+    return backupData(dir, resolve(cwd, action));
+  }
+  if (command === 'recover') {
+    if (!action || action === 'inspect') return using(dir, store => store.integrity());
+    if (action === 'apply') return using(dir, store => store.recover(input()));
+    if (action === 'packet') return using(dir, store => persistAttemptPacket(dir, store, required(argument, 'attempt_id')));
+    throw new Error('recover: inspect | apply --input file | packet <attempt_id>');
+  }
+  if (command === 'privacy') {
+    if (!action || action === 'map') return privacyMap(dir);
+    if (action === 'export') return backupData(dir, resolve(cwd, required(argument, 'destination')));
+    if (['redact', 'purge'].includes(action) && argument) throw new Error(`privacy ${action} uses --input`);
+    if (action === 'redact') return redactData(dir, input());
+    if (action === 'purge') {
+      const request = input();
+      return purgeData(dir, { ...request, backup_directory: resolve(cwd, required(request.backup_directory, 'backup_directory')) });
+    }
+    throw new Error('privacy: map | export <directory> | redact/purge --input file');
+  }
   if (command === 'policy') {
     if (argument) throw new Error('Unexpected policy argument');
     if (!action || action === 'show') return readJSON(join(dir, 'policy.json'));

package/plugins/jobhunt-kit/scripts/extract-resume.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // Parser subprocess: local bytes only, bounded by parent timeout/memory/output limits.
-import { readFileSync, existsSync } from 'node:fs';
-import { extname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { localPath, MAX_RESUME_BYTES, readBytes } from './files.mjs';
 
 try {
   const [dir, file] = process.argv.slice(2);
@@ -10,7 +11,8 @@ try {
   const bundled = createRequire(import.meta.url);
   const runtime = existsSync(local) ? createRequire(local) : bundled;
   const load = name => { try { return runtime(name); } catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; return bundled(name); } };
-  const bytes = readFileSync(file);
+  const safeFile = localPath(dir, relative(resolve(dir), resolve(file)));
+  const bytes = readBytes(safeFile, { base: resolve(dir), maxBytes: MAX_RESUME_BYTES });
   let result;
   if (extname(file).toLowerCase() === '.pdf') {
     const { PDFParse } = load('pdf-parse');

package/plugins/jobhunt-kit/scripts/files.mjs

@@ -0,0 +1,69 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+export const MAX_JSON_BYTES = 2 * 1024 * 1024;
+export const MAX_RESUME_BYTES = 20 * 1024 * 1024;
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+export function inside(base, candidate) {
+  const delta = relative(resolve(base), resolve(candidate));
+  return delta === '' || (!isAbsolute(delta) && delta !== '..' && !delta.startsWith(`..${sep}`));
+}
+
+export function assertNoSymlink(path, stop = dirname(resolve(path))) {
+  let current = resolve(path);
+  const boundary = resolve(stop);
+  while (inside(boundary, current)) {
+    if (existsSync(current) && lstatSync(current).isSymbolicLink()) throw new Error(`Symbolic links are not allowed for local data: ${current}`);
+    if (current === boundary) return;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  throw new Error(`Path escapes the expected data directory: ${path}`);
+}
+
+export function localPath(base, path) {
+  if (typeof path !== 'string' || !path.trim() || isAbsolute(path)) throw new Error('Expected a relative path inside the local data directory');
+  const output = resolve(base, path);
+  if (!inside(base, output)) throw new Error(`Path escapes the local data directory: ${path}`);
+  assertNoSymlink(output, base);
+  return output;
+}
+
+export function readBytes(path, { maxBytes = MAX_JSON_BYTES, base = null } = {}) {
+  const target = resolve(path);
+  if (base) {
+    if (!inside(base, target)) throw new Error(`Path escapes the local data directory: ${path}`);
+    assertNoSymlink(target, base);
+  } else if (existsSync(target) && lstatSync(target).isSymbolicLink()) throw new Error(`Symbolic link input is not allowed: ${target}`);
+  const stat = lstatSync(target);
+  if (!stat.isFile()) throw new Error(`Expected a regular file: ${target}`);
+  if (stat.size > maxBytes) throw new Error(`File exceeds ${maxBytes} byte limit: ${target}`);
+  return readFileSync(target);
+}
+
+export function readJSON(path, options = {}) {
+  return JSON.parse(readBytes(path, options).toString('utf8').replace(/^\uFEFF/, ''));
+}
+
+export function atomicWrite(path, bytes, { base, mode = 0o600 } = {}) {
+  const target = resolve(path);
+  if (!base || !inside(base, target)) throw new Error(`Write target escapes the local data directory: ${target}`);
+  assertNoSymlink(target, base);
+  mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+  assertNoSymlink(dirname(target), base);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, bytes, { flag: 'wx', mode });
+    renameSync(temporary, target);
+  } catch (error) {
+    try { if (existsSync(temporary)) unlinkSync(temporary); } catch {}
+    throw error;
+  }
+}
+
+export function atomicWriteJSON(path, value, options) {
+  atomicWrite(path, JSON.stringify(value, null, 2) + '\n', options);
+}