@hegemonart/get-design-done 1.22.0 → 1.23.5

package/scripts/lib/design-solidify.mjs

@@ -0,0 +1,265 @@
+/**
+ * design-solidify.mjs — solidify-with-rollback gate (Plan 23-02).
+ *
+ * Code-level gate that runs the validation triplet for a task and, on
+ * any failure, rolls the working tree back via git stash (configurable)
+ * and appends a `solidify.rollback` event onto the Phase 22 causal chain.
+ *
+ * Replaces the prompt-encoded "stash if it broke" instruction in today's
+ * solidify agents with a typed, testable function.
+ *
+ * Why .mjs, not .ts:
+ *   * Node 24 + Windows + .mjs dynamic-importing .ts triggers
+ *     STATUS_STACK_BUFFER_OVERRUN (Phase 22 lesson). Keep this file as
+ *     plain .mjs with a CJS test wrapper.
+ *
+ * Usage:
+ *   import { solidify } from './design-solidify.mjs';
+ *   const result = await solidify({ taskId: '23-02' });
+ *   // result.outcome === 'pass' | 'fail'
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// Anchor on the .mjs file's own directory — NOT on the caller's cwd —
+// because callers pass in arbitrary `cwd` values (test scaffolds,
+// sub-repos) where event-chain.cjs is unreachable. Walk up from
+// scripts/lib/ to repo root.
+const __filename = fileURLToPath(import.meta.url);
+function _findRepoRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+const PLUGIN_ROOT = _findRepoRoot(dirname(__filename));
+const _nodeRequire = createRequire(join(PLUGIN_ROOT, 'package.json'));
+const { appendChainEvent } = _nodeRequire(
+  resolve(PLUGIN_ROOT, 'scripts/lib/event-chain.cjs'),
+);
+
+/**
+ * @typedef {Object} SolidifyValidation
+ * @property {string} name
+ * @property {string} cmd
+ * @property {string[]} args
+ * @property {number} [timeout_ms]
+ */
+
+/**
+ * @typedef {Object} SolidifyOptions
+ * @property {string} taskId
+ * @property {SolidifyValidation[]} [validations]
+ * @property {'stash'|'hard'|'none'} [rollback]
+ * @property {string} [cwd]
+ * @property {string[]} [decisionRefs]
+ * @property {string} [parentEventId]
+ * @property {(ev: object) => void} [emit]
+ * @property {string} [chainPath]
+ */
+
+/**
+ * @typedef {Object} SolidifyStep
+ * @property {string} name
+ * @property {'pass'|'fail'} status
+ * @property {string} [stdout]
+ * @property {string} [stderr]
+ * @property {number|null} [code]
+ * @property {string|null} [signal]
+ */
+
+/**
+ * @typedef {Object} SolidifyResult
+ * @property {'pass'|'fail'} outcome
+ * @property {SolidifyStep[]} steps
+ * @property {'stash'|'hard'|'none'|'skipped'} [rolledBackVia]
+ * @property {string} eventId
+ * @property {string} [stashRef]
+ */
+
+/**
+ * Build the default validation triplet for a task. Caller may override
+ * by supplying `opts.validations` directly.
+ *
+ * @param {string} taskId
+ * @returns {SolidifyValidation[]}
+ */
+function defaultValidations(taskId) {
+  return [
+    { name: 'typecheck', cmd: 'npm', args: ['run', 'typecheck'], timeout_ms: 120_000 },
+    { name: 'build', cmd: 'npm', args: ['run', 'build'], timeout_ms: 300_000 },
+    {
+      name: 'targeted-test',
+      cmd: 'npm',
+      args: ['test', '--', '--testPathPattern', String(taskId)],
+      timeout_ms: 120_000,
+    },
+  ];
+}
+
+/**
+ * Run one validation step via spawnSync. Always returns a step record;
+ * never throws.
+ *
+ * @param {SolidifyValidation} v
+ * @param {string} cwd
+ * @returns {SolidifyStep}
+ */
+function runStep(v, cwd) {
+  const r = spawnSync(v.cmd, v.args, {
+    cwd,
+    encoding: 'utf8',
+    shell: false,
+    timeout: v.timeout_ms ?? 120_000,
+  });
+  const status = r.status === 0 && !r.error ? 'pass' : 'fail';
+  return {
+    name: v.name,
+    status,
+    stdout: r.stdout,
+    stderr: r.stderr || (r.error ? String(r.error.message || r.error) : undefined),
+    code: r.status,
+    signal: r.signal,
+  };
+}
+
+/**
+ * Roll the tree back per the configured strategy. Never throws —
+ * returns the resolved verb (or 'skipped' if the strategy could not be
+ * applied) and an optional stash ref.
+ *
+ * @param {'stash'|'hard'|'none'} mode
+ * @param {string} cwd
+ * @param {string} taskId
+ * @returns {{via: 'stash'|'hard'|'none'|'skipped', stashRef?: string}}
+ */
+function rollback(mode, cwd, taskId) {
+  if (mode === 'none') return { via: 'none' };
+  if (!existsSync(join(cwd, '.git'))) return { via: 'skipped' };
+  const ts = new Date().toISOString();
+
+  if (mode === 'stash') {
+    const r = spawnSync(
+      'git',
+      ['stash', 'push', '-u', '-m', `solidify-rollback:${taskId}:${ts}`],
+      { cwd, encoding: 'utf8', shell: false, timeout: 30_000 },
+    );
+    if (r.status !== 0) return { via: 'skipped' };
+    const refRes = spawnSync('git', ['stash', 'list', '-1', '--format=%gd'], {
+      cwd,
+      encoding: 'utf8',
+      shell: false,
+      timeout: 10_000,
+    });
+    const stashRef = refRes.status === 0 ? refRes.stdout.trim() : undefined;
+    return { via: 'stash', stashRef };
+  }
+
+  if (mode === 'hard') {
+    const r = spawnSync('git', ['reset', '--hard', 'HEAD'], {
+      cwd,
+      encoding: 'utf8',
+      shell: false,
+      timeout: 30_000,
+    });
+    if (r.status !== 0) return { via: 'skipped' };
+    return { via: 'hard' };
+  }
+
+  return { via: 'skipped' };
+}
+
+/**
+ * Run the solidify gate.
+ *
+ * @param {SolidifyOptions} opts
+ * @returns {Promise<SolidifyResult>}
+ */
+export async function solidify(opts) {
+  if (!opts || typeof opts.taskId !== 'string' || opts.taskId.length === 0) {
+    throw new TypeError('solidify: opts.taskId is required (non-empty string)');
+  }
+  const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+  const validations =
+    Array.isArray(opts.validations) && opts.validations.length > 0
+      ? opts.validations
+      : defaultValidations(opts.taskId);
+  const mode = opts.rollback ?? 'stash';
+
+  /** @type {SolidifyStep[]} */
+  const steps = [];
+  /** @type {SolidifyStep|null} */
+  let failingStep = null;
+  for (const v of validations) {
+    const step = runStep(v, cwd);
+    steps.push(step);
+    if (step.status === 'fail') {
+      failingStep = step;
+      break;
+    }
+  }
+
+  let rolledBackVia = 'none';
+  let stashRef;
+  if (failingStep && mode !== 'none') {
+    const r = rollback(mode, cwd, opts.taskId);
+    rolledBackVia = r.via;
+    stashRef = r.stashRef;
+  } else if (failingStep && mode === 'none') {
+    rolledBackVia = 'none';
+  }
+
+  const chainEvent = {
+    parent_event_id: opts.parentEventId ?? null,
+    agent: 'design-solidify',
+    decision_refs: opts.decisionRefs ?? [],
+    outcome: failingStep ? 'rolled-back' : 'pass',
+    task_id: opts.taskId,
+    rolled_back_via: rolledBackVia,
+    steps: steps.map((s) => ({ name: s.name, status: s.status, code: s.code })),
+  };
+  if (failingStep) {
+    chainEvent.rollback_reason = `${failingStep.name} failed (code=${failingStep.code})`;
+  }
+  if (stashRef) chainEvent.stash_ref = stashRef;
+  if (opts.chainPath) chainEvent.path = opts.chainPath;
+  if (opts.cwd) chainEvent.baseDir = opts.cwd;
+
+  const eventId = appendChainEvent(chainEvent);
+
+  if (typeof opts.emit === 'function') {
+    try {
+      opts.emit({
+        type: 'solidify.rollback',
+        timestamp: new Date().toISOString(),
+        sessionId: process.env.GDD_SESSION_ID || 'unknown',
+        payload: {
+          task_id: opts.taskId,
+          outcome: chainEvent.outcome,
+          rolled_back_via: rolledBackVia,
+          failing_step: failingStep ? failingStep.name : null,
+        },
+      });
+    } catch {
+      /* swallow — emission must never bubble */
+    }
+  }
+
+  /** @type {SolidifyResult} */
+  const result = {
+    outcome: failingStep ? 'fail' : 'pass',
+    steps,
+    rolledBackVia,
+    eventId,
+  };
+  if (stashRef) result.stashRef = stashRef;
+  return result;
+}

