#!/usr/bin/env node
/**
 * followup-seed.mjs — Seed data/follow-ups.md when a row is marked Applied (#1430)
 *
 * WHY: the follow-up system was "born dead". Marking a tracker row Applied only
 * updated applications.md — data/follow-ups.md stayed empty until the user ran
 * the `followup` mode by hand and it happened to notice the row. In practice
 * that meant most applications never got a scheduled next-follow-up date at
 * all, silently defeating the entire cadence feature. This script closes that
 * gap: given an appNum (or --backfill for the whole tracker), it computes the
 * cadence-default next-follow-up date and writes it as a PIN DIRECTIVE line —
 * never a table row, because a table row in follow-ups.md means "a follow-up
 * was SENT", which seeding must not claim.
 *
 * Pin format (parsed by `parseNextOverrides` in followup-cadence.mjs):
 *   - next #<appNum> <YYYY-MM-DD> (set <YYYY-MM-DD>)
 * First date = seeded next-follow-up date. `(set …)` = the day the pin was
 * written. The LAST pin per application wins, so re-seeding with --force is
 * always safe — it just appends a fresh pin.
 *
 * Apply-date resolution order (see resolveAppliedDate): explicit --date, then
 * "Applied YYYY-MM-DD" in the row's notes, then the tracker's `date` column,
 * then today. Every result carries an `appDateSource` saying which of those it
 * came from, so a measured date is never mistaken for a guessed one.
 *
 * The `date` column used to be excluded here as "the evaluation date, not the
 * submission date". It is — but the fallback it was being excluded in favour of
 * was `today`, which is worse: an early date makes a follow-up fire early
 * (visible), while today makes an old application look new and silently resets
 * its follow-up clock (not visible). Preferring the labelled proxy over the
 * unlabelled guess is the trade that replaced it (#2607).
 *
 * Idempotency: by default, seeding a given appNum is a NO-OP FOREVER once
 * either a pin or a logged follow-up exists for it (exit 0, seeded:false).
 * Pass --force to append a fresh pin anyway.
 *
 * Usage:
 *   node followup-seed.mjs <appNum> [--date YYYY-MM-DD] [--force] [--dry-run] [--json]
 *   node followup-seed.mjs --backfill [--dry-run] [--json]
 *
 * Exit codes:
 *   0 success or idempotent no-op
 *   1 usage or validation error (incl. impossible --date, non-Applied row
 *     without --force, unknown flag)
 *   2 row not found (or tracker missing)
 *   4 lock timeout
 *
 * Env overrides (mirroring merge-tracker.mjs / followup-cadence.mjs):
 *   CAREER_OPS_TRACKER                     tracker path
 *   CAREER_OPS_FOLLOWUPS                   follow-ups path
 *   CAREER_OPS_PROFILE                     profile.yml path (cadence overrides)
 *   CAREER_OPS_FOLLOWUPS_LOCK              lock directory override
 *   CAREER_OPS_FOLLOWUPS_LOCK_TIMEOUT_MS   lock acquire timeout
 *   CAREER_OPS_FOLLOWUPS_LOCK_RETRY_MS     lock retry interval
 *   CAREER_OPS_FOLLOWUPS_LOCK_STALE_MS     stale-lock recovery threshold
 *   CAREER_OPS_OWNERLESS_GRACE_MS          ownerless-lock floor (lib/dir-lock.mjs; shared, not per-script)
 */

import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, realpathSync } from 'fs';
import { join, dirname, basename, resolve, isAbsolute, relative, sep } from 'path';
import { fileURLToPath } from 'url';
import { createHash, randomUUID } from 'crypto';
// The lock protocol is lib/dir-lock.mjs, shared with every other core lock;
// this module only picks the follow-ups lock directory, timing and error.
import { acquireDirLock, releaseOrWarn } from './lib/dir-lock.mjs';
import { makeCliFailWith, renameSyncWithRetry } from './tracker-utils.mjs';
import { tmpdir } from 'os';
import { resolveColumns, parseTrackerRow } from './tracker-parse.mjs';
import { localToday } from './lib/local-today.mjs';
import {
  resolveCadenceConfig,
  loadFollowupsEnabled,
  normalizeStatus,
  parseAppliedDate,
  parseFollowups,
  parseNextOverrides,
  parseDate,
  addDays,
  isRealCalendarDate,
} from './followup-cadence.mjs';
import { flagValue } from './lib/cli-flags.mjs';
import { getCareerOpsRoot, canonicalizeTrackerPath, resolveTrackerPath as sharedResolveTrackerPath } from './path-resolver.mjs';
import { isMainModule } from './lib/is-main-module.mjs';

