@hegemonart/get-design-done 1.31.0 → 1.31.5

package/sdk/primitives/lockfile.cjs

@@ -0,0 +1,201 @@
+// scripts/lib/lockfile.cjs
+//
+// Plan 20-14 — PID+timestamp sibling lockfile for `.cjs` consumers.
+//
+// Algorithm mirrors sdk/state/lockfile.ts (Plan 20-01):
+//   Lock path:     `${target}.lock`
+//   Payload:       { pid: number, host: string, acquired_at: ISO8601 }
+//   Acquire:       atomic `writeFileSync(..., { flag: 'wx' })`
+//   Stale rule:    pid dead (ESRCH via `kill(pid, 0)`) OR `acquired_at` older
+//                  than `staleMs` OR unparseable payload
+//   Release:       unlink; ENOENT is not an error; idempotent
+//
+// Windows: AV scanners and file-indexers can hold a file briefly after
+// close. `wx` create may fail with EPERM/EBUSY even when the target is
+// free; we treat these as transient and loop (same code path as EEXIST).
+//
+// Dependency-cycle note: Plan 20-14's rate-guard + iteration-budget
+// consume this module, and both are required to stay dependency-light so
+// that hooks/budget-enforcer.ts can import them without dragging the
+// gdd-state MCP graph along. Hence this standalone .cjs port instead of
+// calling the .ts version.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_MAX_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 50;
+
+/**
+ * Acquire an advisory lock at `${path}.lock`. Returns an idempotent
+ * async release function.
+ *
+ * @param {string} path path being locked (we append `.lock`)
+ * @param {object} [opts]
+ * @param {number} [opts.staleMs]   ms after which an existing lock is stale. Default 60_000.
+ * @param {number} [opts.maxWaitMs] total ms to wait before throwing. Default 5_000.
+ * @param {number} [opts.pollMs]    ms between retry attempts. Default 50.
+ * @returns {Promise<() => Promise<void>>} release function
+ * @throws {Error} with name === 'LockAcquisitionError' when maxWaitMs elapses
+ */
+async function acquire(path, opts) {
+  const o = opts || {};
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_STALE_MS;
+  const maxWaitMs = Number.isFinite(o.maxWaitMs) ? o.maxWaitMs : DEFAULT_MAX_WAIT_MS;
+  const pollMs = Number.isFinite(o.pollMs) ? o.pollMs : DEFAULT_POLL_MS;
+
+  if (staleMs < 0 || maxWaitMs < 0 || pollMs < 0) {
+    throw new Error(
+      `lockfile.acquire: invalid options (staleMs=${staleMs}, maxWaitMs=${maxWaitMs}, pollMs=${pollMs})`,
+    );
+  }
+
+  const lockPath = `${path}.lock`;
+  const payload = JSON.stringify({
+    pid: process.pid,
+    host: os.hostname(),
+    acquired_at: new Date().toISOString(),
+  });
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      fs.writeFileSync(lockPath, payload, { flag: 'wx', encoding: 'utf8' });
+      return makeRelease(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EBUSY') {
+        throw err;
+      }
+      // Try to read the current holder; if it vanished between EEXIST and
+      // read, loop immediately.
+      const existing = readLockSafe(lockPath);
+      if (existing === null) continue;
+
+      const parsed = parseLock(existing);
+      // Only clear when we're confident the lock is stale: the payload
+      // parses AND the PID/age check says so. An unparseable payload is
+      // treated as fresh — on Windows, AV/indexer can transiently deny
+      // reads (EACCES/EPERM/EBUSY), and clearing under that condition
+      // would let two writers race and lose increments.
+      if (parsed !== null && isStale(parsed, staleMs)) {
+        // Clear stale lock; race-tolerant — if it's already gone we get
+        // ENOENT, no-op.
+        try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
+        continue;
+      }
+
+      if (Date.now() - startedAt >= maxWaitMs) {
+        const e = new Error(
+          `lockfile: failed to acquire ${lockPath} within ${maxWaitMs}ms (held by ${existing})`,
+        );
+        e.name = 'LockAcquisitionError';
+        e.lockPath = lockPath;
+        e.holder = existing;
+        e.waitedMs = Date.now() - startedAt;
+        throw e;
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+function makeRelease(lockPath) {
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code === 'ENOENT') return; // idempotent — already gone
+      if (code === 'EPERM' || code === 'EBUSY') {
+        // Windows AV/indexer: retry once.
+        await sleep(50);
+        try {
+          if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+        } catch { /* give up; stale-detection will reclaim */ }
+        return;
+      }
+      // Any other errno: swallow. Best-effort cleanup; stale-age check
+      // will eventually reclaim the lock.
+    }
+  };
+}
+
+function readLockSafe(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ENOENT') return null;
+    return '<unreadable>';
+  }
+}
+
+function parseLock(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (
+      obj && typeof obj === 'object' &&
+      typeof obj.pid === 'number' &&
+      typeof obj.host === 'string' &&
+      typeof obj.acquired_at === 'string'
+    ) {
+      return obj;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function isStale(payload, staleMs) {
+  if (!isPidAlive(payload.pid, payload.host)) return true;
+  const t = Date.parse(payload.acquired_at);
+  if (!Number.isFinite(t)) return true;
+  return Date.now() - t > staleMs;
+}
+
+function isPidAlive(pid, host) {
+  if (host !== os.hostname()) return true; // can't introspect other hosts
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0); // signal 0 = validate, don't deliver
+    return true;
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ESRCH') return false;
+    // EPERM / EACCES: process exists but is unsignalable; treat as alive.
+    return true;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * `fs.renameSync` wrapper that retries once on Windows EPERM/EBUSY/EACCES.
+ * AV scanners and the file-indexer can briefly hold a destination open
+ * after another process closed it, causing rename to fail even when the
+ * advisory lock is correctly held.
+ *
+ * Mirrors the inline retry in sdk/state/index.ts mutate().
+ */
+async function renameWithRetry(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') throw err;
+    await sleep(50);
+    fs.renameSync(from, to);
+  }
+}
+
+module.exports = { acquire, renameWithRetry };

package/{scripts/lib/gdd-state → sdk/state}/gates.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/gates.ts — pure transition-gate functions.
+// sdk/state/gates.ts — pure transition-gate functions.
 //
 // Plan 20-02 (SDK-03): the typed, single-source-of-truth implementation
 // of "can this pipeline advance?" that replaces prose-encoded guards in

package/sdk/state/index.ts

@@ -0,0 +1,167 @@
+// sdk/state/index.ts — public API for the gdd-state module.
+//
+// This is the ONLY file consumers should import from. The module exposes
+// exactly five surface-level names:
+//   * read(path)                    — parse STATE.md from disk
+//   * mutate(path, fn)              — atomic read-modify-write under a lock
+//   * transition(path, toStage)     — gate + stage-advance helper
+//   * ParsedState (type)            — consumer-visible shape
+//   * Stage (type)                  — stage enum
+//
+// Plan 20-02 wired the real transition gates in via `gateFor(from, to)`
+// imported from `./gates.ts`. Plan 20-04 migrated the error classes
+// (TransitionGateFailed, LockAcquisitionError, ParseError) to the
+// unified `gdd-errors` taxonomy — `types.ts` re-exports them verbatim
+// so consumers of `gdd-state` need no changes.
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+
+import { acquire } from './lockfile.ts';
+import { parse } from './parser.ts';
+import { serialize } from './mutator.ts';
+import { gateFor } from './gates.ts';
+import {
+  TransitionGateFailed,
+  isStage,
+  type ParsedState,
+  type Stage,
+  type TransitionResult,
+} from './types.ts';
+
+export type { ParsedState, Stage } from './types.ts';
+export { TransitionGateFailed, LockAcquisitionError, ParseError } from './types.ts';
+
+/**
+ * Read STATE.md from disk and return the parsed state.
+ *
+ * Shared-read: no lock is taken. Reads are snapshot-safe for markdown
+ * (the OS guarantees a coherent view even if a writer is mid-rename —
+ * we either see the old file or the new file, never a torn write,
+ * because `mutate()` uses atomic rename).
+ */
+export async function read(path: string): Promise<ParsedState> {
+  const raw: string = readFileSync(path, 'utf8');
+  return parse(raw).state;
+}
+
+/**
+ * Atomic read-modify-write on STATE.md.
+ *
+ * Flow:
+ *   1. Acquire sibling `.lock` file (PID+timestamp advisory lock).
+ *   2. Read current contents.
+ *   3. Apply `fn`.
+ *   4. Serialize to a `.tmp` file next to `path`.
+ *   5. `renameSync(.tmp, path)` — POSIX-atomic; on Windows EPERM means
+ *      a scanner held it briefly, retry once.
+ *   6. Release the lock (in `finally` — released even on mid-fn throw).
+ *
+ * Crash between write and rename is benign: STATE.md is untouched; the
+ * `.tmp` file is orphaned (cleaned up on the next acquire by the caller).
+ */
+export async function mutate(
+  path: string,
+  fn: (s: ParsedState) => ParsedState,
+): Promise<ParsedState> {
+  const release = await acquire(path);
+  const tmpPath: string = `${path}.tmp`;
+  try {
+    const raw: string = readFileSync(path, 'utf8');
+    const { state, raw_bodies, raw_frontmatter, block_gaps, line_ending } =
+      parse(raw);
+    // Deep-clone so the consumer's fn cannot mutate the state we just
+    // parsed (defensive — apply() does this too for pure callers).
+    const clone = structuredClone(state);
+    const next = fn(clone);
+    const out = serialize(next, {
+      raw_frontmatter,
+      raw_bodies,
+      block_gaps,
+      line_ending,
+    });
+    writeFileSync(tmpPath, out, 'utf8');
+    try {
+      renameSync(tmpPath, path);
+    } catch (err) {
+      // Windows EPERM retry — AV / indexer holding STATE.md briefly.
+      const code =
+        typeof err === 'object' && err !== null && 'code' in err
+          ? (err as { code?: unknown }).code
+          : undefined;
+      if (code === 'EPERM' || code === 'EBUSY') {
+        await new Promise((r) => setTimeout(r, 50));
+        renameSync(tmpPath, path);
+      } else {
+        throw err;
+      }
+    }
+    return next;
+  } catch (err) {
+    // Clean up the orphaned tmp file on failure so we don't pollute.
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best-effort; a leftover tmp file does not corrupt STATE.md.
+    }
+    throw err;
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Advance to `toStage` under the locked RMW protocol.
+ *
+ * Steps:
+ *   1. Read current state (outside the lock) to pass to the gate.
+ *   2. Resolve the gate via `gateFor(position.stage, toStage)`.
+ *        - `null` → TransitionGateFailed "Invalid transition" (skip-stage,
+ *          backward, same-stage, or from outside the Stage union).
+ *   3. Invoke the gate. If `pass: false`, throw TransitionGateFailed with
+ *      the gate's blockers verbatim.
+ *   4. If `pass: true`, mutate STATE.md under the lock:
+ *        - frontmatter.stage = toStage
+ *        - position.stage = toStage
+ *        - frontmatter.last_checkpoint = now (ISO)
+ *        - timestamps[`${toStage}_started_at`] = now (ISO)
+ *
+ * Returns the updated state plus the gate response (for callers that
+ * want to log blockers — on pass, `blockers` is always `[]`).
+ */
+export async function transition(
+  path: string,
+  toStage: Stage,
+): Promise<TransitionResult> {
+  // Read (outside the lock) to pass current state to the gate — the
+  // mutate() below will re-read under the lock before applying changes.
+  // This two-phase pattern matches the GSD reference implementation.
+  const beforeMutate = await read(path);
+  const from: string = beforeMutate.position.stage;
+  // `position.stage` is typed as `string` in ParsedState (parser tolerates
+  // `scan` and other pre-brief values). Narrow it to `Stage` before asking
+  // the gate registry — anything outside the union is an invalid FROM.
+  if (!isStage(from)) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: from="${from}" is not a recognized Stage`,
+    ]);
+  }
+  const gate = gateFor(from, toStage);
+  if (gate === null) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: ${from} → ${toStage}`,
+    ]);
+  }
+  const gateResult = gate(beforeMutate);
+  if (!gateResult.pass) {
+    throw new TransitionGateFailed(toStage, gateResult.blockers);
+  }
+  const nowIso: string = new Date().toISOString();
+  const nextState = await mutate(path, (s): ParsedState => {
+    s.frontmatter.stage = toStage;
+    s.frontmatter.last_checkpoint = nowIso;
+    s.position.stage = toStage;
+    s.timestamps[`${toStage}_started_at`] = nowIso;
+    return s;
+  });
+  return { pass: true, blockers: gateResult.blockers, state: nextState };
+}