package/scripts/lib/design-tokens/_js-harness.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * _js-harness.cjs — child process worker for js-const.cjs.
+ *
+ * Reads argv[2] as a file path, attempts to require() it (CJS first,
+ * then dynamic import for ESM), extracts tokens per recognised shapes,
+ * prints `{tokens: ..., error?: string}` JSON on stdout, exits 0.
+ *
+ * Never throws — errors are returned as JSON so the parent can render
+ * them as warnings.
+ */
+
+'use strict';
+
+const target = process.argv[2];
+
+function main() {
+  if (!target) {
+    return { tokens: {}, error: 'no-target' };
+  }
+  // Try CJS require first.
+  try {
+    // eslint-disable-next-line node/no-missing-require, global-require
+    const mod = require(target);
+    return { tokens: extract(mod) };
+  } catch (cjsErr) {
+    // Fall through to dynamic import.
+  }
+  // ESM dynamic import — async; wrap in IIFE.
+  return new Promise((resolve) => {
+    const url = require('node:url').pathToFileURL(target).href;
+    import(url).then(
+      (mod) => {
+        const candidate = mod.tokens ?? mod.default?.tokens ?? mod.default ?? mod;
+        resolve({ tokens: extract(candidate) });
+      },
+      (err) => resolve({ tokens: {}, error: `import-failed: ${err.message || String(err)}` }),
+    );
+  });
+}
+
+function extract(mod) {
+  if (mod && typeof mod === 'object') {
+    if (mod.tokens && typeof mod.tokens === 'object') return mod.tokens;
+    if (mod.default && typeof mod.default === 'object' && mod.default.tokens) {
+      return mod.default.tokens;
+    }
+    return mod;
+  }
+  return {};
+}
+
+Promise.resolve(main()).then(
+  (result) => {
+    try {
+      process.stdout.write(JSON.stringify(result));
+    } catch {
+      process.stdout.write(JSON.stringify({ tokens: {}, error: 'stringify-failed' }));
+    }
+    process.exit(0);
+  },
+  (err) => {
+    process.stdout.write(JSON.stringify({ tokens: {}, error: String(err) }));
+    process.exit(0);
+  },
+);

