@hegemonart/get-design-done 1.19.6 → 1.20.0

package/scripts/lib/iteration-budget.cjs

@@ -0,0 +1,205 @@
+// scripts/lib/iteration-budget.cjs
+//
+// Plan 20-14 — bounded fix-loop iteration budget.
+//
+// Stops infinite fix cycles from burning unbounded context. Every fix-
+// iteration consumes 1 unit; Layer-B cache hits refund 1 unit so
+// cached answers don't count against the ceiling. When the budget
+// reaches 0, consume() throws and the caller must surface to user.
+//
+// State file: `.design/iteration-budget.json`. All mutations go through
+// `scripts/lib/lockfile.cjs` with atomic temp+rename writes so
+// concurrent callers (hook + fix-loop + verify) don't clobber each
+// other. The lock scope is the state file itself, so refund + consume
+// from different children serialize correctly.
+//
+// Shape on disk matches reference/schemas/iteration-budget.schema.json:
+//   { budget, remaining, consumed, refunded, updatedAt }
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { acquire } = require('./lockfile.cjs');
+
+const STATE_PATH_REL = path.join('.design', 'iteration-budget.json');
+const DEFAULT_BUDGET = 50;
+const LOCK_MAX_WAIT_MS = 5_000;
+
+/** Error thrown by `consume()` when the remaining budget would go below 0. */
+class IterationBudgetExhaustedError extends Error {
+  constructor(amount, state) {
+    super(
+      `IterationBudgetExhausted: cannot consume ${amount} — remaining=${state.remaining}, budget=${state.budget}, consumed=${state.consumed}. Caller must surface to user (fix-loop has stopped converging).`,
+    );
+    this.name = 'IterationBudgetExhaustedError';
+    this.amount = amount;
+    this.state = state;
+  }
+}
+
+function stateAbsPath() {
+  return path.join(process.cwd(), STATE_PATH_REL);
+}
+
+/** Read and validate the state file. Returns null on missing/corrupt. */
+function readStateSync() {
+  const p = stateAbsPath();
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      Number.isInteger(parsed.budget) && parsed.budget >= 0 &&
+      Number.isInteger(parsed.remaining) && parsed.remaining >= 0 &&
+      Number.isInteger(parsed.consumed) && parsed.consumed >= 0 &&
+      Number.isInteger(parsed.refunded) && parsed.refunded >= 0 &&
+      typeof parsed.updatedAt === 'string'
+    ) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomically write state under a file-lock. */
+async function writeStateAtomic(state) {
+  const p = stateAbsPath();
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const release = await acquire(p, { maxWaitMs: LOCK_MAX_WAIT_MS });
+  try {
+    // Re-read inside the lock so we merge against the very latest
+    // on-disk state, not the value the caller observed pre-lock. This
+    // is what makes concurrent consume() from 10 children add up to
+    // consumed=10 rather than racing each other.
+    const latest = readStateSync();
+    const merged = state.mergeFn ? state.mergeFn(latest || state.seed) : state.seed;
+    const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, p);
+    return merged;
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Initialize or restart the iteration budget.
+ *
+ * @param {number} [budget] default 50
+ * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
+ */
+async function reset(budget = DEFAULT_BUDGET) {
+  if (!Number.isFinite(budget) || budget < 0) {
+    throw new Error(`iteration-budget.reset: budget must be a non-negative finite number, got ${budget}`);
+  }
+  const b = Math.floor(budget);
+  const state = {
+    budget: b,
+    remaining: b,
+    consumed: 0,
+    refunded: 0,
+    updatedAt: new Date().toISOString(),
+  };
+  return writeStateAtomic({ seed: state, mergeFn: () => state });
+}
+
+/**
+ * Consume N units from the remaining budget. Throws
+ * IterationBudgetExhaustedError when N would send remaining below zero.
+ *
+ * @param {number} [amount] default 1
+ * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
+ *   the new on-disk state after consumption.
+ */
+async function consume(amount = 1) {
+  const n = normalizeAmount(amount);
+  // Seed for the case when no state exists yet: auto-init to default budget.
+  const seed = defaultState();
+  return writeStateAtomic({
+    seed,
+    mergeFn: (current) => {
+      const base = current || seed;
+      const nextRemaining = base.remaining - n;
+      if (nextRemaining < 0) {
+        // Throw without writing — atomic: either consume fully or not at all.
+        throw new IterationBudgetExhaustedError(n, base);
+      }
+      return {
+        budget: base.budget,
+        remaining: nextRemaining,
+        consumed: base.consumed + n,
+        refunded: base.refunded,
+        updatedAt: new Date().toISOString(),
+      };
+    },
+  });
+}
+
+/**
+ * Refund N units to the remaining budget, capped at `budget`.
+ *
+ * @param {number} [amount] default 1
+ * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
+ */
+async function refund(amount = 1) {
+  const n = normalizeAmount(amount);
+  const seed = defaultState();
+  return writeStateAtomic({
+    seed,
+    mergeFn: (current) => {
+      const base = current || seed;
+      const nextRemaining = Math.min(base.budget, base.remaining + n);
+      // Only count the portion that actually landed — if we were already
+      // at budget, the refund is a no-op.
+      const actuallyRefunded = nextRemaining - base.remaining;
+      return {
+        budget: base.budget,
+        remaining: nextRemaining,
+        consumed: base.consumed,
+        refunded: base.refunded + actuallyRefunded,
+        updatedAt: new Date().toISOString(),
+      };
+    },
+  });
+}
+
+/**
+ * Return the current on-disk state. Reads without the lock — callers
+ * using this for UI display only see a best-effort snapshot; mutating
+ * paths (consume/refund) always re-read inside the lock.
+ */
+function remaining() {
+  return readStateSync() || defaultState();
+}
+
+function normalizeAmount(amount) {
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new Error(`iteration-budget: amount must be a positive finite number, got ${amount}`);
+  }
+  return Math.floor(amount);
+}
+
+function defaultState() {
+  return {
+    budget: DEFAULT_BUDGET,
+    remaining: DEFAULT_BUDGET,
+    consumed: 0,
+    refunded: 0,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  consume,
+  refund,
+  remaining,
+  reset,
+  IterationBudgetExhaustedError,
+};

package/scripts/lib/iteration-budget.d.cts

@@ -0,0 +1,32 @@
+// scripts/lib/iteration-budget.d.cts — types for iteration-budget.cjs.
+
+export interface BudgetState {
+  budget: number;
+  remaining: number;
+  consumed: number;
+  refunded: number;
+  updatedAt: string; // ISO-8601
+}
+
+/** Error thrown by {@link consume} when remaining would drop below 0. */
+export class IterationBudgetExhaustedError extends Error {
+  readonly name: 'IterationBudgetExhaustedError';
+  readonly amount: number;
+  readonly state: BudgetState;
+  constructor(amount: number, state: BudgetState);
+}
+
+/**
+ * Consume N units from the remaining budget. Throws
+ * {@link IterationBudgetExhaustedError} when N would send remaining below zero.
+ */
+export function consume(amount?: number): Promise<BudgetState>;
+
+/** Refund N units, capped at `budget`. */
+export function refund(amount?: number): Promise<BudgetState>;
+
+/** Current snapshot; non-locking read. */
+export function remaining(): BudgetState;
+
+/** Initialize or restart the budget. Default 50. */
+export function reset(budget?: number): Promise<BudgetState>;

package/scripts/lib/jittered-backoff.cjs

@@ -0,0 +1,112 @@
+// scripts/lib/jittered-backoff.cjs
+//
+// Plan 20-14 — jittered exponential backoff primitive.
+//
+// Replaces fixed-interval retry sleeps across the codebase (update-check,
+// watch-authorities, figma probes, connection probes, hook retry loops) with
+// a deterministic, capped, jittered backoff curve.
+//
+// Formula:
+//   base = min(maxMs, baseMs * factor^attempt)
+//   delay = base * (1 + rand(-jitter, +jitter))
+//   clamp to [0, maxMs * (1 + jitter)]
+//
+// The zero-based `attempt` counter gives `baseMs` on the first call, then
+// multiplies by `factor` per attempt up to the cap. Jitter is full-width
+// symmetric (not AWS-style equal/decorrelated) because our consumers are
+// single-threaded retry loops — there's no thundering-herd problem to
+// smooth; the jitter is cosmetic protection against synchronized retries
+// between siblings like the watcher + update-check running at the same
+// session boundary.
+//
+// Defaults (baseMs=100, maxMs=30_000, factor=2, jitter=0.2) yield:
+//   attempt 0 → 80-120ms
+//   attempt 1 → 160-240ms
+//   attempt 2 → 320-480ms
+//   ...
+//   attempt 9 → ~24s-30s (capped)
+//
+// This module is `.cjs` (not `.ts`) per Plan 20-14 D-01 so it can be
+// `require()`d from both the `.ts` runtime (hooks, MCP server) and future
+// `.cjs` CLI invocations without needing `--experimental-strip-types` at
+// every consumer site. Types live in the paired `jittered-backoff.d.cts`.
+//
+// No external dependencies; pure Math.random + setTimeout.
+
+'use strict';
+
+/**
+ * Default backoff parameters — chosen to cover retry-after-Xms through
+ * retry-after-30s with reasonable mid-range distribution.
+ */
+const DEFAULTS = Object.freeze({
+  baseMs: 100,
+  maxMs: 30_000,
+  factor: 2,
+  jitter: 0.2,
+});
+
+/**
+ * Compute the jittered delay in milliseconds for a given attempt number.
+ *
+ * @param {number} attempt zero-based attempt counter (0 = first retry)
+ * @param {object} [opts]
+ * @param {number} [opts.baseMs]  initial delay before any jitter. Default 100.
+ * @param {number} [opts.maxMs]   maximum un-jittered base. Default 30_000.
+ * @param {number} [opts.factor]  per-attempt multiplier. Default 2.
+ * @param {number} [opts.jitter]  symmetric jitter fraction in [0, 1). Default 0.2.
+ * @returns {number} delay in ms. Never negative. May exceed `maxMs` by up
+ *   to `jitter * maxMs` on the high side.
+ *
+ * Invariants:
+ *  - `delayMs(n, opts) >= 0` for every non-negative `n`.
+ *  - `delayMs(n, opts) <= maxMs * (1 + jitter)` for every non-negative `n`.
+ *  - The distribution has nonzero stddev whenever `jitter > 0`.
+ */
+function delayMs(attempt, opts) {
+  const baseMs = (opts && Number.isFinite(opts.baseMs)) ? opts.baseMs : DEFAULTS.baseMs;
+  const maxMs = (opts && Number.isFinite(opts.maxMs)) ? opts.maxMs : DEFAULTS.maxMs;
+  const factor = (opts && Number.isFinite(opts.factor)) ? opts.factor : DEFAULTS.factor;
+  const jitter = (opts && Number.isFinite(opts.jitter)) ? opts.jitter : DEFAULTS.jitter;
+
+  // Guard against nonsense inputs — callers that pass garbage shouldn't
+  // cause NaN or Infinity to propagate into setTimeout.
+  const a = Math.max(0, Number.isFinite(attempt) ? Math.floor(attempt) : 0);
+  const safeBase = Math.max(0, baseMs);
+  const safeMax = Math.max(safeBase, maxMs);
+  const safeFactor = factor > 0 ? factor : DEFAULTS.factor;
+  // Clamp jitter to [0, 1) — full-range (>=1) would allow negative values
+  // after subtraction, which we want to forbid by invariant.
+  const safeJitter = Math.min(0.999, Math.max(0, jitter));
+
+  // Exponential growth capped at safeMax.
+  // Math.pow with a huge attempt count can overflow to Infinity; the
+  // Math.min picks up safeMax before Infinity escapes.
+  const unjittered = Math.min(safeMax, safeBase * Math.pow(safeFactor, a));
+
+  // Symmetric jitter in [-jitter, +jitter).
+  // Math.random() returns [0, 1); 2r - 1 maps to [-1, 1); scale by jitter.
+  const noise = (Math.random() * 2 - 1) * safeJitter;
+  const delay = unjittered * (1 + noise);
+
+  // Floor at zero (noise could in theory go slightly negative due to FP
+  // precision even with safeJitter < 1, for very small unjittered values).
+  return Math.max(0, delay);
+}
+
+/**
+ * Sleep for a jittered backoff interval. Convenience wrapper around
+ * `delayMs` + `setTimeout`.
+ *
+ * @param {number} attempt zero-based attempt counter
+ * @param {object} [opts] see {@link delayMs}
+ * @returns {Promise<number>} resolves to the actual delay that was applied
+ */
+function sleep(attempt, opts) {
+  const ms = delayMs(attempt, opts);
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(ms), ms);
+  });
+}
+
+module.exports = { delayMs, sleep, DEFAULTS };