const CAREER_OPS = getCareerOpsRoot();

/** Canonical header written when data/follow-ups.md doesn't exist yet. */
export const FOLLOWUPS_HEADER = [
  '# Follow-ups',
  '',
  '| num | appNum | date | company | role | channel | contact | notes |',
  '|---|---|---|---|---|---|---|---|',
].join('\n');

const FOLLOWUPS_LOCK_PREFIX = 'career-ops-followups-';

/**
 * Minimum age before directory age alone may condemn an ownerless lock.
 * See `lockRecoveryVerdict` for why the age check needs a floor.
 *
 * Re-exported rather than redeclared: the floor is applied inside that function
 * now, so a local copy would be a constant this file no longer enforces.
 */
export { OWNERLESS_GRACE_MS } from './lib/dir-lock.mjs';

/** Structured error carrying an exit-code-mapping `code`. */
export class SeedError extends Error {
  constructor(code, message) {
    super(message);
    this.name = 'SeedError';
    this.code = code;
  }
}

function todayStr() {
  return localToday();
}

/**
 * Validate a `YYYY-MM-DD` string is both well-formed AND a real calendar date.
 *
 * `parseDate` (followup-cadence.mjs) happily accepts `2026-02-31` because the
 * underlying `Date` constructor silently rolls invalid days over into the next
 * month. Round-tripping the parsed date back through `toISOString` catches
 * that: a real date always survives the round trip unchanged.
 *
 * @param {string} str
 * @returns {boolean}
 */
export function isValidCalendarDate(str) {
  if (typeof str !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(str)) return false;
  const d = parseDate(str);
  if (!d || isNaN(d)) return false;
  return d.toISOString().slice(0, 10) === str;
}

/**
 * Resolve the date an application was actually submitted, AND say where that
 * date came from: explicit `--date` > "Applied YYYY-MM-DD" in the row's notes >
 * the tracker's `date` column > today.
 *
 * The `date` column used to be excluded on the grounds that it is the
 * evaluation date, not the submission date. True, but it was the wrong
 * conclusion, because the alternative was `todayStr()` — and today is not a
 * neutral default here, it is the single most damaging guess available:
 *
 *   - the evaluation date is early by however long the user took to apply,
 *     which makes a follow-up fire early. Visible, and harmless.
 *   - today makes the application look brand new, which silently RESETS the
 *     follow-up clock. Someone who applied three weeks ago drops out of the
 *     chase queue, and the pin looks exactly like a normal fresh entry.
 *
 * A wrong date you can see beats a wrong date you cannot, so the proxy is now
 * preferred over the guess and `appDateSource` says which one you got. That
 * matches followup-cadence.mjs's `resolveAppliedDate` (same fallback, same
 * labelling) and company-history.mjs's `dateBasis`, so all three agree.
 *
 * `today` remains the last resort for a row whose `date` column is missing or
 * unusable — but it is now labelled too, rather than being indistinguishable
 * from a measured date.
 *
 * A notes date that isn't a real calendar date (e.g. "Applied 2026-02-31")
 * throws rather than falling through: `parseDate` would return null for it and
 * the pin would be written with a literal "null" next-date.
 *
 * @param {{num?: number, notes?: string, date?: string}} row - Parsed tracker row.
 * @param {string|null|undefined} explicitDate - `--date` value, already validated.
 * @param {string|null|undefined} [statusChangeDate] - The day a caller moved the row
 *   to Applied. It ranks below the notes date, which the user wrote on purpose, and
 *   above the evaluation-date column, which is only a proxy.
 * @returns {{appliedDate: string, appDateSource: 'explicit'|'notes'|'status-change'|'evaluation-date'|'today'}}
 * @throws {SeedError} INVALID_DATE when the notes carry an impossible date.
 */
