@hegemonart/get-design-done 1.30.6 → 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/figma-extract/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gdd-figma-extract
+description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+---
+
+# gdd-figma-extract
+
+Pull a whole Figma design system into a compact, queryable local digest — **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
+
+## Usage
+
+```
+/gdd:figma-extract <file-key-or-url>                  # full design-system digest
+/gdd:figma-extract <file-key-or-url> --component Button  # ~500-token single-component slice
+```
+
+`<file-key-or-url>` is a Figma file URL (`https://www.figma.com/file/<key>/…` or `/design/<key>/…`) or a bare file key.
+
+## Behavior
+
+1. **Preflight (D-10).** Confirm `FIGMA_TOKEN` is set in the environment:
+   ```
+   node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
+   ```
+   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** — never ask the user to paste it into a file or the chat, and never echo it back.
+
+2. **Stage 1 — pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
+   ```
+   node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
+   ```
+   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout — the raw bodies stay on disk.
+
+3. **Stage 2 — plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
+   ```
+   node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
+   ```
+   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** — see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
+
+4. **Stage 3 — digest.** Transform the cache into the compact digest:
+   ```
+   node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
+   ```
+   This writes `DESIGN.md`, `tokens.json`, and `components.json`. Add `--prefer-styles` to invert the token priority to styles-first (D-04). Add `--component <name>` (D-08) to emit a single-component slice instead of the full digest.
+
+5. **Read the digest.** Open **only** `.figma-extract-cache/digest/DESIGN.md` (plus `tokens.json` / `components.json` when you need structured data). For a single component, pass `--component <name>` in Stage 3 and read the ~500-token slice instead of the full ~16K-token spec.
+
+## Required Reading
+
+- `.figma-extract-cache/digest/DESIGN.md` — the compact human/LLM-readable spec
+- `.figma-extract-cache/digest/tokens.json` — resolved design tokens (when structured token data is needed)
+- `.figma-extract-cache/digest/components.json` — components with variants/props/defaults (when structured component data is needed)
+
+## Notes
+
+- Two-stage pipeline (D-01): re-run Stage 3 against an existing cache without re-pulling. The digest does zero network calls.
+- The spike proved **0 Claude tokens** during extraction (898× compression, 223 MB → 254 KB). That property holds only because this skill never surfaces the raw cache.
+- Figma MCP remains the right tool for spot questions on a single live component; this skill is the cheaper path for whole-design-system workflows.
+
+## Do Not
+
+- **Do NOT read or `cat` the `raw/*.json` cache** (e.g. `.figma-extract-cache/raw/<file-key>/file.json`). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
+- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only — never write it to a file, a commit, or chat output.
+
+## FIGMA-EXTRACT COMPLETE

package/skills/health/SKILL.md

@@ -53,6 +53,16 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Figma-extract readiness (figma_extract)
+
+After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror/index.cjs`) reports a `figma_extract` check so a user knows whether figma-extract is usable. The detail is one of three exact strings:
+
+- `figma extract: ready (token set)` — `FIGMA_TOKEN` (or `FIGMA_PERSONAL_ACCESS_TOKEN`) is present (status `ok`).
+- `figma extract: token missing` — no token env is set (status `warn`).
+- `figma extract: plugin sync needed for variables (Free tier detected)` — token present but a prior pull recorded a 403/skip on the Variables REST path, so run the plugin-sync step (status `warn`).
+
+Token PRESENCE only is detected (D-10) — the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
+
 ## Check MCP registration (gdd-mcp)
 
 After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.

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 |
 |-------|------|---------|