@workit-dev/core 0.0.1 → 1.0.0

package/src/core/skill-manifests.ts

@@ -0,0 +1,173 @@
+import { cpSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const WORKIT_METHOD_SKILLS = [
+  "workit-shape",
+  "workit-implement",
+  "workit-review",
+  "workit-debug",
+  "workit-ship",
+  "workit-continue",
+  "workit-bdd",
+  "workit-test-audit",
+  "workit-deslop",
+  "workit-fanout",
+  "workit-verify-app",
+  "workit-retro",
+  "workit-architecture",
+] as const;
+
+export type WorkitSkill = (typeof WORKIT_METHOD_SKILLS)[number];
+
+/** wk- slash aliases (one per skill): alias → method skill. An alias routes
+ * through policy to model skills; an alias never calls another alias. */
+export const WORKIT_SKILL_ALIASES = {
+  "wk-shape": "workit-shape",
+  "wk-implement": "workit-implement",
+  "wk-review": "workit-review",
+  "wk-debug": "workit-debug",
+  "wk-ship": "workit-ship",
+  "wk-continue": "workit-continue",
+  "wk-bdd": "workit-bdd",
+  "wk-test-audit": "workit-test-audit",
+  "wk-deslop": "workit-deslop",
+  "wk-fanout": "workit-fanout",
+  "wk-verify-app": "workit-verify-app",
+  "wk-retro": "workit-retro",
+  "wk-architecture": "workit-architecture",
+} as const satisfies Record<string, WorkitSkill>;
+
+/**
+ * The words a user types that should load each skill. Each skill's
+ * description and its bootstrap routing line carry every one of them, and no
+ * two skills share one (checked by test), so a trigger routes to one skill.
+ */
+export const WORKIT_SKILL_TRIGGERS: Readonly<Record<WorkitSkill, readonly string[]>> = {
+  "workit-shape": ["brainstorm", "plan", "spec", "grill", "should we"],
+  "workit-implement": ["implement", "build", "add a feature"],
+  "workit-review": ["review", "blast radius"],
+  "workit-debug": ["bug", "broken", "flaky", "regression"],
+  "workit-ship": ["ship", "babysit", "CI", "merge"],
+  "workit-continue": ["resume", "pick up", "handoff", "interruption"],
+  "workit-bdd": ["BDD", "TDD", "acceptance criteria", "Given/When/Then"],
+  "workit-test-audit": ["test audit", "tautology", "weak tests"],
+  "workit-deslop": ["deslop", "slop", "dead code"],
+  "workit-fanout": ["fan out", "parallelize", "parallel agents", "swarm"],
+  "workit-verify-app": ["verify the app", "smoke test", "prove it works"],
+  "workit-retro": ["retro"],
+  "workit-architecture": ["architecture"],
+};
+
+/** The `description:` frontmatter value of a SKILL.md (one line, unquoted). */
+export const skillDescription = (skillMd: string): string => {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd)?.[1] ?? "";
+  const line = /^description:\s*(.+)$/m.exec(frontmatter)?.[1] ?? "";
+  return line.trim().replace(/^(["'])(.*)\1$/, "$2");
+};
+
+/** A generated Cursor slash command for one alias; `commands/` is committed
+ * because Cursor discovers the plugin from git, so the build writes these and
+ * a drift test compares them to the committed copies. */
+export const cursorCommandText = (alias: string, skill: string, description: string): string =>
+  `# /${alias}\n\nLoad and apply the bundled \`${skill}\` skill. ${description}\n\nExtra context: $ARGUMENTS\n`;
+
+/** The hosts whose build writes a copy of the skills. */
+export type SkillHost = "claude-code" | "cursor" | "codex" | "opencode" | "pi";
+
+/**
+ * How an agent on `host` loads another Workit skill. A skill named only in
+ * prose does not reliably load; naming the host's own loading mechanism does
+ * (mattpocock/skills 1.3.0). Claude Code namespaces plugin skills, so
+ * `workit-bdd` is `workit:bdd` there.
+ */
+export const skillLoadWording = (host: SkillHost, skill: string): string => {
+  switch (host) {
+    case "claude-code":
+      return `call the Skill tool with \`workit:${skill.replace(/^workit-/, "")}\``;
+    case "opencode":
+      return `call the skill tool with \`${skill}\``;
+    default:
+      return `read the \`${skill}\` skill's SKILL.md and follow it`;
+  }
+};
+
+/** A canonical cross-skill reference: a method skill's name alone in parentheses. */
+const SKILL_REFERENCE = /\((workit-[a-z-]+)\)/g;
+
+/** A canonical skill file with each cross-skill reference in the host's load wording. */
+export const renderSkillText = (text: string, host: SkillHost): string =>
+  text.replace(SKILL_REFERENCE, (match, name: string) =>
+    (WORKIT_METHOD_SKILLS as readonly string[]).includes(name)
+      ? `(${skillLoadWording(host, name)})`
+      : match,
+  );
+
+/** Copy one canonical skill directory to `out`, rendering its Markdown for `host`. */
+export const copySkillForHost = (source: string, out: string, host: SkillHost): void => {
+  cpSync(source, out, { recursive: true });
+  const pending = [out];
+  while (pending.length > 0) {
+    const dir = pending.pop()!;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) pending.push(file);
+      else if (entry.name.endsWith(".md"))
+        writeFileSync(file, renderSkillText(readFileSync(file, "utf8"), host));
+    }
+  }
+};
+
+export const skillManifestNames = (root: string): string[] =>
+  existsSync(root)
+    ? readdirSync(root)
+        .filter((name) => existsSync(path.join(root, name, "SKILL.md")))
+        .toSorted()
+    : [];
+
+export const validateSkillManifests = (
+  root: string,
+  expected: readonly string[],
+  label: string,
+): string | null => {
+  const actual = skillManifestNames(root);
+  const missing = expected.filter((name) => !actual.includes(name));
+  const extra = actual.filter((name) => !expected.includes(name));
+  return missing.length === 0 && extra.length === 0
+    ? null
+    : `${label} mismatch at ${root} (missing: ${missing.join(", ") || "none"}; extra: ${extra.join(", ") || "none"})`;
+};
+
+export const validateCursorSkills = (
+  pluginDir: string,
+  expected: readonly string[] = WORKIT_METHOD_SKILLS,
+): string | null => {
+  const workit = validateSkillManifests(
+    path.join(pluginDir, "skills"),
+    expected,
+    "Cursor Workit skills",
+  );
+  if (workit) return workit;
+  const pending = [path.join(pluginDir, "skills")];
+  while (pending.length > 0) {
+    const dir = pending.pop()!;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) pending.push(file);
+      else if (
+        (statSync(file).mode & 0o111) !== 0 ||
+        readFileSync(file).subarray(0, 2).toString("latin1") === "#!"
+      ) {
+        return `Cursor vendor contains active file: ${file}`;
+      }
+    }
+  }
+  return null;
+};
+
+if (import.meta.main) {
+  const error = validateCursorSkills(process.argv[2] ?? "");
+  if (error) {
+    process.stderr.write(`${error}\n`);
+    process.exit(1);
+  }
+}

