@hegemonart/get-design-done 1.30.6 → 1.31.5

package/scripts/lib/gdd-errors/index.ts

@@ -1,218 +1,29 @@
-// scripts/lib/gdd-errors/index.ts — unified GDD error taxonomy.
+// scripts/lib/gdd-errors/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Three classes exactly — mirrors the GSD errors.ts discipline:
+// Thin deprecation shim. The real implementation moved to sdk/errors/index.ts
+// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
+// path so undocumented EXTERNAL importers (anyone who reached into
+// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-errors/index.ts
+// directly) keep working for one minor grace window.
 //
-//   * ValidationError       — throw at boundary; "fix your input"
-//   * StateConflictError    — throw; lockfile contention or transition guard
-//                             failed; retryable by upstream
-//   * OperationFailedError  — return in data.error; "couldn't complete in
-//                             this state"; expected failure mode the caller
-//                             should branch on, not crash on
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
 //
-// MCP tool handlers place OperationFailedError instances into data.error
-// so the model can see and reason about them. ValidationError and
-// StateConflictError are thrown (non-zero exit path).
-//
-// Plan 20-01 introduced LockAcquisitionError and TransitionGateFailed as
-// local Error subclasses; this module re-exports taxonomy-compliant
-// versions so the existing `gdd-state` surface (tests + consumers) keeps
-// working unchanged. Plan 20-05 wires `toToolError` into MCP tool
-// handlers; Plan 20-06 emits error events to the telemetry stream.
-
-/** Short machine-readable code. Example: "VALIDATION_MISSING_FIELD". */
-export type GDDErrorCode = string;
-
-/**
- * Abstract base class — every GDD taxonomy error inherits from this.
- *
- * Subclasses set a literal `kind` discriminant so `classify()` can
- * branch on it without `instanceof` chains, and `toJSON()` produces a
- * lossless payload for tool-result transport.
- */
-export abstract class GDDError extends Error {
-  abstract readonly kind: 'validation' | 'state_conflict' | 'operation_failed';
-  readonly code: GDDErrorCode;
-  readonly context: Readonly<Record<string, unknown>>;
-
-  constructor(
-    message: string,
-    code: GDDErrorCode,
-    context: Record<string, unknown> = {},
-  ) {
-    super(message);
-    this.code = code;
-    this.context = Object.freeze({ ...context });
-    // Set .name to the concrete subclass name (LockAcquisitionError,
-    // ValidationError, etc.) so error serialization is human-meaningful.
-    this.name = new.target.name;
-  }
-
-  /**
-   * Serialize to a plain object safe for JSON.stringify. Round-trips
-   * through JSON without loss of `name`, `kind`, `code`, `message`, or
-   * `context`. Does NOT include the stack trace — MCP tool handlers do
-   * not forward stacks to the model.
-   */
-  toJSON(): {
-    name: string;
-    kind: GDDError['kind'];
-    code: GDDErrorCode;
-    message: string;
-    context: Readonly<Record<string, unknown>>;
-  } {
-    return {
-      name: this.name,
-      kind: this.kind,
-      code: this.code,
-      message: this.message,
-      context: this.context,
-    };
-  }
-}
-
-/**
- * Throw at boundary when the caller's input is malformed.
- *
- * Example: MCP tool handler receives an argument that fails schema
- * validation; the correct response is `throw new ValidationError(...)`
- * so the harness catches it and returns a structured error to the model.
- * The model should fix its input and retry.
- */
-export class ValidationError extends GDDError {
-  readonly kind = 'validation' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'VALIDATION',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
-}
-
-/**
- * Throw when a concurrency primitive or transition guard vetoes the
- * operation. Retryable by upstream — the caller may try again after a
- * backoff, or surface the blocker to the operator.
- *
- * Examples: lockfile contention (LockAcquisitionError), transition
- * gate failure (TransitionGateFailed).
- */
-export class StateConflictError extends GDDError {
-  readonly kind = 'state_conflict' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'STATE_CONFLICT',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
+
+import { emitWarning } from 'node:process';
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/gdd-errors/index.ts is deprecated; import sdk/errors instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/**
- * Return as `data.error` — do NOT throw. This is the expected failure
- * mode the caller should branch on: the operation is well-formed, the
- * state is valid, but the specific request cannot complete right now.
- *
- * Example: "try to advance to `design`, but no plan exists yet" — the
- * model should be told, not crashed on.
- */
-export class OperationFailedError extends GDDError {
-  readonly kind = 'operation_failed' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'OPERATION_FAILED',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
-}
-
-// -----------------------------------------------------------------------
-// Plan 20-01 compatibility re-exports.
-//
-// These keep the `gdd-state` module's public surface stable post-refactor:
-// - LockAcquisitionError — lockfile contention (plan 20-01 lockfile.ts)
-// - TransitionGateFailed — transition gate veto (plan 20-01 transition())
-// Both are StateConflictError subclasses (retryable / contention-class
-// errors).
-// -----------------------------------------------------------------------
-
-/**
- * Error thrown when `acquire()` cannot obtain the lockfile within
- * `maxWaitMs`. Carries the contents of the offending lockfile (as
- * text — may be JSON, may be garbage if corrupted) so callers can
- * surface them to operators.
- *
- * The `lockPath` and `lockContents` instance properties are preserved
- * from the Plan 20-01 shape for API compat; they're also stored in
- * the frozen `context` object for uniform GDDError serialization.
- */
-export class LockAcquisitionError extends StateConflictError {
-  readonly lockPath: string;
-  readonly lockContents: string;
-  readonly waitedMs: number;
-  constructor(
-    lockPath: string,
-    lockContents: string,
-    waitedMs: number,
-    context?: Record<string, unknown>,
-  ) {
-    super(
-      `failed to acquire lock at ${lockPath} after ${waitedMs}ms; current holder: ${lockContents}`,
-      'LOCK_ACQUISITION',
-      { ...context, lockPath, lockContents, waitedMs },
-    );
-    this.lockPath = lockPath;
-    this.lockContents = lockContents;
-    this.waitedMs = waitedMs;
-  }
-}
-
-/**
- * Error thrown when a transition gate vetoes a stage advance. Carries
- * the frozen list of blocker messages so callers can surface them to
- * operators or retry after resolving.
- *
- * The `blockers` instance property is preserved from the Plan 20-01
- * shape (readonly string[]) for API compat; it's also mirrored into
- * the frozen `context` object for uniform GDDError serialization.
- */
-export class TransitionGateFailed extends StateConflictError {
-  readonly blockers: readonly string[];
-  readonly toStage: string;
-  constructor(
-    toStage: string,
-    blockers: string[],
-    context?: Record<string, unknown>,
-  ) {
-    super(
-      `transition to "${toStage}" blocked by gate: ${blockers.join('; ') || '(no detail)'}`,
-      'TRANSITION_GATE_FAILED',
-      { ...context, toStage, blockers: [...blockers] },
-    );
-    this.toStage = toStage;
-    this.blockers = Object.freeze([...blockers]);
-  }
-}
-
-/**
- * Error thrown by STATE.md `parse()` when the input cannot be
- * interpreted. `ValidationError` semantics: the caller (likely the
- * operator or an upstream generator) gave us malformed input — fix
- * your STATE.md and retry.
- *
- * The `line` instance property points at the 1-indexed line in the
- * source markdown where the parser gave up. It's also mirrored into
- * the frozen `context` object.
- */
-export class ParseError extends ValidationError {
-  readonly line: number;
-  constructor(message: string, line: number, context?: Record<string, unknown>) {
-    super(
-      `STATE.md parse error at line ${line}: ${message}`,
-      'PARSE_ERROR',
-      { ...context, line },
-    );
-    this.line = line;
-  }
-}
+export * from '../../../sdk/errors/index.ts';

package/scripts/lib/gdd-state/index.ts

@@ -1,167 +1,29 @@
-// scripts/lib/gdd-state/index.ts — public API for the gdd-state module.
+// scripts/lib/gdd-state/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// 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
+// Thin deprecation shim. The real implementation moved to sdk/state/index.ts
+// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
+// path so undocumented EXTERNAL importers (anyone who reached into
+// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-state/index.ts
+// directly) keep working for one minor grace window.
 //
-// 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';
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
+//
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
 
-/**
- * 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;
-}
+import { emitWarning } from 'node:process';
 
-/**
- * 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();
-  }
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/gdd-state/index.ts is deprecated; import sdk/state instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/**
- * 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 };
-}
+export * from '../../../sdk/state/index.ts';

package/scripts/lib/health-mirror/index.cjs

@@ -8,12 +8,13 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 5 checks (in stable order) are:
+// The 6 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
 //   4. package_json         — package.json present AND parseable
 //   5. issue_reporter       — kill-switch state (Plan 30-06 / D-08)
+//   6. figma_extract        — extract readiness + Free-tier signal (Plan 31-09)
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -22,6 +23,17 @@
 //   - "issue reporter: disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)"
 //   - "issue reporter: disabled by config (.design/config.json: issue_reporter=false)"
 // When both env and config trigger, env wins (matches D-08 display contract).
+//
+// Check 6 was added in Plan 31-09 — surfaces figma-extract readiness so a user
+// running /gdd:health immediately knows whether figma-extract is usable. The
+// detail line is one of three exact strings:
+//   - "figma extract: ready (token set)"
+//   - "figma extract: token missing"
+//   - "figma extract: plugin sync needed for variables (Free tier detected)"
+// D-10: only FIGMA_TOKEN *presence* is used — the token VALUE is never read,
+// logged, or placed in the detail. The Free-tier state is derived from a LOCAL
+// signal only (a prior pull's _meta.json recording a 403/skip on the Variables
+// endpoint) — never a live network call (health-mirror is pure read-only).
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -135,7 +147,82 @@ async function getHealthChecks(rootDir) {
     });
   }
 
+  // 6. figma_extract — extract readiness + Free-tier plugin-sync signal (Plan 31-09)
+  // Reports exactly one of three states. PURE read-only: presence-only token
+  // check (D-10 — value never read/logged/printed) + a LOCAL Free-tier marker
+  // (a prior pull's _meta.json recording a 403/skip on the Variables endpoint —
+  // see scripts/lib/figma-extract/pull.cjs). NEVER throws, NEVER networks.
+  {
+    // D-10: presence only. The token VALUE is never bound to a variable that
+    // could be interpolated into detail/logs — only the boolean is kept.
+    const tokenSet = !!(process.env.FIGMA_TOKEN || process.env.FIGMA_PERSONAL_ACCESS_TOKEN);
+
+    let detail;
+    let status;
+    if (!tokenSet) {
+      detail = 'figma extract: token missing';
+      status = 'warn';
+    } else if (figmaVariablesBlockedLocally(rootDir)) {
+      // Token present but a prior pull recorded a 403/skip on the Variables REST
+      // path → Free/non-Enterprise tier. Actionable (plugin sync), not a hard fail.
+      detail = 'figma extract: plugin sync needed for variables (Free tier detected)';
+      status = 'warn';
+    } else {
+      detail = 'figma extract: ready (token set)';
+      status = 'ok';
+    }
+    checks.push({ name: 'figma_extract', status, detail });
+  }
+
   return { checks };
 }
 
+/**
+ * Free-tier signal (LOCAL only — never a network call). The raw-pull stage
+ * (scripts/lib/figma-extract/pull.cjs) writes a _meta.json per file key under
+ * the gitignored cache dir; on a Variables 403 it records a totals[] entry
+ * `{ name: 'variables', skipped: true, reason: 'HTTP 403' }`. We scan the
+ * default cache root for any such marker. Defensive: malformed/absent markers
+ * default to NOT-free (→ 'ready') so the health probe never false-alarms and
+ * NEVER throws. NEVER reads the token; NEVER makes a request.
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {boolean} true iff a prior pull recorded a Variables 403/skip
+ */
+function figmaVariablesBlockedLocally(rootDir) {
+  try {
+    const rawRoot = path.join(rootDir, '.figma-extract-cache', 'raw');
+    let entries;
+    try {
+      entries = fs.readdirSync(rawRoot, { withFileTypes: true });
+    } catch {
+      return false; // no cache yet → default to ready
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const metaPath = path.join(rawRoot, ent.name, '_meta.json');
+      let meta;
+      try {
+        meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      } catch {
+        continue; // missing/garbage marker → ignore this dir, keep scanning
+      }
+      const totals = meta && Array.isArray(meta.totals) ? meta.totals : [];
+      const blocked = totals.some(
+        (t) =>
+          t &&
+          t.name === 'variables' &&
+          t.skipped === true &&
+          typeof t.reason === 'string' &&
+          /403/.test(t.reason)
+      );
+      if (blocked) return true;
+    }
+    return false;
+  } catch {
+    // Absolute safety net — the health probe must never crash on this check.
+    return false;
+  }
+}
+
 module.exports = { getHealthChecks };