package/scripts/lib/jittered-backoff.d.cts

@@ -0,0 +1,38 @@
+// scripts/lib/jittered-backoff.d.cts — types for jittered-backoff.cjs.
+//
+// Paired ambient declaration for TS consumers that `require()` the .cjs
+// module. `.d.cts` suffix matches the `.cjs` runtime file so TS's Node16
+// resolver picks it up for CommonJS require calls from .ts files.
+
+export interface BackoffOptions {
+  /** Initial delay before any jitter. Default 100ms. */
+  baseMs?: number;
+  /** Maximum un-jittered base. Default 30_000ms. */
+  maxMs?: number;
+  /** Per-attempt multiplier. Default 2. */
+  factor?: number;
+  /** Symmetric jitter fraction in [0, 1). Default 0.2. */
+  jitter?: number;
+}
+
+/** Default backoff parameters (frozen). */
+export const DEFAULTS: Readonly<Required<BackoffOptions>>;
+
+/**
+ * Compute the jittered delay in milliseconds for a given attempt number.
+ *
+ * @param attempt zero-based attempt counter (0 = first retry)
+ * @param opts optional overrides for the four backoff parameters
+ * @returns delay in ms. Never negative. May exceed `maxMs` by up to
+ *   `jitter * maxMs` on the high side.
+ */
+export function delayMs(attempt: number, opts?: BackoffOptions): number;
+
+/**
+ * Sleep for a jittered backoff interval.
+ *
+ * @param attempt zero-based attempt counter
+ * @param opts see {@link BackoffOptions}
+ * @returns the actual delay that was applied
+ */
+export function sleep(attempt: number, opts?: BackoffOptions): Promise<number>;