package/scripts/lib/design-tokens/css-vars.cjs

@@ -0,0 +1,55 @@
+/**
+ * design-tokens/css-vars.cjs — extract custom-property declarations
+ * from CSS / SCSS source (Plan 23-08).
+ *
+ * Parses any `--name: value;` declarations regardless of selector
+ * context. Last-write-wins on duplicate names. Block comments stripped.
+ * Strips the `--` prefix in the returned token map.
+ *
+ * Not supported (caller-warned via warnings):
+ *   * SCSS `$var: value;` syntax — use the JS reader for SCSS exports
+ *   * calc() / var() reference resolution — values returned verbatim
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CUSTOM_PROP_RE = /--([A-Za-z0-9][A-Za-z0-9_-]*)\s*:\s*([^;]+?)\s*(?=[;}])/g;
+const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+const SCSS_VAR_RE = /^\s*\$[A-Za-z][A-Za-z0-9_-]*\s*:/m;
+
+/**
+ * Read a CSS/SCSS file and extract `--token: value;` declarations.
+ *
+ * @param {string} filePath
+ * @returns {{tokens: Record<string, string>, source: string, format: 'css-vars', warnings: string[]}}
+ */
+function readCssVars(filePath) {
+  const abs = path.resolve(filePath);
+  const raw = fs.readFileSync(abs, 'utf8');
+  const stripped = raw.replace(BLOCK_COMMENT_RE, '');
+  /** @type {string[]} */
+  const warnings = [];
+  if (SCSS_VAR_RE.test(stripped)) {
+    warnings.push('scss-vars-detected: $var: ... declarations are not parsed by css-vars.cjs');
+  }
+  /** @type {Record<string, string>} */
+  const tokens = {};
+  CUSTOM_PROP_RE.lastIndex = 0;
+  let m;
+  while ((m = CUSTOM_PROP_RE.exec(stripped)) !== null) {
+    const name = m[1];
+    const value = m[2].trim();
+    tokens[name] = value;
+  }
+  return {
+    tokens,
+    source: abs,
+    format: 'css-vars',
+    warnings,
+  };
+}
+
+module.exports = { readCssVars };