export function resolveAppliedDate(row, explicitDate, statusChangeDate) {
  if (explicitDate) return { appliedDate: explicitDate, appDateSource: 'explicit' };
  const notesDate = parseAppliedDate(row?.notes);
  if (notesDate) {
    if (!isValidCalendarDate(notesDate)) {
      throw new SeedError('INVALID_DATE', `Application #${row?.num ?? '?'} notes carry an impossible "Applied ${notesDate}" date; fix the notes or pass --date`);
    }
    return { appliedDate: notesDate, appDateSource: 'notes' };
  }
  if (statusChangeDate) return { appliedDate: statusChangeDate, appDateSource: 'status-change' };
  // Only a usable calendar date qualifies: a blank or malformed `date` cell
  // must not become a pin with a "null" next-date, which is the same failure
  // the notes branch throws over.
  const columnDate = String(row?.date ?? '').trim();
  if (isValidCalendarDate(columnDate)) {
    return { appliedDate: columnDate, appDateSource: 'evaluation-date' };
  }
  return { appliedDate: todayStr(), appDateSource: 'today' };
}

/**
 * Format one pin directive line. The parser side lives in
 * followup-cadence.mjs's `OVERRIDE_RE` / `parseNextOverrides`.
 *
 * @param {number} appNum
 * @param {string} nextDate - YYYY-MM-DD
 * @param {string} setDate - YYYY-MM-DD
 * @returns {string}
 */
export function formatPinLine(appNum, nextDate, setDate) {
  return `- next #${appNum} ${nextDate} (set ${setDate})`;
}

// --- Path resolution (env override → option override → default) -----------

function resolveTrackerPath(override) {
  if (override) return override;
  return sharedResolveTrackerPath(CAREER_OPS);
}

function resolveFollowupsPath(override) {
  if (override) return override;
  if (process.env.CAREER_OPS_FOLLOWUPS) return process.env.CAREER_OPS_FOLLOWUPS;
  return join(CAREER_OPS, 'data/follow-ups.md');
}

function envInt(name, fallback) {
  const v = process.env[name];
  if (v === undefined || v === '') return fallback;
  const n = Number(v);
  return Number.isFinite(n) ? n : fallback;
}

// --- Tracker reading ---------------------------------------------------

function readTrackerRows(trackerPath) {
  const content = readFileSync(trackerPath, 'utf-8');
  const lines = content.split('\n');
  const parseOptions = { allowTabs: true, allowIndentation: true };
  const colmap = resolveColumns(lines, parseOptions);
  const rows = [];
  for (const line of lines) {
    const row = parseTrackerRow(line, colmap, parseOptions);
    if (row) rows.push(row);
  }
  return rows;
}

// --- Idempotency: pin OR an existing follow-up for appNum -----------------

function isAlreadySeeded(content, appNum) {
  if (!content) return false;
  if (parseNextOverrides(content).has(appNum)) return true;
  return parseFollowups(content).some(entry => entry.appNum === appNum);
}

// --- Locking (mirrors merge-tracker.mjs's tracker lock, scoped to follow-ups) --

function pathIsInside(childPath, parentDir) {
  const relativePath = relative(parentDir, childPath);
  return relativePath === '' || (relativePath !== '..' && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));
}

function resolveFollowupsLockDir(envValue, lockKey) {
  const tmpRoot = realpathSync(tmpdir());
  const fallback = join(tmpRoot, `${FOLLOWUPS_LOCK_PREFIX}${lockKey}.lock`);
  if (!envValue || !isAbsolute(envValue)) return fallback;

  const candidate = resolve(envValue);
  const parentDir = dirname(candidate);
  const canonicalParent = existsSync(parentDir) ? realpathSync(parentDir) : resolve(parentDir);
  if (!pathIsInside(canonicalParent, tmpRoot)) return fallback;
  if (!basename(candidate).startsWith(FOLLOWUPS_LOCK_PREFIX)) return fallback;
  return candidate;
}

function resolveLockDir(explicitLockDir, followupsPath) {
  if (explicitLockDir) return explicitLockDir;
  // Canonicalize the parent so the key stays stable when the file is first created.
  const lockPath = join(canonicalizeTrackerPath(dirname(followupsPath)), basename(followupsPath));
  const lockKey = createHash('sha256').update(lockPath).digest('hex').slice(0, 16);
  return resolveFollowupsLockDir(process.env.CAREER_OPS_FOLLOWUPS_LOCK, lockKey);
}

/**
 * Acquire an exclusive filesystem lock covering the read-check-append
 * critical section for data/follow-ups.md, through the protocol every core
 * lock shares (lib/dir-lock.mjs).
 *
 * @param {string} lockDir
 * @param {string} followupsPath - Recorded in owner.json for diagnostics.
 * @param {{timeoutMs?: number, retryMs?: number, staleMs?: number}} [options] - `staleMs` is floored at OWNERLESS_GRACE_MS.
 * @returns {Promise<{release: Function}>}
 */
