@workit-dev/core 0.0.1 → 1.0.0

package/src/core/git.ts

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+
+const run = (cwd: string, args: string[]): { stdout: string; stderr: string; exitCode: number } => {
+  try {
+    const stdout = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      // AR-14: expected negative fixtures (non-repo dirs, unborn HEADs, bogus
+      // shas) must not inherit raw git usage/fatal stderr into the suite output.
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { stdout: stdout.trimEnd(), stderr: "", exitCode: 0 };
+  } catch (error) {
+    const e = error as { stdout?: string; stderr?: string; status?: number };
+    return {
+      stdout: (e.stdout ?? "").trimEnd(),
+      stderr: (e.stderr ?? "").trimEnd(),
+      exitCode: e.status ?? 1,
+    };
+  }
+};
+
+export const gitContext = (workspaceRoot: string, paths: string[] = []) => {
+  const cwd = workspaceRoot;
+  let failure: { stderr: string; exitCode: number } | undefined;
+
+  const runHere = (args: string[]) => {
+    const result = run(cwd, args);
+    if (!failure && result.exitCode !== 0) {
+      failure = { stderr: result.stderr, exitCode: result.exitCode };
+    }
+    return result.stdout;
+  };
+
+  const branch = runHere(["rev-parse", "--abbrev-ref", "HEAD"]) || "unknown";
+  const status_short = runHere(["status", "--porcelain"]);
+
+  const staged: string[] = [];
+  const unstaged: string[] = [];
+  const untracked: string[] = [];
+
+  for (const line of status_short.split("\n").filter(Boolean)) {
+    const code = line.slice(0, 2);
+    const file = line.slice(3);
+    if (code === "??") {
+      untracked.push(file);
+    } else {
+      if (code[0] !== " " && code[0] !== "?") staged.push(file);
+      if (code[1] !== " " && code[1] !== "?") unstaged.push(file);
+    }
+  }
+
+  const pathArgs = paths.length ? ["--", ...paths] : [];
+  const diff_stat = runHere(["diff", "--stat", ...pathArgs]);
+  const cached_stat = runHere(["diff", "--cached", "--stat", ...pathArgs]);
+
+  const stagedSet = new Set(staged);
+  const unstagedSet = new Set(unstaged);
+  const partial_staged = [...stagedSet].filter((f) => unstagedSet.has(f));
+
+  return {
+    workspace_root: cwd,
+    branch,
+    status_short,
+    staged,
+    unstaged,
+    untracked,
+    diff_stat: [diff_stat, cached_stat].filter(Boolean).join("\n"),
+    partial_staged: partial_staged.length > 0,
+    partial_staged_files: partial_staged,
+    ...(failure ? { stderr: failure.stderr, exitCode: failure.exitCode } : {}),
+  };
+};

package/src/core/gitignore.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const GITIGNORE_ENTRIES = [
+  "# workit: SDD working state (never commit)",
+  "docs/*/sdd/",
+  "",
+  "# OS / editor cruft",
+  ".DS_Store",
+  "Thumbs.db",
+  "*.swp",
+  ".idea/",
+  ".vscode/",
+  ".env",
+  "node_modules/",
+  "dist/",
+  "*.log",
+  ".cache/",
+];
+
+export const ensureProjectGitignore = (
+  workspaceRoot: string,
+  confirmed: boolean,
+): { ok: true; path: string; added: string[] } | { ok: false; error: string } => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  const file = path.join(workspaceRoot, ".gitignore");
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
+  const added: string[] = [];
+  const append: string[] = [];
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (entry.trim() === "" || existingLines.has(entry.trim())) continue;
+    append.push(entry);
+    added.push(entry);
+  }
+  if (append.length) {
+    const separator = existing && !existing.endsWith("\n") ? "\n" : "";
+    writeFileSync(
+      file,
+      existing + separator + (existing ? "\n" : "") + append.join("\n") + "\n",
+      "utf8",
+    );
+  } else if (!existsSync(file)) {
+    writeFileSync(file, "", "utf8");
+  }
+  return { ok: true, path: file, added };
+};

package/src/core/heavy-eta.ts

