job-forge 2.14.25 → 2.14.27

package/lib/jobforge-canon.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  canonicalizeCompany,
+  canonicalizeCompanyRole,
+  canonicalizeEntity,
+  canonicalizeRole,
+  canonicalizeUrl,
+  compareCanon,
+  loadCanonConfig,
+  parseJson,
+  resolveProfile,
+} from '@razroo/iso-canon';
+
+export const CANON_CONFIG_FILE = 'templates/canon.json';
+export const CANON_PROFILE = 'jobforge';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeCanonConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_CANON_CONFIG || join(projectDir, CANON_CONFIG_FILE);
+}
+
+export function readJobForgeCanonConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeCanonConfigPath(projectDir);
+  return loadCanonConfig(parseJson(readFileSync(path, 'utf8'), path), path);
+}
+
+export function jobForgeCanonProfile(projectDir = resolveProjectDir()) {
+  return resolveProfile(readJobForgeCanonConfig(projectDir), process.env.JOB_FORGE_CANON_PROFILE || CANON_PROFILE);
+}
+
+export function canonicalizeJobForgeUrl(url, projectDir = resolveProjectDir()) {
+  return canonicalizeUrl(url, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeCompany(company, projectDir = resolveProjectDir()) {
+  return canonicalizeCompany(company, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeRole(role, projectDir = resolveProjectDir()) {
+  return canonicalizeRole(role, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeCompanyRole(company, role, projectDir = resolveProjectDir()) {
+  return canonicalizeCompanyRole(company, role, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeEntity(type, input, projectDir = resolveProjectDir()) {
+  return canonicalizeEntity(type, input, jobForgeCanonProfile(projectDir));
+}
+
+export function compareJobForgeCanon(type, left, right, projectDir = resolveProjectDir()) {
+  return compareCanon(type, left, right, jobForgeCanonProfile(projectDir));
+}
+
+export function jobForgeUrlKey(url, projectDir = resolveProjectDir()) {
+  return canonicalizeJobForgeUrl(url, projectDir).key;
+}
+
+export function jobForgeCompanyRoleKey(company, role, projectDir = resolveProjectDir()) {
+  return canonicalizeJobForgeCompanyRole(company, role, projectDir).key;
+}
+
+export function jobForgeApplicationSubject(company, role, projectDir = resolveProjectDir()) {
+  const companyKey = canonicalizeJobForgeCompany(company, projectDir).key.slice('company:'.length);
+  const roleKey = canonicalizeJobForgeRole(role, projectDir).key.slice('role:'.length);
+  return `application:${companyKey}:${roleKey}`;
+}
+
+export function legacyCompanyRoleKey(company, role) {
+  return `company-role:${legacySlugPart(company)}:${legacySlugPart(role)}`;
+}
+
+export function legacyUrlKey(url) {
+  return `url:${String(url || '').trim()}`;
+}
+
+export function legacySlugPart(value) {
+  const slug = String(value || 'unknown')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'unknown';
+}

package/lib/jobforge-index.mjs

@@ -6,8 +6,15 @@ import {
   loadIndexConfig,
   parseJson,
   queryIndex,
+  recordId,
   verifyIndex,
 } from '@razroo/iso-index';
+import {
+  jobForgeCompanyRoleKey,
+  jobForgeUrlKey,
+  legacyCompanyRoleKey,
+  legacyUrlKey,
+} from './jobforge-canon.mjs';
 
 export const INDEX_FILE = '.jobforge-index.json';
 export const INDEX_CONFIG_FILE = 'templates/index.json';
@@ -35,7 +42,7 @@ export function readJobForgeIndexConfig(projectDir = resolveProjectDir()) {
 
 export function buildJobForgeIndex(options = {}, projectDir = resolveProjectDir()) {
   const config = readJobForgeIndexConfig(projectDir);
-  const index = buildIndex(config, { root: projectDir });
+  const index = canonicalizeJobForgeIndex(buildIndex(config, { root: projectDir }), projectDir);
   const out = options.out || jobForgeIndexPath(projectDir);
   if (options.write !== false) {
     writeFileSync(out, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
@@ -90,3 +97,72 @@ export function jobForgeIndexSummary(projectDir = resolveProjectDir()) {
     configHash: index.configHash,
   };
 }
+
+function canonicalizeJobForgeIndex(index, projectDir) {
+  const records = (index.records || []).map((record) => canonicalizeJobForgeIndexRecord(record, projectDir));
+  records.sort(compareRecords);
+  return {
+    ...index,
+    records,
+    stats: {
+      ...(index.stats || {}),
+      records: records.length,
+    },
+  };
+}
+
+function canonicalizeJobForgeIndexRecord(record, projectDir) {
+  const key = canonicalIndexKey(record, projectDir);
+  if (key === record.key) return record;
+  const updated = { ...record, key };
+  return { ...updated, id: recordId(updated) };
+}
+
+function canonicalIndexKey(record, projectDir) {
+  if (isCompanyRoleRecord(record)) {
+    const { company, role } = companyRoleFields(record);
+    if (company && role) return safeCompanyRoleKey(company, role, projectDir);
+  }
+  if (isUrlRecord(record)) {
+    const url = record.fields?.url;
+    if (url) return safeUrlKey(url, projectDir);
+  }
+  return record.key;
+}
+
+function isCompanyRoleRecord(record) {
+  return record.kind === 'jobforge.application' || record.kind === 'jobforge.tracker-addition';
+}
+
+function companyRoleFields(record) {
+  const fields = record.fields || {};
+  return {
+    company: fields.company || fields.Company,
+    role: fields.role || fields.Role,
+  };
+}
+
+function isUrlRecord(record) {
+  return record.kind === 'jobforge.report.url' || record.kind === 'jobforge.pipeline.url' || record.kind === 'jobforge.scan.url';
+}
+
+function safeCompanyRoleKey(company, role, projectDir) {
+  try {
+    return jobForgeCompanyRoleKey(company, role, projectDir);
+  } catch {
+    return legacyCompanyRoleKey(company, role);
+  }
+}
+
+function safeUrlKey(url, projectDir) {
+  try {
+    return jobForgeUrlKey(url, projectDir);
+  } catch {
+    return legacyUrlKey(url);
+  }
+}
+
+function compareRecords(a, b) {
+  return `${a.kind}\0${a.key}\0${a.source?.path || ''}\0${a.source?.line || ''}\0${a.id}`
+    .localeCompare(`${b.kind}\0${b.key}\0${b.source?.path || ''}\0${b.source?.line || ''}\0${b.id}`);
+}

package/lib/jobforge-ledger.mjs

@@ -8,6 +8,16 @@ import {
   readLedger,
   verifyLedger,
 } from '@razroo/iso-ledger';
+import {
+  jobForgeApplicationSubject,
+  jobForgeCompanyRoleKey,
+  jobForgeUrlKey,
+  legacyCompanyRoleKey,
+  legacySlugPart,
+  legacyUrlKey,
+} from './jobforge-canon.mjs';
+
+export { legacyCompanyRoleKey, legacyUrlKey };
 
 export const LEDGER_DIR = '.jobforge-ledger';
 export const LEDGER_FILE = 'events.jsonl';
@@ -89,7 +99,7 @@ export function recordTrackerMergeResult(addition, options = {}) {
 
 export function buildApplicationEvent(type, app, options = {}) {
   const projectDir = resolveProjectDir(options.projectDir);
-  const key = companyRoleKey(app.company, app.role);
+  const key = companyRoleKey(app.company, app.role, projectDir);
   const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : '';
   const idempotencyParts = [
     options.idempotencyPrefix || type,
@@ -104,7 +114,7 @@ export function buildApplicationEvent(type, app, options = {}) {
   return {
     type,
     key,
-    subject: applicationSubject(app.company, app.role),
+    subject: applicationSubject(app.company, app.role, projectDir),
     idempotencyKey: idempotencyParts.join(':'),
     data: compactObject({
       num: numberOrString(app.num),
@@ -128,7 +138,7 @@ export function buildApplicationEvent(type, app, options = {}) {
 
 export function buildPipelineEvent(item, options = {}) {
   const projectDir = resolveProjectDir(options.projectDir);
-  const key = item.url ? urlKey(item.url) : `pipeline:${item.lineNumber || 'unknown'}`;
+  const key = item.url ? urlKey(item.url, projectDir) : `pipeline:${item.lineNumber || 'unknown'}`;
   const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : 'data/pipeline.md';
   const state = item.checked ? 'processed' : 'pending';
 
@@ -154,25 +164,33 @@ export function buildPipelineEvent(item, options = {}) {
   };
 }
 
-export function companyRoleKey(company, role) {
-  return `company-role:${slugPart(company)}:${slugPart(role)}`;
+export function companyRoleKey(company, role, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeCompanyRoleKey(company, role, projectDir);
+  } catch {
+    return legacyCompanyRoleKey(company, role);
+  }
 }
 
-export function applicationSubject(company, role) {
-  return `application:${slugPart(company)}:${slugPart(role)}`;
+export function applicationSubject(company, role, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeApplicationSubject(company, role, projectDir);
+  } catch {
+    const key = legacyCompanyRoleKey(company, role).slice('company-role:'.length);
+    return `application:${key}`;
+  }
 }
 
-export function urlKey(url) {
-  return `url:${String(url || '').trim()}`;
+export function urlKey(url, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeUrlKey(url, projectDir);
+  } catch {
+    return legacyUrlKey(url);
+  }
 }
 
 export function slugPart(value) {
-  const slug = String(value || 'unknown')
-    .toLowerCase()
-    .replace(/&/g, ' and ')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return slug || 'unknown';
+  return legacySlugPart(value);
 }
 
 function relativePath(projectDir, value) {

package/lib/jobforge-migrate.mjs

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  loadMigrationConfig,
+  parseJson,
+  runMigrations,
+} from '@razroo/iso-migrate';
+
+export const MIGRATION_CONFIG_FILE = 'templates/migrations.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeMigrationConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_MIGRATIONS_CONFIG || join(projectDir, MIGRATION_CONFIG_FILE);
+}
+
+export function migrationConfigExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeMigrationConfigPath(projectDir));
+}
+
+export function readJobForgeMigrationConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeMigrationConfigPath(projectDir);
+  return loadMigrationConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function runJobForgeMigrations(options = {}, projectDir = resolveProjectDir()) {
+  return runMigrations(readJobForgeMigrationConfig(projectDir), {
+    root: options.root || projectDir,
+    dryRun: options.dryRun,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.25",
+  "version": "2.14.27",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -55,6 +55,14 @@
     "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",
+    "canon:normalize": "node bin/job-forge.mjs canon:normalize",
+    "canon:key": "node bin/job-forge.mjs canon:key",
+    "canon:compare": "node bin/job-forge.mjs canon:compare",
+    "canon:explain": "node bin/job-forge.mjs canon:explain",
+    "migrate:plan": "node bin/job-forge.mjs migrate:plan",
+    "migrate:apply": "node bin/job-forge.mjs migrate:apply",
+    "migrate:check": "node bin/job-forge.mjs migrate:check",
+    "migrate:explain": "node bin/job-forge.mjs migrate:explain",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -123,11 +131,13 @@
   "dependencies": {
     "@razroo/iso-capabilities": "^0.1.0",
     "@razroo/iso-cache": "^0.1.0",
+    "@razroo/iso-canon": "^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-migrate": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"

package/scripts/canon.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatCanonResult,
+  formatCompareResult,
+  formatConfigSummary,
+} from '@razroo/iso-canon';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  canonicalizeJobForgeEntity,
+  compareJobForgeCanon,
+  jobForgeCanonConfigPath,
+  jobForgeCanonProfile,
+} from '../lib/jobforge-canon.mjs';
+
+const USAGE = `job-forge canon - deterministic identity keys for JobForge
+
+Usage:
+  job-forge canon:normalize <url|company|role> <value> [--json]
+  job-forge canon:normalize company-role --company <name> --role <title> [--json]
+  job-forge canon:key <url|company|role> <value> [--json]
+  job-forge canon:key company-role --company <name> --role <title> [--json]
+  job-forge canon:compare <url|company|role> <left> <right> [--json]
+  job-forge canon:compare company-role --left-company <name> --left-role <title> --right-company <name> --right-role <title> [--json]
+  job-forge canon:explain [--json]
+  job-forge canon:path
+
+The policy is templates/canon.json. These commands are local, model-free, and
+use the same keys that JobForge ledger/cache helpers use internally.`;
+
+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(jobForgeCanonConfigPath(PROJECT_DIR));
+  } else if (cmd === 'normalize') {
+    normalize(opts, false);
+  } else if (cmd === 'key') {
+    normalize(opts, true);
+  } else if (cmd === 'compare') {
+    compare(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown canon 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,
+    values: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--company') {
+      opts.company = valueAfter(args, ++i, '--company');
+    } else if (arg.startsWith('--company=')) {
+      opts.company = arg.slice('--company='.length);
+    } else if (arg === '--role') {
+      opts.role = valueAfter(args, ++i, '--role');
+    } else if (arg.startsWith('--role=')) {
+      opts.role = arg.slice('--role='.length);
+    } else if (arg === '--left-company') {
+      opts.leftCompany = valueAfter(args, ++i, '--left-company');
+    } else if (arg.startsWith('--left-company=')) {
+      opts.leftCompany = arg.slice('--left-company='.length);
+    } else if (arg === '--left-role') {
+      opts.leftRole = valueAfter(args, ++i, '--left-role');
+    } else if (arg.startsWith('--left-role=')) {
+      opts.leftRole = arg.slice('--left-role='.length);
+    } else if (arg === '--right-company') {
+      opts.rightCompany = valueAfter(args, ++i, '--right-company');
+    } else if (arg.startsWith('--right-company=')) {
+      opts.rightCompany = arg.slice('--right-company='.length);
+    } else if (arg === '--right-role') {
+      opts.rightRole = valueAfter(args, ++i, '--right-role');
+    } else if (arg.startsWith('--right-role=')) {
+      opts.rightRole = arg.slice('--right-role='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown flag "${arg}"`);
+    } else {
+      opts.values.push(arg);
+    }
+  }
+
+  return opts;
+}
+
+function normalize(opts, keyOnly) {
+  const type = parseType(opts.values.shift(), keyOnly ? 'key' : 'normalize');
+  const input = normalizeInput(type, opts);
+  const result = canonicalizeJobForgeEntity(type, input, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (keyOnly) {
+    console.log(result.key);
+  } else {
+    console.log(formatCanonResult(result));
+  }
+}
+
+function compare(opts) {
+  const type = parseType(opts.values.shift(), 'compare');
+  const [left, right] = compareInputs(type, opts);
+  const result = compareJobForgeCanon(type, left, right, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatCompareResult(result));
+}
+
+function explain(opts) {
+  const profile = jobForgeCanonProfile(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(profile, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeCanonConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary({ version: 1, profiles: [profile] }));
+}
+
+function normalizeInput(type, opts) {
+  if (type === 'company-role') {
+    if (!opts.company || !opts.role) throw new Error('company-role requires --company and --role');
+    return { company: opts.company, role: opts.role };
+  }
+  if (opts.values.length !== 1) throw new Error(`${type}: provide exactly one value; quote values containing spaces`);
+  return opts.values[0];
+}
+
+function compareInputs(type, opts) {
+  if (type === 'company-role') {
+    if (!opts.leftCompany || !opts.leftRole || !opts.rightCompany || !opts.rightRole) {
+      throw new Error('company-role compare requires --left-company, --left-role, --right-company, and --right-role');
+    }
+    return [
+      { company: opts.leftCompany, role: opts.leftRole },
+      { company: opts.rightCompany, role: opts.rightRole },
+    ];
+  }
+  if (opts.values.length !== 2) throw new Error(`${type}: provide exactly two values; quote values containing spaces`);
+  return [opts.values[0], opts.values[1]];
+}
+
+function parseType(value, command) {
+  if (value === 'url' || value === 'company' || value === 'role' || value === 'company-role') return value;
+  throw new Error(`${command}: expected type url, company, role, or company-role`);
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/scripts/ledger.mjs

@@ -16,6 +16,8 @@ import {
   jobForgeLedgerPath,
   jobForgeLedgerSummary,
   ledgerExists,
+  legacyCompanyRoleKey,
+  legacyUrlKey,
   readJobForgeLedger,
   urlKey,
   verifyJobForgeLedger,
@@ -201,8 +203,9 @@ function verify(opts) {
 }
 
 function has(opts) {
-  const filters = queryFilters(opts);
-  const events = queryEvents(readJobForgeLedger(PROJECT_DIR), filters);
+  const filters = queryFilterCandidates(opts);
+  const ledger = readJobForgeLedger(PROJECT_DIR);
+  const events = uniqueEvents(filters.flatMap((filter) => queryEvents(ledger, filter)));
   if (opts.json) {
     console.log(JSON.stringify({ match: events.length > 0, count: events.length, filters }, null, 2));
   } else if (events.length > 0) {
@@ -237,6 +240,28 @@ function queryFilters(opts) {
   return filters;
 }
 
+function queryFilterCandidates(opts) {
+  const primary = queryFilters(opts);
+  const candidates = [primary];
+  const legacy = { ...primary };
+  if (opts.url) legacy.key = legacyUrlKey(opts.url);
+  if (opts.company || opts.role) legacy.key = legacyCompanyRoleKey(opts.company, opts.role);
+  if (legacy.key && legacy.key !== primary.key) candidates.push(legacy);
+  return candidates;
+}
+
+function uniqueEvents(events) {
+  const seen = new Set();
+  const out = [];
+  for (const event of events) {
+    const id = event.id || event.idempotencyKey || JSON.stringify(event);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(event);
+  }
+  return out;
+}
+
 function collectProjectEvents() {
   const events = [];
   const { entries } = readAllEntries();

package/scripts/migrate.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatConfigSummary,
+  formatMigrationResult,
+} from '@razroo/iso-migrate';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  jobForgeMigrationConfigPath,
+  readJobForgeMigrationConfig,
+  runJobForgeMigrations,
+} from '../lib/jobforge-migrate.mjs';
+
+const USAGE = `job-forge migrate - deterministic consumer-project migrations
+
+Usage:
+  job-forge migrate:plan [--json]
+  job-forge migrate:apply [--json]
+  job-forge migrate:check [--json]
+  job-forge migrate:explain [--json]
+  job-forge migrate:path
+
+The policy is templates/migrations.json. Sync applies these migrations
+automatically unless JOB_FORGE_SKIP_MIGRATIONS=1 is set.`;
+
+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(jobForgeMigrationConfigPath(PROJECT_DIR));
+  } else if (cmd === 'plan') {
+    run('plan', opts);
+  } else if (cmd === 'apply') {
+    run('apply', opts);
+  } else if (cmd === 'check') {
+    const result = run('check', opts);
+    process.exit(result.changed ? 1 : 0);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown migrate 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 };
+  for (const arg of args) {
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw new Error(`unknown flag "${arg}"`);
+  }
+  return opts;
+}
+
+function run(mode, opts) {
+  const result = runJobForgeMigrations({ dryRun: mode !== 'apply' }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatMigrationResult(result, mode));
+  }
+  return result;
+}
+
+function explain(opts) {
+  const config = readJobForgeMigrationConfig(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeMigrationConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary(config));
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}