package/{scripts/lib/gdd-state → sdk/state}/lockfile.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/lockfile.ts — PID+timestamp sibling lockfile.
+// sdk/state/lockfile.ts — PID+timestamp sibling lockfile.
 //
 // Pattern (from GSD state-mutation.ts D2):
 //   Lock file at `${target}.lock` holds JSON

package/{scripts/lib/gdd-state → sdk/state}/mutator.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/mutator.ts — serializer + `apply(raw, fn)` mutator.
+// sdk/state/mutator.ts — serializer + `apply(raw, fn)` mutator.
 //
 // Two guarantees:
 //   1. `serialize(parse(raw).state, parse(raw).raw_bodies)` === `raw`

package/{scripts/lib/gdd-state → sdk/state}/parser.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/parser.ts — turns STATE.md text into ParsedState.
+// sdk/state/parser.ts — turns STATE.md text into ParsedState.
 //
 // Design constraints:
 //   1. Pure function (no I/O). `read()` in index.ts supplies the file.

package/{scripts/lib/gdd-state → sdk/state}/types.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/types.ts — typed shape of a parsed STATE.md.
+// sdk/state/types.ts — typed shape of a parsed STATE.md.
 //
 // Plan 20-01 (SDK-01/02): canonical type surface consumed by the parser,
 // mutator, and public read/mutate/transition API. Everything here is