function acquireFollowupsLock(lockDir, followupsPath, options = {}) {
  return acquireDirLock(lockDir, {
    timeoutMs: options.timeoutMs ?? 60_000,
    retryMs: options.retryMs ?? 75,
    staleMs: options.staleMs ?? 10 * 60_000,
    owner: { followups: followupsPath },
    timeoutError: () => new SeedError('LOCK_TIMEOUT', `Timed out waiting for follow-ups lock at ${lockDir}`),
  });
}

// --- Atomic write (mirrors writeFileAtomic in tracker.mjs / merge-tracker.mjs) --

function writeFileAtomic(filePath, content) {
  const tmpPath = join(dirname(filePath), `.${basename(filePath)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
  try {
    writeFileSync(tmpPath, content);
    renameSyncWithRetry(tmpPath, filePath);
  } catch (err) {
    rmSync(tmpPath, { force: true });
    throw err;
  }
}

function appendPins(existingContent, pinLines) {
  const joined = pinLines.join('\n');
  if (existingContent == null) {
    return `${FOLLOWUPS_HEADER}\n${joined}\n`;
  }
  return existingContent + (existingContent.endsWith('\n') ? '' : '\n') + joined + '\n';
}

// --- Core: seed one application --------------------------------------------

/**
 * Seed data/follow-ups.md with a pin directive for one Applied application.
 *
 * Silent-no-op-forever by default: once a pin or a follow-up table row exists
 * for `appNum`, subsequent calls return `{seeded:false, reason:'already-seeded'}`
 * without touching the file, unless `options.force` is set.
 *
 * @param {number} appNum
 * @param {object} [options]
 * @param {string} [options.date] - Explicit apply date (YYYY-MM-DD), already validated.
 * @param {string} [options.statusChangeDate] - The day the row moved to Applied, see resolveAppliedDate.
 * @param {boolean} [options.force] - Bypass idempotency guard and the Applied-status guard.
 * @param {boolean} [options.assumeApplied] - Relax the Applied-status guard ONLY, keeping
 *   idempotency intact. For a caller that is about to make the row Applied and wants a
 *   truthful preview of what will happen: `force` would answer that question by also
 *   suppressing `already-seeded`, so the preview would promise a pin the real run then
 *   declines to write. This says "treat the status as Applied", not "write regardless".
 * @param {boolean} [options.dryRun] - Compute and report, but write nothing (no lock taken).
 * @param {string} [options.trackerPath]
 * @param {string} [options.followupsPath]
 * @param {string} [options.profilePath]
 * @param {string} [options.lockDir]
 * @param {number} [options.lockTimeoutMs]
 * @param {number} [options.lockRetryMs]
 * @param {number} [options.lockStaleMs]
 * @returns {Promise<object>}
 */
/**
 * Run `fn` while holding the cross-process lock on a follow-ups file.
 *
 * EXISTS BECAUSE "TAKE A LOCK" IS NOT ENOUGH HERE (#3034). The lock directory
 * is DERIVED — sha256 of the resolved follow-ups path, under tmpdir — so two
 * writers that each take "a lock" on separately computed directories exclude
 * nothing at all. Any second implementation has to reproduce that derivation
 * exactly, and a derivation copied into another codebase is a second body of
 * the same truth: it works until the day one side changes.
 *
 * So the derivation never leaves this file. Callers outside the core (the web
 * dashboard's follow-up log and override routes) import this function and get
 * the same directory by construction.
 *
 * TWO PROPERTIES CALLERS DEPEND ON, both deliberate:
 *
 *   1. The lock is released on EVERY path, including a throw. A long-lived
 *      process that returns a 500 without releasing would block the user's own
 *      CLI until staleMs elapses, so the `finally` lives here rather than in
 *      each caller's hands.
 *
 *   2. It is NOT reentrant. Holding this lock and then invoking a core script
 *      that also takes it (`followup-seed.mjs` itself) self-deadlocks until the
 *      timeout. Callers that write the file directly are safe; callers that
 *      orchestrate core scripts must not wrap them in this.
 *
 * An in-process queue is not a substitute: it serialises one process against
 * itself and is blind to every other one. The two compose — queue inside this
 * lock — and neither replaces the other.
 *
 * @param {string} followupsPath - Path to the follow-ups file to guard.
 * @param {() => Promise<T>|T} fn - Runs while the lock is held.
 * @param {object} [options]
 * @param {string} [options.lockDir] - Explicit lock directory (tests).
 * @param {number} [options.timeoutMs=60000]
 * @param {number} [options.retryMs=75]
 * @param {number} [options.staleMs=600000]
 * @returns {Promise<T>} Whatever `fn` returned.
 * @template T
 */
export async function withFollowupsLock(followupsPath, fn, options = {}) {
  const resolvedPath = resolveFollowupsPath(followupsPath);
  const lockDir = resolveLockDir(options.lockDir, resolvedPath);
  const lock = await acquireFollowupsLock(lockDir, resolvedPath, {
    timeoutMs: options.timeoutMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_TIMEOUT_MS', 60_000),
    retryMs: options.retryMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_RETRY_MS', 75),
    staleMs: options.staleMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_STALE_MS', 10 * 60_000),
  });
  try {
    return await fn();
  } finally {
    releaseOrWarn(lock);
  }
}

const PIN_LINE = /^-\s+next\s+#(\d+)\s+(\d{4}-\d{2}-\d{2})(?:\s+\(set\s+(\d{4}-\d{2}-\d{2})\))?(?:\s*[—–-]\s*(.*))?\s*$/i;

function pinLinePattern(appNum) {
  return new RegExp(`^-\\s+next\\s+#${appNum}\\s`, 'i');
}

function lastPin(content, appNum) {
  let found = null;
  for (const line of String(content ?? '').split('\n')) {
    const match = line.match(PIN_LINE);
    if (!match || Number(match[1]) !== appNum) continue;
    found = { date: match[2], setDate: match[3] || match[2], why: (match[4] || '').trim() };
  }
  return found;
}

function withoutPins(content, appNum) {
  const pattern = pinLinePattern(appNum);
  return String(content ?? '').split('\n').filter((line) => !pattern.test(line)).join('\n');
}

function appendPinLine(content, appNum, line) {
  const base = content == null ? `${FOLLOWUPS_HEADER}\n` : withoutPins(content, appNum);
  return `${base.endsWith('\n') ? base : `${base}\n`}${line}\n`;
}

function pinText(appNum, date, setDate, why) {
  const line = formatPinLine(appNum, date, setDate);
  return why ? `${line} — ${why}` : line;
}

export async function replaceNextPin(appNum, options = {}) {
  if (!Number.isInteger(appNum) || appNum <= 0) {
    throw new SeedError('USAGE', `Invalid appNum: ${appNum}`);
  }
  if (!isRealCalendarDate(options.date)) {
    throw new SeedError('INVALID_DATE', `next date must be a real calendar date in YYYY-MM-DD form: ${options.date}`);
  }
  const why = String(options.why ?? '').trim();
  if (/[\t\r\n]/.test(why)) {
    throw new SeedError('USAGE', 'pin note cannot contain a tab or newline');
  }
  const followupsPath = resolveFollowupsPath(options.followupsPath);
  const setDate = localToday(options.now instanceof Date ? options.now : new Date());
  return withFollowupsLock(followupsPath, () => {
    const existing = existsSync(followupsPath) ? readFileSync(followupsPath, 'utf8') : null;
    const current = existing == null ? null : lastPin(existing, appNum);
    if (current && current.date === options.date && current.why === why) {
      return { changed: false, date: options.date, setDate: current.setDate };
    }
    mkdirSync(dirname(followupsPath), { recursive: true });
    writeFileAtomic(followupsPath, appendPinLine(existing, appNum, pinText(appNum, options.date, setDate, why)));
    return { changed: true, date: options.date, setDate };
  }, { timeoutMs: options.lockTimeoutMs, lockDir: options.lockDir });
}

export async function clearNextPin(appNum, options = {}) {
  if (!Number.isInteger(appNum) || appNum <= 0) {
    throw new SeedError('USAGE', `Invalid appNum: ${appNum}`);
  }
  const followupsPath = resolveFollowupsPath(options.followupsPath);
  return withFollowupsLock(followupsPath, () => {
    if (!existsSync(followupsPath)) return { cleared: false };
    const existing = readFileSync(followupsPath, 'utf8');
    const next = withoutPins(existing, appNum);
    if (next === existing) return { cleared: false };
    writeFileAtomic(followupsPath, next);
    return { cleared: true };
  }, { timeoutMs: options.lockTimeoutMs, lockDir: options.lockDir });
}

export async function seedFollowup(appNum, options = {}) {
  if (!Number.isInteger(appNum) || appNum <= 0) {
    throw new SeedError('USAGE', `Invalid appNum: ${appNum}`);
  }
  if (options.date != null && !isValidCalendarDate(options.date)) {
    throw new SeedError('INVALID_DATE', `--date must be a real calendar date in YYYY-MM-DD form: ${options.date}`);
  }

  if (!loadFollowupsEnabled(options.profilePath)) {
    return { seeded: false, appNum, pin: null, nextDate: null, reason: 'disabled', ...(options.dryRun ? { dryRun: true } : {}) };
  }

  const trackerPath = resolveTrackerPath(options.trackerPath);
  const followupsPath = resolveFollowupsPath(options.followupsPath);

  if (!existsSync(trackerPath)) {
    throw new SeedError('ROW_NOT_FOUND', `Tracker not found at ${trackerPath}`);
  }
  const rows = readTrackerRows(trackerPath);
  const row = rows.find(r => r.num === appNum);
  if (!row) {
    throw new SeedError('ROW_NOT_FOUND', `Application #${appNum} not found in ${trackerPath}`);
  }

  const normalized = normalizeStatus(row.status);
  if (normalized !== 'applied' && !options.force && !options.assumeApplied) {
    throw new SeedError('NOT_APPLIED', `Application #${appNum} is not Applied (status: "${row.status.trim()}"); use --force to seed anyway`);
  }

  // appDateSource travels with the result so a caller can tell a measured apply
  // date from a proxy or a guess — the same contract followup-cadence.mjs and
  // company-history.mjs already expose.
  const { appliedDate, appDateSource } = resolveAppliedDate(row, options.date, options.statusChangeDate);
  const cadence = resolveCadenceConfig({ profilePath: options.profilePath });
  const nextDate = addDays(parseDate(appliedDate), cadence.applied_first);
  const setDate = todayStr();
  const pin = formatPinLine(appNum, nextDate, setDate);

  if (options.dryRun) {
    const existingContent = existsSync(followupsPath) ? readFileSync(followupsPath, 'utf-8') : '';
    if (isAlreadySeeded(existingContent, appNum) && !options.force) {
      return { seeded: false, appNum, pin: null, nextDate, appliedDate, appDateSource, setDate, reason: 'already-seeded', dryRun: true };
    }
    return { seeded: true, appNum, pin, nextDate, appliedDate, appDateSource, setDate, dryRun: true };
  }

  const lockDir = resolveLockDir(options.lockDir, followupsPath);
  const lock = await acquireFollowupsLock(lockDir, followupsPath, {
    timeoutMs: options.lockTimeoutMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_TIMEOUT_MS', 60_000),
    retryMs: options.lockRetryMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_RETRY_MS', 75),
    staleMs: options.lockStaleMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_STALE_MS', 10 * 60_000),
  });

  try {
    const existingContent = existsSync(followupsPath) ? readFileSync(followupsPath, 'utf-8') : null;
    if (existingContent != null && isAlreadySeeded(existingContent, appNum) && !options.force) {
      return { seeded: false, appNum, pin: null, nextDate, appliedDate, appDateSource, setDate, reason: 'already-seeded' };
    }

    mkdirSync(dirname(followupsPath), { recursive: true });
    writeFileAtomic(followupsPath, appendPins(existingContent, [pin]));
    return { seeded: true, appNum, pin, nextDate, appliedDate, appDateSource, setDate };
  } finally {
    releaseOrWarn(lock);
  }
}

// --- Core: backfill all Applied rows ---------------------------------------

/**
 * Seed every tracker row whose status normalizes to `applied` that doesn't
 * already have a pin or follow-up table row. Non-Applied rows are skipped
 * silently. Idempotent — re-running seeds nothing new.
 *
 * @param {object} [options] - Same shape as seedFollowup's options (minus `date`/appNum).
 * @returns {Promise<{seeded: object[], skipped: object[]}>}
 */
export async function seedBackfill(options = {}) {
  if (!loadFollowupsEnabled(options.profilePath)) return { seeded: [], skipped: [], reason: 'disabled' };
  const trackerPath = resolveTrackerPath(options.trackerPath);
  const followupsPath = resolveFollowupsPath(options.followupsPath);

  if (!existsSync(trackerPath)) {
    throw new SeedError('ROW_NOT_FOUND', `Tracker not found at ${trackerPath}`);
  }
  const rows = readTrackerRows(trackerPath);
  const appliedRows = rows.filter(r => normalizeStatus(r.status) === 'applied');
  const cadence = resolveCadenceConfig({ profilePath: options.profilePath });
  const setDate = todayStr();

  function planFor(row) {
    const { appliedDate, appDateSource } = resolveAppliedDate(row, null);
    const nextDate = addDays(parseDate(appliedDate), cadence.applied_first);
    return { appNum: row.num, pin: formatPinLine(row.num, nextDate, setDate), nextDate, appliedDate, appDateSource, setDate };
  }

  if (options.dryRun) {
    const existingContent = existsSync(followupsPath) ? readFileSync(followupsPath, 'utf-8') : '';
    const seeded = [];
    const skipped = [];
    for (const row of appliedRows) {
      if (isAlreadySeeded(existingContent, row.num) && !options.force) {
        skipped.push({ appNum: row.num, reason: 'already-seeded' });
        continue;
      }
      try {
        seeded.push({ ...planFor(row), dryRun: true });
      } catch (err) {
        if (err instanceof SeedError && err.code === 'INVALID_DATE') {
          skipped.push({ appNum: row.num, reason: 'invalid-notes-date', detail: err.message });
        } else {
          throw err;
        }
      }
    }
    return { seeded, skipped, dryRun: true };
  }

  const lockDir = resolveLockDir(options.lockDir, followupsPath);
  const lock = await acquireFollowupsLock(lockDir, followupsPath, {
    timeoutMs: options.lockTimeoutMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_TIMEOUT_MS', 60_000),
    retryMs: options.lockRetryMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_RETRY_MS', 75),
    staleMs: options.lockStaleMs ?? envInt('CAREER_OPS_FOLLOWUPS_LOCK_STALE_MS', 10 * 60_000),
  });

  try {
    const existingContent = existsSync(followupsPath) ? readFileSync(followupsPath, 'utf-8') : null;
    const checkContent = existingContent ?? '';
    const seeded = [];
    const skipped = [];
    const newPins = [];
    for (const row of appliedRows) {
      if (isAlreadySeeded(checkContent, row.num) && !options.force) {
        skipped.push({ appNum: row.num, reason: 'already-seeded' });
        continue;
      }
      let plan;
      try {
        plan = planFor(row);
      } catch (err) {
        if (err instanceof SeedError && err.code === 'INVALID_DATE') {
          skipped.push({ appNum: row.num, reason: 'invalid-notes-date', detail: err.message });
          continue;
        }
        throw err;
      }
      seeded.push(plan);
      newPins.push(plan.pin);
    }

    if (newPins.length > 0) {
      mkdirSync(dirname(followupsPath), { recursive: true });
      writeFileAtomic(followupsPath, appendPins(existingContent, newPins));
    }

    return { seeded, skipped };
  } finally {
    releaseOrWarn(lock);
  }
}

// --- CLI ---------------------------------------------------------------

const USAGE = `Usage:
  node followup-seed.mjs <appNum> [--date YYYY-MM-DD] [--force] [--dry-run] [--json]
  node followup-seed.mjs --backfill [--force] [--dry-run] [--json]

  --date <YYYY-MM-DD>  override applied date (single-app only)
  --backfill           seed all Applied rows lacking pins/logs
  --force              re-seed even if already pinned/logged
  --dry-run            compute without writing follow-ups.md
  --json               machine-readable JSON output
  --help, -h           print this and exit`;

function parseCliArgs(argv) {
  const opts = { force: false, dryRun: false, json: false, backfill: false, date: null, appNum: null, help: false };
  const positionals = [];
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === '--date' || a.startsWith('--date=')) {
      const val = flagValue(argv.slice(i, i + 2), '--date');
      if (val === undefined) throw new SeedError('USAGE', '--date requires a value');
      opts.date = val;
      if (a === '--date') i++;
    } else if (a === '--help' || a === '-h') {
      opts.help = true;
    } else if (a === '--force') {
      opts.force = true;
    } else if (a === '--dry-run') {
      opts.dryRun = true;
    } else if (a === '--json') {
      opts.json = true;
    } else if (a === '--backfill') {
      opts.backfill = true;
    } else if (a.startsWith('--')) {
      throw new SeedError('USAGE', `Unknown flag: ${a}`);
    } else {
      positionals.push(a);
    }
  }

  if (opts.help) return opts;

  if (opts.backfill) {
    if (positionals.length !== 0) {
      throw new SeedError('USAGE', '--backfill does not take a positional appNum');
    }
    if (opts.date != null) {
      throw new SeedError('USAGE', '--date cannot be combined with --backfill (each row resolves its own apply date from its notes)');
    }
  } else {
    if (positionals.length !== 1) {
      throw new SeedError('USAGE', 'Usage: node followup-seed.mjs <appNum> [--date YYYY-MM-DD] [--force] [--dry-run] [--json]');
    }
    const raw = positionals[0];
    const n = parseInt(raw, 10);
    if (isNaN(n) || n <= 0 || String(n) !== raw.trim()) {
      throw new SeedError('USAGE', `Invalid appNum: ${raw}`);
    }
    opts.appNum = n;
  }

  return opts;
}