package/scripts/lib/design-tokens/figma.cjs

@@ -0,0 +1,121 @@
+/**
+ * design-tokens/figma.cjs — parse a Figma variable export JSON into
+ * a flat token map (Plan 23-08).
+ *
+ * Consumes the shape returned by mcp__figma__get_variable_defs (and the
+ * official Figma Variables Export JSON). Handles either:
+ *   * `{ variableCollections: { <id>: { name, modes, variables: { <id>: {name, valuesByMode} } } } }`
+ *   * Already-flattened `{ name: value }` map (passes through with format='figma')
+ *
+ * Mode handling: when a variable has multiple modes, we emit one token
+ * per mode using `<collection>.<varName>.<modeName>`. Single-mode
+ * variables emit the bare path.
+ *
+ * Color values are emitted as `rgba(R, G, B, A)` strings; numeric +
+ * string values pass through verbatim.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function rgbaFor(c) {
+  if (typeof c !== 'object' || c === null) return String(c);
+  const r = Math.round((Number(c.r) || 0) * 255);
+  const g = Math.round((Number(c.g) || 0) * 255);
+  const b = Math.round((Number(c.b) || 0) * 255);
+  const a = c.a === undefined ? 1 : Number(c.a);
+  return a === 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function valueToString(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+    return String(v);
+  }
+  if (typeof v === 'object') {
+    // Color shape: {r, g, b, a?}.
+    if (Object.prototype.hasOwnProperty.call(v, 'r') &&
+        Object.prototype.hasOwnProperty.call(v, 'g') &&
+        Object.prototype.hasOwnProperty.call(v, 'b')) {
+      return rgbaFor(v);
+    }
+    // Alias / reference — emit the full reference id for the consumer to resolve.
+    if (v.type === 'VARIABLE_ALIAS' && v.id) return `var(--${v.id})`;
+    return JSON.stringify(v);
+  }
+  return String(v);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{tokens: Record<string, string>, source: string, format: 'figma', warnings: string[]}}
+ */
+function readFigma(filePath) {
+  const abs = path.resolve(filePath);
+  const raw = fs.readFileSync(abs, 'utf8');
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'figma',
+      warnings: [`json-parse-failed: ${err.message}`],
+    };
+  }
+
+  /** @type {Record<string, string>} */
+  const out = {};
+  // Branch 1: variableCollections shape.
+  if (parsed && typeof parsed === 'object' && parsed.variableCollections) {
+    for (const collId of Object.keys(parsed.variableCollections)) {
+      const coll = parsed.variableCollections[collId];
+      const collName = coll.name || collId;
+      const modes = coll.modes || {};
+      // modes might be an array of {modeId, name} or a map.
+      const modeNames = Array.isArray(modes)
+        ? new Map(modes.map((m) => [m.modeId, m.name]))
+        : new Map(Object.entries(modes).map(([id, m]) => [id, (m && m.name) || id]));
+      const vars = coll.variables || {};
+      for (const varId of Object.keys(vars)) {
+        const v = vars[varId];
+        const varName = v.name || varId;
+        const valuesByMode = v.valuesByMode || {};
+        const modeIds = Object.keys(valuesByMode);
+        if (modeIds.length === 0) {
+          warnings.push(`no-modes: ${collName}.${varName}`);
+          continue;
+        }
+        if (modeIds.length === 1) {
+          const key = `${collName}.${varName}`;
+          out[key] = valueToString(valuesByMode[modeIds[0]]);
+        } else {
+          for (const mid of modeIds) {
+            const modeName = modeNames.get(mid) || mid;
+            out[`${collName}.${varName}.${modeName}`] = valueToString(valuesByMode[mid]);
+          }
+        }
+      }
+    }
+    return { tokens: out, source: abs, format: 'figma', warnings };
+  }
+
+  // Branch 2: already-flattened bag.
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    for (const k of Object.keys(parsed)) {
+      out[k] = valueToString(parsed[k]);
+    }
+    return { tokens: out, source: abs, format: 'figma', warnings };
+  }
+
+  warnings.push('unrecognised-figma-shape');
+  return { tokens: out, source: abs, format: 'figma', warnings };
+}
+
+module.exports = { readFigma };