@@ -241,18 +241,18 @@ export interface TransitionResult extends GateResult {
 
 // Error classes migrated to the unified GDDError taxonomy in Plan 20-04.
 // Re-exported here so existing consumers (tests, downstream modules) keep
-// importing from `gdd-state/types.ts` unchanged.
+// importing from `sdk/state/types.ts` unchanged.
 //
 //   * TransitionGateFailed  — StateConflictError subclass; retryable
 //   * LockAcquisitionError  — StateConflictError subclass; retryable
 //   * ParseError            — ValidationError subclass; fix your STATE.md
 //
-// See `scripts/lib/gdd-errors/index.ts` for the taxonomy definition.
+// See `sdk/errors/index.ts` for the taxonomy definition.
 export {
   TransitionGateFailed,
   LockAcquisitionError,
   ParseError,
-} from '../gdd-errors/index.ts';
+} from '../errors/index.ts';
 
 /** Type-guard for `Stage`. */
 export function isStage(value: unknown): value is Stage {

package/skills/quality-gate/SKILL.md

@@ -58,11 +58,11 @@ Else: increment `iteration`, emit `quality_gate_iteration`, spawn `design-fixer`
 
 ## Step 5 — STATE write
 
-Mutate `state.quality_gate.run` to `{started_at, completed_at, status, iteration, commands_run, extra_attrs:{}}`. Persist via `mcp__gdd_state__set_quality_gate` or `apply()` mutator from `scripts/lib/gdd-state/mutator.ts` — identical on-disk shape.
+Mutate `state.quality_gate.run` to `{started_at, completed_at, status, iteration, commands_run, extra_attrs:{}}`. Persist via `mcp__gdd_state__set_quality_gate` or `apply()` mutator from `sdk/state/mutator.ts` — identical on-disk shape.
 
 ## Step 6 — Event emission (D-09)
 
-Use `appendEvent` from `scripts/lib/event-stream/index.ts` — persist-first / broadcast-second; never throws on persist path. `ts` / `cycle` / `stage` are stamped by the writer. Six event types (one per lifecycle position):
+Use `appendEvent` from `sdk/event-stream/index.ts` — persist-first / broadcast-second; never throws on persist path. `ts` / `cycle` / `stage` are stamped by the writer. Six event types (one per lifecycle position):
 
 | Event | When | Payload |
 |-------|------|---------|