package/src/core/store-lock.ts

@@ -0,0 +1,374 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+import * as z from "zod";
+import { canonicalJson } from "./task-contract";
+import { checkoutSlug, resolveStore } from "../store/paths";
+
+/**
+ * Ownership rules for the workit store's locks: a checkout's
+ * `checkouts/<slug>/metadata.lock` and each task's `tasks/<id>/lock`.
+ *
+ * The lock is a short mutex around one store mutation (or one managed effect).
+ * A lock whose owner is gone is reclaimed automatically; a lock whose owner is
+ * alive is contention, which callers report as retryable `busy`.
+ */
+
+export type MetadataLock = {
+  pid: number;
+  processStart: string | null;
+  host: string;
+  nonce: string;
+};
+
+const metadataLockSchema = z
+  .object({
+    pid: z.number().int().nonnegative().safe(),
+    processStart: z.string().nullable(),
+    host: z.string().min(1),
+    nonce: z.string().min(1),
+    /** Written by ≤4.x managed external actions; read and ignored (D17). */
+    externalAction: z.literal(true).optional(),
+  })
+  .strict();
+
+/** A lock from another host cannot be checked for liveness; trust it this long. */
+export const FOREIGN_LOCK_TTL_MS = 10 * 60_000;
+/** An empty or unparseable lock is a writer mid-create; after this it is debris. */
+export const UNREADABLE_LOCK_TTL_MS = 30_000;
+/** A reclaim guard lives for microseconds; one older than this was abandoned. */
+export const RECLAIM_GUARD_TTL_MS = 30_000;
+/**
+ * Total time a mutation waits for a live holder before returning `busy`. The
+ * wait blocks the calling thread, so in-process hosts (OpenCode, MCP, Pi) keep
+ * the short default; the CLI raises it for its own process.
+ */
+export const IN_PROCESS_LOCK_TIMEOUT_MS = 250;
+let defaultLockTimeoutMs = IN_PROCESS_LOCK_TIMEOUT_MS;
+export const defaultLockTimeout = (): number => defaultLockTimeoutMs;
+/**
+ * The wait for a lock that a CLI process may hold longer (the ledger's
+ * network-filesystem lock): `cliMs` once the process raised the default
+ * (the CLI does), else the in-process cap.
+ */
+export const hostAwareLockTimeout = (cliMs: number): number =>
+  defaultLockTimeoutMs > IN_PROCESS_LOCK_TIMEOUT_MS ? cliMs : IN_PROCESS_LOCK_TIMEOUT_MS;
+export const setDefaultLockTimeout = (ms: number): void => {
+  defaultLockTimeoutMs = ms;
+};
+
+export const parseMetadataLock = (raw: string): MetadataLock => {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
+  }
+  const parsed = metadataLockSchema.safeParse(value);
+  if (!parsed.success)
+    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
+  return parsed.data;
+};
+
+/** Lenient variant for the acquire loop: an unreadable lock is classified by age. */
+export const parseMetadataLockOrNull = (raw: string): MetadataLock | null => {
+  try {
+    return parseMetadataLock(raw);
+  } catch {
+    return null;
+  }
+};
+
+export const sameMetadataLock = (left: unknown, right: MetadataLock): boolean => {
+  const parsed = metadataLockSchema.safeParse(left);
+  return parsed.success && canonicalJson(parsed.data) === canonicalJson(right);
+};
+
+/** Field 22 (starttime) of /proc/<pid>/stat; parsed after the last ")" so a comm with spaces cannot shift it. */
+export const parseProcStatStart = (stat: string): string | null => {
+  const close = stat.lastIndexOf(")");
+  if (close < 0) return null;
+  // After ")": field 3 (state) is index 0, so field 22 is index 19.
+  return (
+    stat
+      .slice(close + 1)
+      .trim()
+      .split(/\s+/)[19] ?? null
+  );
+};
+
+/** What processStartOf reads; tests inject a platform and readers. */
+export type ProcessStartDeps = {
+  platform?: NodeJS.Platform;
+  /** The text of /proc/<pid>/stat, or null. */
+  readStat?: (pid: number) => string | null;
+  /** `ps -o lstart= -p <pid>` output, or null. */
+  psStart?: (pid: number) => string | null;
+};
+
+const readProcStat = (pid: number): string | null => {
+  try {
+    return fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+const psStart = (pid: number): string | null => {
+  try {
+    // C locale: lstart is compared as a string across processes, and a holder
+    // and a waiter in different locales would otherwise disagree on a live pid.
+    const run = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 1_000,
+      env: { ...process.env, LC_ALL: "C" },
+    });
+    return run.status === 0 ? run.stdout.trim() || null : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Start time of `pid`, so a recycled pid is told apart: /proc on Linux, `ps -o lstart=` on macOS and FreeBSD. */
+export const processStartOf = (pid: number, deps: ProcessStartDeps = {}): string | null => {
+  const platform = deps.platform ?? process.platform;
+  if (platform === "linux") {
+    const stat = (deps.readStat ?? readProcStat)(pid);
+    return stat ? parseProcStatStart(stat) : null;
+  }
+  if (platform === "darwin" || platform === "freebsd") return (deps.psStart ?? psStart)(pid);
+  return null;
+};
+
+const readTrimmed = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Identity of the pid space this process lives in: hostname plus, on Linux,
+ * the pid-namespace inode and boot id. Containers that share the hostname
+ * (`--network host`) but not the pid namespace get a different identity, so
+ * their pids are never checked against this process table. Folded into the
+ * existing `host` string so older Workit versions still parse the lock.
+ */
+let cachedLockHost: string | null = null;
+export const localLockHost = (): string => {
+  if (cachedLockHost !== null) return cachedLockHost;
+  let pidns: string | null = null;
+  try {
+    pidns = /\[(\d+)\]/.exec(fs.readlinkSync("/proc/self/ns/pid"))?.[1] ?? null;
+  } catch {}
+  const boot = readTrimmed("/proc/sys/kernel/random/boot_id");
+  cachedLockHost = pidns || boot ? `${hostname()}#${pidns ?? "?"}:${boot ?? "?"}` : hostname();
+  return cachedLockHost;
+};
+
+const pidAlive = (pid: number): boolean => {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user.
+    return (error as { code?: unknown }).code === "EPERM";
+  }
+};
+
+export type LockOwnerState = {
+  /** live: wait. stale: reclaim. unknown: wait (cannot prove the owner is gone). */
+  state: "live" | "stale" | "unknown";
+  reason: string;
+};
+
+export type ClassifyOptions = {
+  /**
+   * Task-store locks only: a holder keeps one for a single mutation, so a
+   * same-host lock past FOREIGN_LOCK_TTL_MS whose start time cannot be
+   * compared is taken as a reused pid (Windows has no start time). Never for
+   * the stack lock, which a long synchronous rebase holds without heartbeat.
+   */
+  reclaimUnverifiedAfterTtl?: boolean;
+};
+
+/** How task-store locks (and doctor, which inspects them) classify an owner. */
+export const TASK_STORE_LOCK: ClassifyOptions = { reclaimUnverifiedAfterTtl: true };
+
+export const classifyLockOwner = (
+  payload: unknown,
+  ageMs: number | null,
+  localHost: string = localLockHost(),
+  options: ClassifyOptions = {},
+): LockOwnerState => {
+  const lock = metadataLockSchema.safeParse(payload);
+  if (!lock.success)
+    return ageMs !== null && ageMs > UNREADABLE_LOCK_TTL_MS
+      ? { state: "stale", reason: "unreadable lock left behind" }
+      : { state: "unknown", reason: "lock is being written" };
+  const { pid, processStart, host } = lock.data;
+  // Same host and pid namespace but another boot: the machine rebooted since
+  // the lock was taken, so its owner cannot still be running.
+  const [lockName, lockSpace] = host.split("#");
+  const [localName, localSpace] = localHost.split("#");
+  if (lockSpace && localSpace && lockName === localName) {
+    const [lockNs, lockBoot] = lockSpace.split(":");
+    const [localNs, localBoot] = localSpace.split(":");
+    if (lockNs === localNs && lockNs !== "?" && lockBoot !== "?" && lockBoot !== localBoot)
+      return { state: "stale", reason: "lock was taken before this machine rebooted" };
+  }
+  // Another host, another pid namespace, or a lock written by an older Workit
+  // without namespace identity: its pid cannot be checked here.
+  if (host !== localHost)
+    return ageMs !== null && ageMs > FOREIGN_LOCK_TTL_MS
+      ? { state: "stale", reason: `lock from ${host} is older than its TTL` }
+      : { state: "unknown", reason: `lock is held from ${host}; its pid cannot be checked here` };
+  if (!pidAlive(pid)) return { state: "stale", reason: `pid ${pid} is not running` };
+  const currentStart = processStartOf(pid);
+  if (processStart !== null && currentStart !== null && processStart !== currentStart)
+    return { state: "stale", reason: `pid ${pid} now belongs to a different process` };
+  // Without both start times (Windows has none) a reused pid looks alive. A
+  // task-store holder keeps the lock for one mutation, never minutes, so past
+  // the TTL the pid is taken to be reused and the crashed writer's lock is
+  // reclaimed (opt-in: see ClassifyOptions).
+  if (
+    options.reclaimUnverifiedAfterTtl === true &&
+    (processStart === null || currentStart === null) &&
+    ageMs !== null &&
+    ageMs > FOREIGN_LOCK_TTL_MS
+  )
+    return {
+      state: "stale",
+      reason: `pid ${pid} is running but the lock is older than its TTL and the pid's start time cannot be checked (reused pid)`,
+    };
+  return { state: "live", reason: `held by running pid ${pid}` };
+};
+
+const ageOf = (file: string, nowMs: number): number | null => {
+  try {
+    return nowMs - fs.lstatSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+/** A checkout's lock in the task store (see core/task-store.ts). */
+export const lockPathFor = (root: string): string => {
+  let real = path.resolve(root);
+  try {
+    real = fs.realpathSync(real);
+  } catch {}
+  const location = resolveStore(real);
+  const dir = location instanceof Error ? path.join(real, ".workit") : location.dir;
+  return path.join(dir, "checkouts", checkoutSlug(real), "metadata.lock");
+};
+
+/** Remove a reclaim guard abandoned by a crashed reclaimer. Returns true when removed. */
+export const clearAbandonedReclaimGuard = (lockPath: string, nowMs = Date.now()): boolean => {
+  const guard = `${lockPath}.reclaim`;
+  const age = ageOf(guard, nowMs);
+  if (age === null || age <= RECLAIM_GUARD_TTL_MS) return false;
+  try {
+    fs.rmdirSync(guard);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export type MetadataLockStatus = {
+  path: string;
+  present: boolean;
+  owner: MetadataLock | null;
+  state: LockOwnerState["state"] | "absent";
+  reason: string;
+  guard: "absent" | "fresh" | "abandoned";
+  /** Exact lock bytes that were classified (for compare-before-remove). */
+  raw?: string;
+  /** Age of the lock file in milliseconds, when present. */
+  ageMs?: number | null;
+};
+
+/** Read-only inspection of a checkout's metadata lock (doctor surface). */
+export const inspectMetadataLock = (root: string, nowMs = Date.now()): MetadataLockStatus => {
+  const lockPath = lockPathFor(root);
+  const guardAge = ageOf(`${lockPath}.reclaim`, nowMs);
+  const guard =
+    guardAge === null ? "absent" : guardAge > RECLAIM_GUARD_TTL_MS ? "abandoned" : "fresh";
+  let raw: string;
+  try {
+    raw = fs.readFileSync(lockPath, "utf8");
+  } catch {
+    return {
+      path: lockPath,
+      present: false,
+      owner: null,
+      state: "absent",
+      reason: "no lock",
+      guard,
+    };
+  }
+  const owner = parseMetadataLockOrNull(raw);
+  const ageMs = ageOf(lockPath, nowMs);
+  // The task store's own reclaim rule, so doctor reports what a write will do.
+  const verdict = classifyLockOwner(owner, ageMs, localLockHost(), TASK_STORE_LOCK);
+  return { path: lockPath, present: true, owner, ...verdict, guard, raw, ageMs };
+};
+
+export type ClearLockOutcome = MetadataLockStatus & {
+  cleared: boolean;
+  guardCleared: boolean;
+  /** Why the lock was kept, when it was present and not cleared. */
+  skipped?: string;
+};
+
+/**
+ * Clear a stale metadata lock (or, with `force`, any lock) and an abandoned
+ * reclaim guard. Removal holds the same `.reclaim` guard that writers take
+ * before reclaiming, so no writer can replace the lock between the final
+ * byte check and the unlink; a fresh guard means a reclaim is already in
+ * progress and the lock is left alone.
+ */
+export const clearStaleMetadataLock = (
+  root: string,
+  options: { force?: boolean; nowMs?: number } = {},
+): ClearLockOutcome => {
+  const nowMs = options.nowMs ?? Date.now();
+  const status = inspectMetadataLock(root, nowMs);
+  const guardCleared = status.guard === "abandoned" && clearAbandonedReclaimGuard(status.path);
+  const outcome = { ...status, cleared: false, guardCleared };
+  if (!status.present) return outcome;
+  if (status.state !== "stale" && !options.force) return { ...outcome, skipped: status.reason };
+  const guard = `${status.path}.reclaim`;
+  try {
+    fs.mkdirSync(guard);
+  } catch {
+    return { ...outcome, skipped: "a reclaim is in progress" };
+  }
+  try {
+    const before = fs.readFileSync(status.path, "utf8");
+    if (before !== status.raw) return { ...outcome, skipped: "the lock changed" };
+    if (!options.force) {
+      const verdict = classifyLockOwner(
+        parseMetadataLockOrNull(before),
+        ageOf(status.path, nowMs),
+        localLockHost(),
+        TASK_STORE_LOCK,
+      );
+      if (verdict.state !== "stale") return { ...outcome, skipped: verdict.reason };
+    }
+    if (fs.readFileSync(status.path, "utf8") !== before)
+      return { ...outcome, skipped: "the lock changed" };
+    fs.rmSync(status.path);
+    return { ...outcome, cleared: true };
+  } catch (error) {
+    return { ...outcome, skipped: `could not clear: ${String(error)}` };
+  } finally {
+    try {
+      fs.rmdirSync(guard);
+    } catch {}
+  }
+};

package/src/core/support-matrix.ts

@@ -0,0 +1,24 @@
+// Declared support matrix for published Workit artifacts (RR-10/PT-11/PT-12).
+// Single source of truth for the pinned toolchain and host versions; the CI
+// workflow, package engines, and lockfiles must stay in sync (enforced by
+// test/artifacts/manifests.test.ts and test/artifacts/packed-runtime.test.ts).
+// Deno is intentionally not part of the matrix (PT-12): nothing advertises a
+// host that has no executable artifact/test evidence.
+export const SUPPORT_MATRIX = {
+  bun: "1.4.4",
+  node: { minimum: "24", current: "24.20.0" },
+  // OpenCode V2 plugin API only: the entry exports `setup()` (Workit 3.0
+  // retired the V1 `server()` adapter), so 1.x hosts cannot load it. 2.0.18 is
+  // the `@opencode/plugin` contract the adapter is built and tested against.
+  opencode: { minimum: "2.0.18", current: "2.0.18" },
+  // Codex is a qualification host, not a runtime dependency: the CLI version
+  // below is the one live qualification evidence covers. The doctor warns when
+  // an installed CLI drifts ahead so a fresh install never silently outruns
+  // the qualification pin.
+  codex: { cli: "0.153.4", desktopPackage: "26.901.20858", bundledCodexCli: "0.153.0-alpha.5" },
+  // Claude Code is a qualification host too: CI runs `claude plugin validate
+  // --strict` with exactly this CLI, and the hook output schema fixture
+  // (test/fixtures/claude-code-schemas) was transcribed from this binary.
+  claudeCode: { cli: "2.1.288" },
+  os: ["ubuntu-latest", "macos-latest", "windows-latest"],
+} as const;