const EXIT_CODES = {
  USAGE: 1,
  INVALID_DATE: 1,
  NOT_APPLIED: 1,
  ROW_NOT_FOUND: 2,
  LOCK_TIMEOUT: 4,
};

/**
 * How the apply date was arrived at, for the human-readable line — empty for a
 * date that was actually measured.
 *
 * The whole point of tracking the source is that the user can see when a
 * cadence is being counted from a proxy rather than from the real submission
 * date, so an unmeasured date has to say so where they will actually look. In
 * --json it travels as `appDateSource`.
 */
function appDateNote(source) {
  if (source === 'evaluation-date') return ', from the evaluation date — notes carry no apply date';
  if (source === 'today') return ', assumed today — no apply date and no evaluation date';
  return '';
}

function reportSingle(result, json) {
  if (json) {
    console.log(JSON.stringify(result));
    return;
  }
  if (result.reason === 'disabled') {
    console.log('⏭️  Follow-ups are turned off (follow_ups.enabled: false in config/profile.yml); nothing seeded.');
    return;
  }
  const dryTag = result.dryRun ? ' [dry-run]' : '';
  if (result.seeded) {
    console.log(`✅ Seeded #${result.appNum}: next follow-up ${result.nextDate} (applied ${result.appliedDate}${appDateNote(result.appDateSource)}, set ${result.setDate})${dryTag}`);
  } else {
    console.log(`⏭️  #${result.appNum} already seeded — no-op (${result.reason})${dryTag}`);
  }
}