@@ -0,0 +1,170 @@
+// Wait estimates for the heavy-check lease (#326): how long until a waiter
+// gets a slot, from each check's last measured duration in the ledger of the
+// repo it runs in. Only the CLI imports this module; hooks never do.
+import fs from "node:fs";
+import { ledgerPath } from "../ledger";
+import { DEFAULT_MAX_HOLD_MS, formatWait, type LeaseHolder } from "./resources";
+
+/** The last measured run of a holder's or waiter's check, in ms, or null when there is none. */
+export type DurationOf = (holder: Pick<LeaseHolder, "check" | "cwd">) => number | null;
+
+/**
+ * How much of the ledger's end measuredDurations reads: the last runs are what
+ * an estimate wants, and a long-lived ledger must not be read whole on every
+ * waiter's status line.
+ */
+export const ETA_TAIL_BYTES = 512 * 1024;
+
+/** The complete lines in the last `bytes` of `file` (a cut first line is dropped). */
+function tailRows(file: string, bytes: number): string[] {
+  let fd: number;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    return [];
+  }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const span = Math.min(size, Math.max(1, bytes));
+    const buffer = Buffer.alloc(span);
+    fs.readSync(fd, buffer, 0, span, size - span);
+    const lines = buffer.toString("utf8").split("\n");
+    if (span < size) lines.shift();
+    return lines;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Each check's last measured duration per label (the check's name, or its
+ * argv for an ad-hoc run), from the last `tailBytes` of the ledger at `cwd`.
+ * A passed run wins over a later failed one, which may have stopped early; a
+ * timed-out run never counts.
+ */
+export function measuredDurations(cwd: string, tailBytes = ETA_TAIL_BYTES): Map<string, number> {
+  const passed = new Map<string, number>();
+  const any = new Map<string, number>();
+  const file = ledgerPath(cwd);
+  if (!file.ok) return passed;
+  for (const line of tailRows(file.value, tailBytes)) {
+    if (!line.trim()) continue;
+    let row: Record<string, unknown>;
+    try {
+      row = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (!row || typeof row !== "object" || row.type !== "check" || row.timedOut === true) continue;
+    const ms = row.durationMs;
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) continue;
+    const label =
+      typeof row.name === "string"
+        ? row.name
+        : Array.isArray(row.argv)
+          ? row.argv.map(String).join(" ")
+          : null;
+    if (!label) continue;
+    any.set(label, ms);
+    if (row.result === "passed") passed.set(label, ms);
+  }
+  for (const [label, ms] of any) if (!passed.has(label)) passed.set(label, ms);
+  return passed;
+}
+
+/** A holder may run this many times its last measured run before it looks stuck. */
+export const HOLD_MARGIN = 1.5;
+
+/** The most a measured run can raise the hold limit to. */
+export const MAX_DERIVED_HOLD_MS = 6 * 60 * 60_000;
+
+/**
+ * How long a check may hold its slot before it is shown `stuck?`: HOLD_MARGIN
+ * times its last measured run, never below the configured limit (default
+ * DEFAULT_MAX_HOLD_MS), which alone applies when it was never measured. The
+ * lease carries it, so auto-reap's factor applies to it too.
+ */
+export function holdLimit(measuredMs: number | null, configuredMs = DEFAULT_MAX_HOLD_MS): number {
+  if (measuredMs === null || !Number.isFinite(measuredMs) || measuredMs <= 0) return configuredMs;
+  // A corrupt or freak ledger row must not make a hung check unreapable.
+  return Math.max(
+    configuredMs,
+    Math.min(MAX_DERIVED_HOLD_MS, Math.round(measuredMs * HOLD_MARGIN)),
+  );
+}
+
+/** A DurationOf that reads each repo's ledger once. */
+export function ledgerDurations(read: (cwd: string) => Map<string, number> = measuredDurations) {
+  const byRepo = new Map<string, Map<string, number>>();
+  const durationOf: DurationOf = ({ check, cwd }) => {
+    let known = byRepo.get(cwd);
+    if (!known) {
+      try {
+        known = read(cwd);
+      } catch {
+        known = new Map();
+      }
+      byRepo.set(cwd, known);
+    }
+    return known.get(check) ?? null;
+  };
+  return durationOf;
+}
+
+export type WaitEstimate =
+  | { ms: number }
+  /** Checks with no measured run, so no estimate. */
+  | { ms: null; unmeasured: string[] };
+
+/**
+ * When a waiter behind `ahead` (in serving order) gets one of `slots`: each
+ * holder frees its slot when its last measured run would end (at once when it
+ * is already past that), and each waiter ahead takes the slot that frees
+ * first for its own measured run.
+ */
+export function estimateWait(input: {
+  slots: number;
+  holders: LeaseHolder[];
+  ahead: LeaseHolder[];
+  durationOf: DurationOf;
+  now?: number;
+}): WaitEstimate {
+  const now = input.now ?? Date.now();
+  const unmeasured = new Set<string>();
+  const measure = (holder: LeaseHolder): number => {
+    const ms = input.durationOf(holder);
+    if (ms === null) unmeasured.add(holder.check);
+    return ms ?? 0;
+  };
+  const free = input.holders.map((holder) =>
+    Math.max(0, measure(holder) - (now - Date.parse(holder.startedAt))),
+  );
+  while (free.length < Math.max(1, input.slots)) free.push(0);
+  for (const waiter of input.ahead) {
+    free.sort((a, b) => a - b);
+    free[0] += measure(waiter);
+  }
+  if (unmeasured.size) return { ms: null, unmeasured: [...unmeasured] };
+  return { ms: Math.min(...free) };
+}
+
+/** "estimated wait ~9m (last measured runs)" or "no wait estimate yet (no measured run of test)". */
+export function describeEstimate(estimate: WaitEstimate): string {
+  if (estimate.ms === null)
+    return `no wait estimate yet (no measured run of ${estimate.unmeasured.join(", ")})`;
+  return estimate.ms === 0
+    ? "estimated wait: any moment (the holders are past their last measured runs)"
+    : `estimated wait ~${formatWait(estimate.ms)} (last measured runs)`;
+}
+
+/** "~3m left", "past its last 14m run", or null when the check was never measured. */
+export function remainingNote(
+  holder: LeaseHolder,
+  durationOf: DurationOf,
+  now = Date.now(),
+): string | null {
+  const ms = durationOf(holder);
+  if (ms === null) return null;
+  const left = ms - (now - Date.parse(holder.startedAt));
+  return left > 0 ? `~${formatWait(left)} left` : `past its last ${formatWait(ms)} run`;
+}