package/scripts/lib/lockfile.cjs

@@ -0,0 +1,177 @@
+// scripts/lib/lockfile.cjs
+//
+// Plan 20-14 — PID+timestamp sibling lockfile for `.cjs` consumers.
+//
+// Algorithm mirrors scripts/lib/gdd-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);
+      if (parsed === null || isStale(parsed, staleMs)) {
+        // Clear stale/garbage lock; race-tolerant — if it's already gone
+        // we'll just 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));
+}
+
+module.exports = { acquire };

package/scripts/lib/lockfile.d.cts

@@ -0,0 +1,21 @@
+// scripts/lib/lockfile.d.cts — types for lockfile.cjs.
+
+export interface AcquireOptions {
+  /** ms after which an existing lock is considered stale. Default 60_000. */
+  staleMs?: number;
+  /** total ms to wait before throwing LockAcquisitionError. Default 5_000. */
+  maxWaitMs?: number;
+  /** ms between retry attempts. Default 50. */
+  pollMs?: number;
+}
+
+/** Release function returned by `acquire()`. Idempotent. */
+export type LockRelease = () => Promise<void>;
+
+/**
+ * Acquire an advisory lock at `${path}.lock`. Returns a release function.
+ *
+ * @throws Error with `name === 'LockAcquisitionError'` when `maxWaitMs`
+ *   elapses without acquiring.
+ */
+export function acquire(path: string, opts?: AcquireOptions): Promise<LockRelease>;