package/scripts/lib/design-tokens/index.cjs

@@ -0,0 +1,100 @@
+/**
+ * design-tokens/index.cjs — facade over the four token readers
+ * (Plan 23-08).
+ *
+ * Auto-detects format from extension + content sniff, dispatches to
+ * css-vars / js-const / tailwind / figma. Returns the uniform
+ * `{tokens, source, format, warnings}` shape from each reader.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readCssVars } = require('./css-vars.cjs');
+const { readJsConst } = require('./js-const.cjs');
+const { readTailwind } = require('./tailwind.cjs');
+const { readFigma } = require('./figma.cjs');
+
+/**
+ * @typedef {Object} TokenSet
+ * @property {Object<string, string>} tokens
+ * @property {string} source
+ * @property {'css-vars'|'js-const'|'tailwind'|'figma'} format
+ * @property {string[]} [warnings]
+ */
+
+/**
+ * Sniff format from a file's extension + a head-snippet of its content.
+ *
+ * @param {string} filePath
+ * @returns {'css-vars'|'js-const'|'tailwind'|'figma'}
+ */
+function detectFormat(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.css') || lower.endsWith('.scss')) return 'css-vars';
+  if (
+    /tailwind\.config\.(js|cjs|mjs|ts)$/.test(lower) ||
+    lower.endsWith('tailwind.config.js')
+  ) {
+    return 'tailwind';
+  }
+  if (lower.endsWith('.json')) {
+    // Sniff: variableCollections → figma, else js-const path with the JSON.
+    try {
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 4096);
+      if (head.includes('"variableCollections"')) return 'figma';
+    } catch {
+      /* fall through */
+    }
+    return 'figma';
+  }
+  // Default: any other JS/TS file is js-const.
+  return 'js-const';
+}
+
+/**
+ * Read tokens from a file with auto-detected format.
+ *
+ * @param {string} filePath
+ * @returns {TokenSet}
+ */
+function read(filePath) {
+  const format = detectFormat(filePath);
+  switch (format) {
+    case 'css-vars':
+      return readCssVars(filePath);
+    case 'tailwind':
+      return readTailwind(filePath);
+    case 'figma':
+      return readFigma(filePath);
+    case 'js-const':
+    default:
+      return readJsConst(filePath);
+  }
+}
+
+/**
+ * Read multiple files into separate TokenSets.
+ *
+ * @param {string[]} filePaths
+ * @returns {TokenSet[]}
+ */
+function readAll(filePaths) {
+  if (!Array.isArray(filePaths)) {
+    throw new TypeError('design-tokens: filePaths must be an array');
+  }
+  return filePaths.map((p) => read(p));
+}
+
+module.exports = {
+  read,
+  readAll,
+  detectFormat,
+  // re-export for callers that already know the format
+  readCssVars,
+  readJsConst,
+  readTailwind,
+  readFigma,
+};