function reportBackfill(result, json) {
  if (json) {
    console.log(JSON.stringify(result));
    return;
  }
  if (result.reason === 'disabled') {
    console.log('⏭️  Follow-ups are turned off (follow_ups.enabled: false in config/profile.yml); nothing seeded.');
    return;
  }
  const dryTag = result.dryRun ? ' [dry-run]' : '';
  console.log(`✅ Backfill${dryTag}: seeded ${result.seeded.length}, skipped ${result.skipped.length}`);
  for (const s of result.seeded) console.log(`  + #${s.appNum}: next ${s.nextDate}${appDateNote(s.appDateSource)}`);
  for (const s of result.skipped) console.log(`  - #${s.appNum}: ${s.reason}`);
}

async function main() {
  const argv = process.argv.slice(2);
  const jsonRequested = argv.includes('--json');
  // Bound from the raw argv rather than from opts.json: a parse that fails mid-argv
  // never settles opts.json, and the two disagree for `--date --json` (#5198).
  const failWith = makeCliFailWith(jsonRequested);
  let opts;
  try {
    opts = parseCliArgs(argv);
  } catch (err) {
    failWith(EXIT_CODES[err.code] ?? 1, err.code || 'USAGE', err.message);
    return;
  }

  if (opts.help) {
    console.log(USAGE);
    process.exit(0);
  }

  try {
    if (opts.backfill) {
      const result = await seedBackfill({ dryRun: opts.dryRun, force: opts.force });
      reportBackfill(result, opts.json);
    } else {
      const result = await seedFollowup(opts.appNum, { date: opts.date, force: opts.force, dryRun: opts.dryRun });
      reportSingle(result, opts.json);
    }
    process.exit(0);
  } catch (err) {
    const code = err.code || 'ERROR';
    const exitCode = EXIT_CODES[code] ?? 1;
    failWith(exitCode, code, err.message);
  }
}

// Run (CLI only; guarded so the module is safely importable for tests).
if (isMainModule(import.meta.url)) {
  main();
}