@avee1234/worklease 0.1.1

package/src/adapters/git-hook.js

@@ -0,0 +1,164 @@
+// worklease — git pre-commit hook adapter (the dogfood surface).
+//
+// This is what makes worklease actually prevent collisions in a live
+// parallel-agent setup: a pre-commit hook that runs `worklease check` on the
+// files a commit is about to change and surfaces any overlap with another
+// agent's active claim. The git plumbing lives here; the coordination decision
+// is delegated to the existing pure `check` core, so this adapter adds a new
+// *surface*, not a second notion of "conflict".
+//
+// Design, matching roadmap principle #1 ("advisory, not enforcing"): the hook
+// is warn-only by default (prints conflicts, exits 0, never blocks a commit).
+// `worklease hook install --strict` bakes in blocking mode, where a conflict
+// exits 1 and git aborts the commit. Both modes run the same `hook run` verb;
+// the only difference is whether a conflict is fatal.
+//
+// Zero runtime dependencies: `git` is invoked via `child_process`, everything
+// else reuses this package's own modules.
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  mkdirSync,
+} from "node:fs";
+import { dirname, join, isAbsolute } from "node:path";
+import { loadRegistry, defaultRegistryPath } from "../registry.js";
+import { check } from "../check.js";
+
+// Markers delimiting worklease's managed region inside `.git/hooks/pre-commit`.
+// Install rewrites only the text *between* (and including) these lines, so any
+// pre-existing hook body a user or another tool wrote is preserved verbatim.
+const START = "# >>> worklease >>>";
+const END = "# <<< worklease <<<";
+
+// --- staged-path check (the check-on-staged-paths function) ----------------
+
+// stagedPaths({ cwd }) → the repo-relative paths staged for the pending commit.
+//
+// These are the "files about to change". A staged path is already a concrete
+// path, and every concrete path is a valid glob in the committed subset (a
+// literal), so the paths feed straight into `check` — `check("src/auth/x.ts",
+// …)` overlaps a claim on `src/auth/**`. No path→glob translation is needed.
+// A non-git directory (or any git failure) yields [] — the caller then treats
+// the commit as clear, since an advisory hook must never wedge a commit.
+export function stagedPaths(opts = {}) {
+  const { cwd = process.cwd() } = opts;
+  const r = spawnSync("git", ["diff", "--cached", "--name-only"], {
+    cwd,
+    encoding: "utf8",
+  });
+  if (r.status !== 0 || typeof r.stdout !== "string") return [];
+  return r.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+// checkStagedPaths(paths, { registry, agent, now }) → { clear, conflicts, notes }
+//
+// The core the hook runs: load the registry once and run the shared `check`
+// core over the staged paths. Empty input short-circuits to clear (an empty or
+// docs-only commit can never collide). `notes` carries loadRegistry's
+// skipped/tampered/expired warnings so the caller can surface them — a dropped
+// line means `check` might call a held path clear, the exact collision this
+// tool exists to catch.
+export function checkStagedPaths(paths, opts = {}) {
+  const { registry = null, agent = null, now = Date.now() } = opts;
+  if (!paths || paths.length === 0) {
+    return { clear: true, conflicts: [], notes: [] };
+  }
+  const path = registry || defaultRegistryPath();
+  const { claims, notes } = loadRegistry(path, { now });
+  const result = check(paths, claims, { agent, now });
+  return { clear: result.clear, conflicts: result.conflicts, notes };
+}
+
+// --- hook install ----------------------------------------------------------
+
+// gitPath(cwd, rel) → the absolute path of a file inside the git dir, or null
+// if cwd is not a git repo. Uses `git rev-parse --git-path` so it resolves
+// correctly for worktrees (where hooks live in the shared common dir) — the
+// exact setup worklease targets, since fleets run in parallel worktrees.
+function gitPath(cwd, rel) {
+  const r = spawnSync("git", ["rev-parse", "--git-path", rel], {
+    cwd,
+    encoding: "utf8",
+  });
+  if (r.status !== 0 || typeof r.stdout !== "string") return null;
+  const p = r.stdout.trim();
+  if (!p) return null;
+  return isAbsolute(p) ? p : join(cwd, p);
+}
+
+// hookPath(cwd) → absolute path of this repo's pre-commit hook, or null if cwd
+// is not a git repository.
+export function hookPath(cwd = process.cwd()) {
+  return gitPath(cwd, "hooks/pre-commit");
+}
+
+// renderHookBlock(strict) → the marker-delimited shell block install writes.
+//
+// The block delegates to `worklease hook run`, guarded by `command -v` so a
+// clone where `worklease` isn't on PATH degrades gracefully (no hook error,
+// consistent with advisory-first). The strict/warn policy lives entirely in
+// `hook run`; install just chooses whether to pass `--strict`, keeping the
+// exit-code decision in one place.
+export function renderHookBlock(strict = false) {
+  return [
+    START,
+    "# Managed by `worklease hook install` — runs `worklease check` on staged files.",
+    strict
+      ? "# Mode: strict — a claim conflict blocks the commit (exit 1)."
+      : "# Mode: advisory — conflicts are printed but never block the commit.",
+    "if command -v worklease >/dev/null 2>&1; then",
+    strict ? "  worklease hook run --strict" : "  worklease hook run",
+    "fi",
+    END,
+  ].join("\n");
+}
+
+// installHook({ cwd, strict }) → { path, action, strict }
+//
+// Idempotent, existing-hook-preserving install:
+//   - no pre-commit hook yet         → create one (shebang + block)  ["created"]
+//   - a hook with our markers        → replace only the marked block ["updated"]
+//   - a hook without our markers      → append the block after it     ["appended"]
+// Re-running install therefore converges to a single managed block and never
+// duplicates it or clobbers a hand-written hook. The file is chmod +x so git
+// will execute it.
+export function installHook(opts = {}) {
+  const { cwd = process.cwd(), strict = false } = opts;
+  const path = hookPath(cwd);
+  if (!path) {
+    throw new Error("not a git repository (run `git init` first)");
+  }
+
+  const block = renderHookBlock(strict);
+  let content;
+  let action;
+
+  if (!existsSync(path)) {
+    content = `#!/bin/sh\n${block}\n`;
+    action = "created";
+  } else {
+    const existing = readFileSync(path, "utf8");
+    const s = existing.indexOf(START);
+    const e = existing.indexOf(END);
+    if (s !== -1 && e !== -1 && e > s) {
+      content = existing.slice(0, s) + block + existing.slice(e + END.length);
+      action = "updated";
+    } else {
+      const sep = existing.endsWith("\n") ? "" : "\n";
+      content = `${existing}${sep}\n${block}\n`;
+      action = "appended";
+    }
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  chmodSync(path, 0o755);
+  return { path, action, strict };
+}

package/src/check.js

@@ -0,0 +1,43 @@
+// worklease — `check` core (pure orchestration over `globsOverlap`).
+//
+// Given planned-edit globs and a resolved registry array, report whether the
+// plan overlaps any *active* claim held by *another* agent. No filesystem, no
+// clock: time is injected as `opts.now` so expiry is deterministic in tests.
+
+import { globsOverlap } from "./glob.js";
+
+// check(plannedGlobs, registry, opts) → { clear, conflicts }
+//
+//   opts.agent — the caller's id; a claim by this agent counts as clear (you may
+//                edit what you already hold). If null/undefined, no same-agent
+//                filtering is applied (every active claim is treated as another
+//                agent's — the safe default).
+//   opts.now   — epoch ms used to evaluate `expires`; injected for determinism.
+//
+// A claim is a conflict iff ALL of: status === "active", its `expires` is still
+// in the future, its `agent` differs from the caller, and at least one of its
+// globs intersects a planned glob. Each conflict's `overlapping_globs` is the
+// deduped, sorted subset of THAT claim's globs which overlap the plan.
+export function check(plannedGlobs, registry, opts = {}) {
+  const { agent = null, now = Date.now() } = opts;
+
+  const conflicts = [];
+  for (const claim of registry) {
+    if (claim.status !== "active") continue;
+    if (!(Date.parse(claim.expires) > now)) continue; // expired-by-time = clear
+    if (agent != null && claim.agent === agent) continue; // own claim = clear
+
+    const overlapping = claim.globs.filter((g) =>
+      plannedGlobs.some((p) => globsOverlap(p, g))
+    );
+    if (overlapping.length) {
+      conflicts.push({ claim, overlapping_globs: dedupeSort(overlapping) });
+    }
+  }
+
+  return { clear: conflicts.length === 0, conflicts };
+}
+
+function dedupeSort(globs) {
+  return [...new Set(globs)].sort();
+}

package/src/claim.js

@@ -0,0 +1,70 @@
+// worklease — `claim` core (pure claim constructor + ttl parsing).
+//
+// `makeClaim` builds a valid claim record with a deterministic content-hash id
+// and a computed `expires`, with NO I/O and NO clock — `created` is injected via
+// `meta`, so the result is fully determined by its inputs and unit-testable. The
+// CLI (`bin/worklease.js`) is the only part that reads the clock and appends to
+// the registry.
+
+import { computeRecordId } from "./registry.js";
+
+// makeClaim(globs, meta) → a claim record matching #1's CLAIM_FIELDS order.
+//
+//   meta.agent       — who is filing the claim
+//   meta.intent      — why (what work the globs are for)
+//   meta.ttl_seconds — lease length in whole seconds (integer)
+//   meta.created     — ISO-8601-UTC timestamp the claim is filed at
+//
+// `expires` is `created + ttl_seconds` to the millisecond, so #1's
+// EXPIRES_MISMATCH cross-check holds by construction. `id` is the registry's
+// shared content hash of the whole record (its `id` excluded), so a claim's id
+// IS its content hash and it resolves cleanly through #4's store — one hasher
+// across every record type. `status` is always "active" on creation. Pure and
+// total: it does not throw and does no validation — the CLI validates the
+// finished record via #1's `validateClaim`.
+export function makeClaim(globs, meta = {}) {
+  const { agent, intent, ttl_seconds, created } = meta;
+  const expires = isoAddSeconds(created, ttl_seconds);
+  const record = {
+    agent,
+    globs,
+    intent,
+    ttl_seconds,
+    created,
+    expires,
+    status: "active",
+  };
+  return { id: computeRecordId(record), ...record };
+}
+
+// parseTtl(input) → integer seconds, or null on anything invalid.
+//
+// Accepts a compact duration shorthand (`<n>s`, `<n>m`, `<n>h`) or a bare
+// positive integer interpreted as seconds (string or number). A bad unit, a
+// non-integer, zero, a negative, or empty input returns null (never throws) so
+// the caller can print one clear error and exit.
+export function parseTtl(input) {
+  if (typeof input === "number") {
+    return Number.isInteger(input) && input > 0 ? input : null;
+  }
+  if (typeof input !== "string") return null;
+
+  const s = input.trim();
+  if (/^\d+$/.test(s)) {
+    const n = Number(s);
+    return n > 0 ? n : null; // bare seconds; "0" → null
+  }
+
+  const m = /^(\d+)(s|m|h)$/.exec(s);
+  if (!m) return null;
+  const n = Number(m[1]);
+  if (n <= 0) return null; // "0m" → null
+  const mult = { s: 1, m: 60, h: 3600 }[m[2]];
+  return n * mult;
+}
+
+// created + ttl_seconds as an ISO-8601-UTC string. With whole-second `created`
+// and integer `ttl_seconds`, epoch-ms equality with #1's derived value holds.
+function isoAddSeconds(created, ttl_seconds) {
+  return new Date(Date.parse(created) + ttl_seconds * 1000).toISOString();
+}

package/src/conformance.js

@@ -0,0 +1,82 @@
+// worklease — `conformance` core (pure orchestration over `globsOverlap`).
+//
+// The after-the-fact metric: given a resolved registry and a set of *merges*
+// (the files each agent actually touched), score whether the fleet coordinated.
+// For each `(agent, file)` change it asks two questions — did the acting agent
+// hold a claim covering the file, and did the file fall under a *different*
+// agent's live claim? — and partitions every change into exactly one of
+// {respected, violation, warning}. No filesystem, no clock: all time comparisons
+// use the merge record's own `at` (or fall back to claim `status`), so the core
+// is pure and deterministic.
+//
+// A touched file is a concrete (wildcard-free) glob, so "does file F fall under
+// claim glob G?" is exactly `globsOverlap(F, G)` from #3 — no new matching logic.
+
+import { globsOverlap } from "./glob.js";
+import { isIso8601Utc } from "./schema.js";
+
+// Is claim `c` held/active at instant `at` (ISO string)? Temporal window
+// [created, expires): created ≤ at < expires. Malformed timestamps are treated
+// as "not held/active" (conservative — never invents coverage or a violation).
+function within(c, at) {
+  if (!isIso8601Utc(at) || !isIso8601Utc(c.created) || !isIso8601Utc(c.expires)) {
+    return false;
+  }
+  const t = Date.parse(at);
+  return Date.parse(c.created) <= t && t < Date.parse(c.expires);
+}
+
+// Status fallback for coverage when a change has no `at`: any non-expired claim.
+function notExpired(c) {
+  return c.status !== "expired";
+}
+
+// conformance(claims, merges, opts) → { score, total, respected, violations, warnings }
+//
+//   claims  — resolved registry array (latest record per id), each claim
+//             `{ id, agent, globs[], intent, ttl_seconds, created, expires, status }`.
+//   merges  — array of `{ agent, files: string[], at? }`; flattened to one change
+//             per `(agent, file)`.
+//   opts    — reserved; no clock needed (this is an after-the-fact audit).
+//
+// A change by agent A on file F at time T is:
+//   - covered   — A held a matching claim at T (temporal `within` if `at`,
+//                 else non-expired status).
+//   - violation — a DIFFERENT agent B held a matching claim live at T (temporal
+//                 if `at`, else `status === "active"`); one entry per such claim.
+//   - respected — covered ∧ not a violation (the coordination numerator).
+//   - warning   — uncovered ∧ not a violation (edited an unclaimed file).
+// A colliding change is a violation even if A also held a claim (double-claim).
+export function conformance(claims, merges, opts = {}) {
+  const changes = merges.flatMap((m) =>
+    m.files.map((file) => ({ agent: m.agent, file, at: m.at }))
+  );
+
+  const violations = [];
+  const warnings = [];
+  let respected = 0;
+
+  for (const { agent, file, at } of changes) {
+    const matching = claims.filter((c) => c.globs.some((g) => globsOverlap(file, g)));
+
+    const held = (c) => (at != null ? within(c, at) : notExpired(c));
+    const live = (c) => (at != null ? within(c, at) : c.status === "active");
+
+    const covered = matching.some((c) => c.agent === agent && held(c));
+    const colliding = matching.filter((c) => c.agent !== agent && live(c));
+
+    if (colliding.length) {
+      for (const c of colliding) {
+        violations.push({ agent, file, conflicting_claim: c });
+      }
+    } else if (covered) {
+      respected += 1;
+    } else {
+      warnings.push({ agent, file });
+    }
+  }
+
+  const total = changes.length;
+  const score = total === 0 ? 1 : respected / total;
+  return { score, total, respected, violations, warnings };
+}

package/src/glob.js

@@ -0,0 +1,92 @@
+// worklease — glob intersection (pure, zero-dependency, no filesystem access).
+//
+// Decides whether two globs from the committed subset (`**`, `*`, `/`, literals)
+// could match a common concrete path. This is the conservative *satisfiability*
+// rule used by `check`: two globs overlap iff there EXISTS at least one concrete
+// path that matches both — evaluated purely over the glob strings, never the
+// working tree, so it is safe for a check that runs *before* the edit (the file
+// may not exist yet). Symmetric by construction: overlap(a, b) === overlap(b, a).
+//
+// The problem is pattern-vs-pattern satisfiability at two levels — across
+// segments (`**` spans zero or more whole segments) and within a segment (`*`
+// matches any run of characters but never crosses `/`). Each level is a memoized
+// two-pointer recursion, bounding work to O(m·n) so stacked `**` cannot blow up.
+
+// Normalize a glob string into an array of segment tokens.
+//   - strip a single leading "./"
+//   - collapse repeated "/" into one
+//   - drop a single trailing "/" (treat `src/auth/` as `src/auth`)
+//   - split on "/"
+//   - within each non-"**" segment, collapse any run of "*" to a single "*"
+//     (so `a**b` → `a*b`); "**" keeps its cross-segment meaning only when it is
+//     the entire segment.
+function normalize(glob) {
+  let g = glob;
+  if (g.startsWith("./")) g = g.slice(2);
+  g = g.replace(/\/+/g, "/");
+  if (g.length > 1 && g.endsWith("/")) g = g.slice(0, -1);
+  return g
+    .split("/")
+    .map((seg) => (seg === "**" ? "**" : seg.replace(/\*+/g, "*")));
+}
+
+// Within-segment overlap: do single-segment patterns `a` and `b` generate a
+// common string? `*` matches any run of characters (including empty); every
+// other character is a case-sensitive literal. Memoized two-pointer over chars.
+function segmentOverlap(a, b) {
+  const memo = new Map();
+  const seg = (i, j) => {
+    if (i === a.length && j === b.length) return true;
+    const key = i * (b.length + 1) + j;
+    if (memo.has(key)) return memo.get(key);
+    let res;
+    if (i < a.length && a[i] === "*") {
+      // `*` consumes zero chars of `b`, or one-or-more (advance `b`).
+      res = seg(i + 1, j) || (j < b.length && seg(i, j + 1));
+    } else if (j < b.length && b[j] === "*") {
+      res = seg(i, j + 1) || (i < a.length && seg(i + 1, j));
+    } else if (i === a.length || j === b.length) {
+      res = false; // one side ran out with a literal still pending
+    } else if (a[i] === b[j]) {
+      res = seg(i + 1, j + 1);
+    } else {
+      res = false;
+    }
+    memo.set(key, res);
+    return res;
+  };
+  return seg(0, 0);
+}
+
+// Segment-level overlap: `A`, `B` are segment-token arrays. A token is either
+// the literal "**" (matches zero or more whole segments) or a single-segment
+// pattern. Memoized on (i, j) so "**"-vs-"**" stays O(|A|·|B|).
+function segmentsOverlap(A, B) {
+  const memo = new Map();
+  const overlap = (i, j) => {
+    if (i === A.length && j === B.length) return true;
+    const key = i * (B.length + 1) + j;
+    if (memo.has(key)) return memo.get(key);
+    let res;
+    if (i < A.length && A[i] === "**") {
+      // "**" matches zero segments, or one-or-more (consume a B segment).
+      res = overlap(i + 1, j) || (j < B.length && overlap(i, j + 1));
+    } else if (j < B.length && B[j] === "**") {
+      res = overlap(i, j + 1) || (i < A.length && overlap(i + 1, j));
+    } else if (i === A.length || j === B.length) {
+      res = false; // one side ran out with a real segment still pending
+    } else if (!segmentOverlap(A[i], B[j])) {
+      res = false; // this pair of segments can't align
+    } else {
+      res = overlap(i + 1, j + 1); // aligned — advance both
+    }
+    memo.set(key, res);
+    return res;
+  };
+  return overlap(0, 0);
+}
+
+// Public API: do two globs share at least one concrete matching path?
+export function globsOverlap(globA, globB) {
+  return segmentsOverlap(normalize(globA), normalize(globB));
+}

package/src/index.js

@@ -0,0 +1,39 @@
+// worklease — public entry point (package `main`).
+// Re-exports the pure schema/validator API.
+// Re-exports the pure `check` / glob-overlap API.
+// Re-exports the pure `conformance` after-the-fact coordination-score API.
+// Re-exports the pure `makeClaim` / `parseTtl` claim-constructor API.
+// Re-exports the append-only registry store (`loadRegistry`, `appendRecord`, …).
+// Re-exports the git pre-commit adapter (`checkStagedPaths`, `installHook`, …).
+
+export {
+  validateClaim,
+  validateRegistry,
+  isIso8601Utc,
+  isAllowedGlob,
+  STATUSES,
+  CLAIM_FIELDS,
+  ERROR_CODES,
+} from "./schema.js";
+export { globsOverlap } from "./glob.js";
+export { check } from "./check.js";
+export { conformance } from "./conformance.js";
+export { makeClaim, parseTtl } from "./claim.js";
+export {
+  canonicalize,
+  computeRecordId,
+  resolveRecords,
+  loadRegistry,
+  appendRecord,
+  defaultRegistryPath,
+  listActive,
+  formatRelative,
+  shortId,
+} from "./registry.js";
+export {
+  stagedPaths,
+  checkStagedPaths,
+  hookPath,
+  renderHookBlock,
+  installHook,
+} from "./adapters/git-hook.js";