package/src/core/heavy-lease.ts

@@ -0,0 +1,290 @@
+// Heavy-check lease hygiene (issue #608), over the lease in resources.ts:
+// prune what no longer holds or waits, reap a stuck holder, cancel queued
+// waiters, and keep a holder's heartbeat while its check prints or uses CPU.
+// Only the CLI imports this module; hooks never do.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  cancelMarker,
+  leaseQueue,
+  leaseSlots,
+  parseLease,
+  processStart,
+  queueDir,
+  reclaim,
+  staleReason,
+  stuckReason,
+  ticketStale,
+  updateLease,
+  type HeldLease,
+  type LeaseHolder,
+  type LeaseProbe,
+  type LeaseRecord,
+} from "./resources";
+
+const readLease = (file: string): LeaseRecord | null => {
+  try {
+    return parseLease(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+const slotFile = (dir: string, slot: number): string => path.join(dir, `slot-${slot}.json`);
+
+/** A cancel marker whose ticket is gone is debris after this. */
+const MARKER_TTL_MS = 10 * 60_000;
+
+export type Pruned = LeaseHolder & { reason: string; kind: "slot" | "waiter" };
+
+/**
+ * Free every slot whose holder is gone and drop every queued waiter whose
+ * process or owner is gone, each under the reclaim guard; clear old cancel
+ * markers. What `workit lock status` runs before it reads.
+ */
+export function pruneLease(dir: string, slots: number, probe: LeaseProbe = {}): Pruned[] {
+  const pruned: Pruned[] = [];
+  for (let slot = 0; slot < slots; slot += 1) {
+    const file = slotFile(dir, slot);
+    const lease = readLease(file);
+    if (!lease) continue;
+    let reason: string | null = null;
+    const removed = reclaim(file, (current) => {
+      reason = current ? staleReason(current, probe) : null;
+      return reason !== null;
+    });
+    if (removed && reason) pruned.push({ ...holderFields(lease), reason, kind: "slot" });
+  }
+  for (const entry of leaseQueue(dir, probe)) {
+    if (!entry.stale) continue;
+    const stale = entry.stale;
+    if (reclaim(entry.file, (current) => !current || ticketStale(current, probe) !== null))
+      pruned.push({ ...entry.holder, reason: stale, kind: "waiter" });
+  }
+  try {
+    const queue = queueDir(dir);
+    for (const name of fs.readdirSync(queue)) {
+      if (!name.endsWith(".cancel")) continue;
+      const marker = path.join(queue, name);
+      if (
+        !fs.existsSync(marker.slice(0, -".cancel".length)) &&
+        (probe.now ?? Date.now()) - fs.statSync(marker).mtimeMs > MARKER_TTL_MS
+      )
+        fs.rmSync(marker, { force: true });
+    }
+  } catch {
+    // No queue yet.
+  }
+  return pruned;
+}
+
+const holderFields = (lease: LeaseRecord): LeaseHolder => ({
+  pid: lease.pid,
+  check: lease.check,
+  cwd: lease.cwd,
+  session: lease.session,
+  startedAt: lease.startedAt,
+});
+
+/** A `workit lock reap` or `cancel` target: a pid, a session id (or its prefix) or a directory. */
+export type LeaseTarget = { pid: number } | { session: string } | { dir: string };
+
+export function parseTarget(text: string, cwd: string): LeaseTarget {
+  if (/^\d+$/u.test(text)) return { pid: Number(text) };
+  if (text.includes("/") || text.includes(path.sep) || text === "." || text === "..")
+    return { dir: path.resolve(cwd, text) };
+  return { session: text.replace(/…$/u, "") };
+}
+
+const within = (dir: string, cwd: string): boolean => {
+  const relative = path.relative(dir, path.resolve(cwd));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+export function matchesTarget(holder: LeaseHolder, target: LeaseTarget): boolean {
+  if ("pid" in target) return holder.pid === target.pid;
+  if ("session" in target)
+    return (
+      holder.session !== null &&
+      (holder.session === target.session ||
+        (target.session.length >= 8 && holder.session.startsWith(target.session)))
+    );
+  return within(target.dir, holder.cwd);
+}
+
+export type Reaped = LeaseHolder & { slot: number; reason: string };
+
+/**
+ * Free every slot whose live holder is stuck (stuckReason), or only those
+ * matching `target`. The holder's process is not signalled: it keeps running
+ * outside the lease, and its own release never touches the slot again.
+ */
+export function reapStuck(
+  dir: string,
+  slots: number,
+  maxHoldMs: number,
+  options: { target?: LeaseTarget | null; probe?: LeaseProbe } = {},
+): Reaped[] {
+  const reaped: Reaped[] = [];
+  for (const state of leaseSlots(dir, slots, options.probe, maxHoldMs)) {
+    if (!state.holder || !state.stuck || state.stale) continue;
+    if (options.target && !matchesTarget(state.holder, options.target)) continue;
+    const file = slotFile(dir, state.slot);
+    let reason: string | null = null;
+    const removed = reclaim(file, (current) => {
+      reason =
+        current && !staleReason(current, options.probe)
+          ? stuckReason(current, maxHoldMs, options.probe?.now)
+          : null;
+      return reason !== null;
+    });
+    if (removed && reason)
+      reaped.push({ ...state.holder, stuck: reason, slot: state.slot, reason });
+  }
+  return reaped;
+}
+
+export type Cancelled = LeaseHolder & { how: "marker" | "signal" | "gone" };
+
+/**
+ * Drop the queued waiters matching `target`. A waiter that reads cancel
+ * markers gets one and its ticket is removed at once; an older waiter gets
+ * SIGTERM, which makes it leave the queue itself.
+ */
+export function cancelWaiters(
+  dir: string,
+  target: LeaseTarget,
+  by: string,
+  probe: LeaseProbe & { signal?: (pid: number) => boolean } = {},
+): Cancelled[] {
+  const cancelled: Cancelled[] = [];
+  for (const entry of leaseQueue(dir, probe)) {
+    if (!matchesTarget(entry.holder, target)) continue;
+    const record = entry.record;
+    if (entry.stale || !record) {
+      if (reclaim(entry.file, (current) => !current || ticketStale(current, probe) !== null))
+        cancelled.push({ ...entry.holder, how: "gone" });
+      continue;
+    }
+    if (record.cancellable) {
+      try {
+        fs.writeFileSync(
+          cancelMarker(entry.file),
+          `${JSON.stringify({ by, at: new Date().toISOString() })}\n`,
+          { mode: 0o600 },
+        );
+      } catch {
+        continue;
+      }
+      if (readLease(entry.file)?.id === record.id) fs.rmSync(entry.file, { force: true });
+      cancelled.push({ ...entry.holder, how: "marker" });
+      continue;
+    }
+    const start = record.processStart ? processStart(record.pid) : null;
+    if (record.processStart && start !== record.processStart) continue;
+    if ((probe.signal ?? terminate)(record.pid)) cancelled.push({ ...entry.holder, how: "signal" });
+  }
+  return cancelled;
+}
+
+const terminate = (pid: number): boolean => {
+  try {
+    process.kill(pid, "SIGTERM");
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** `[[dd-]hh:]mm:ss[.cc]` from `ps` as hundredths of a second, or null. */
+function parseCpuTime(text: string): number | null {
+  const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)$/u.exec(text);
+  if (!match) return null;
+  const [, days, hours, minutes, seconds] = match;
+  const total =
+    (Number(days ?? 0) * 24 + Number(hours ?? 0)) * 3600 + Number(minutes) * 60 + Number(seconds);
+  return Math.round(total * 100);
+}
+
+/** CPU hundredths of a second used so far by process group `pgid` (macOS, via `ps`), or null. */
+export function psGroupCpu(pgid: number, run: typeof spawnSync = spawnSync): number | null {
+  const result = run("ps", ["-axo", "pgid=,cputime="], { encoding: "utf8", timeout: 5000 });
+  if (result.error || result.status !== 0 || typeof result.stdout !== "string") return null;
+  let total = 0;
+  let seen = false;
+  for (const line of result.stdout.split("\n")) {
+    const [group, cputime] = line.trim().split(/\s+/u);
+    if (Number(group) !== pgid || cputime === undefined) continue;
+    const ticks = parseCpuTime(cputime);
+    if (ticks === null) continue;
+    seen = true;
+    total += ticks;
+  }
+  return seen ? total : null;
+}
+
+/** CPU ticks used so far by the processes of group `pgid` (Linux, macOS), or null. */
+export function groupCpuTicks(pgid: number): number | null {
+  if (!(pgid > 0)) return null;
+  if (process.platform === "darwin") return psGroupCpu(pgid);
+  if (process.platform !== "linux") return null;
+  let names: string[];
+  try {
+    names = fs.readdirSync("/proc");
+  } catch {
+    return null;
+  }
+  let total = 0;
+  let seen = false;
+  for (const name of names) {
+    if (!/^\d+$/u.test(name)) continue;
+    let stat: string;
+    try {
+      stat = fs.readFileSync(`/proc/${name}/stat`, "utf8");
+    } catch {
+      continue;
+    }
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    if (Number(fields[2]) !== pgid) continue;
+    seen = true;
+    // utime, stime, cutime, cstime: fields 14-17 of /proc/<pid>/stat.
+    total += [11, 12, 13, 14].reduce((sum, at) => sum + (Number(fields[at]) || 0), 0);
+  }
+  return seen ? total : null;
+}
+
+/** Heartbeats are written at most this often. */
+export const HEARTBEAT_EVERY_MS = 30_000;
+
+export type Heartbeat = { touch: () => void; stop: () => void };
+
+/**
+ * Refresh the held lease's `heartbeatAt` every `everyMs` while its check
+ * printed since the last beat (`touch`) or its process group used CPU.
+ */
+export function startHeartbeat(
+  lease: HeldLease,
+  options: { everyMs?: number; cpu?: () => number | null; now?: () => number } = {},
+): Heartbeat {
+  let active = false;
+  let lastCpu: number | null = null;
+  const cpu = options.cpu ?? (() => (lease.record.pgid ? groupCpuTicks(lease.record.pgid) : null));
+  const timer = setInterval(() => {
+    const ticks = cpu();
+    const moved = ticks !== null && lastCpu !== null && ticks > lastCpu;
+    if (ticks !== null) lastCpu = ticks;
+    if (!active && !moved) return;
+    active = false;
+    updateLease(lease, {
+      heartbeatAt: new Date(options.now?.() ?? Date.now()).toISOString(),
+    });
+  }, options.everyMs ?? HEARTBEAT_EVERY_MS);
+  timer.unref?.();
+  return {
+    touch: () => {
+      active = true;
+    },
+    stop: () => clearInterval(timer),
+  };
+}