@hegemonart/get-design-done 1.21.0 → 1.23.0

package/scripts/lib/connection-probe/index.cjs

@@ -0,0 +1,263 @@
+/**
+ * connection-probe/index.cjs — code-level connection liveness probe
+ * (Plan 22-08).
+ *
+ * Replaces today's per-connection ad-hoc probe bash snippets in
+ * `connections/` with one typed primitive. Used by Phase 21
+ * pipeline-runner and Phase 22 reflector.
+ *
+ * Contract:
+ *   probe({
+ *     name:     'figma' | 'pinterest' | …    // free-form connection id
+ *     cmd:      async () => boolean | Truthy  // probe action
+ *     timeout:  number ms                     // default 5000
+ *     retries:  number                        // default 3 attempts total
+ *     fallback: async () => unknown           // optional degraded path
+ *   }) → {
+ *     status:        'ok' | 'degraded' | 'down'
+ *     latency_ms:    number
+ *     attempts:      number
+ *     fallback_used: boolean
+ *     error?:        string                   // last error message if any
+ *   }
+ *
+ * State persistence:
+ *   * `.design/telemetry/connection-state.json` records `{name → status}`
+ *     across runs.
+ *   * On every probe, if the new status differs from cached, emit a
+ *     `connection.status_change` event via the event-stream bus and
+ *     overwrite the cached value atomically (write to .tmp + rename).
+ *
+ * Backoff:
+ *   * Uses `jittered-backoff.cjs` — `delayMs(attempt)` between retries.
+ *
+ * The probe `cmd` is awaited with a Promise.race against a timeout. On
+ * fulfilment with truthy → ok. On rejection or falsy → fail-this-attempt;
+ * retry until exhausted. After full-fail, if `fallback` is supplied,
+ * runs it and reports `degraded` + `fallback_used: true`.
+ */
+
+'use strict';
+
+const { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } = require('node:fs');
+const { dirname, isAbsolute, resolve, join } = require('node:path');
+
+const { delayMs } = require('../jittered-backoff.cjs');
+
+const DEFAULT_STATE_PATH = '.design/telemetry/connection-state.json';
+
+/**
+ * Resolve the connection-state file path against a base dir.
+ * @param {{baseDir?: string, statePath?: string}} [opts]
+ */
+function statePathFor(opts = {}) {
+  const raw = opts.statePath ?? DEFAULT_STATE_PATH;
+  if (isAbsolute(raw)) return raw;
+  return resolve(opts.baseDir ?? process.cwd(), raw);
+}
+
+/**
+ * Load + return the cached state object (or `{}` if absent / corrupt).
+ * @param {string} path
+ * @returns {Record<string, string>}
+ */
+function loadState(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Atomic state write: write to `.tmp` sibling, rename. Renames are
+ * atomic on POSIX and at least crash-safe on Windows for same-volume
+ * targets.
+ * @param {string} path
+ * @param {Record<string, string>} state
+ */
+function saveState(path, state) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(state, null, 2));
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[connection-probe] state write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Race `promise` against a timeout. Rejects with `TimeoutError` after
+ * `ms` if the promise hasn't settled.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const err = new Error(`probe timed out after ${ms}ms`);
+      err.code = 'PROBE_TIMEOUT';
+      reject(err);
+    }, ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+/**
+ * Run the probe with retries + optional fallback. Resolves to a
+ * structured outcome; never rejects.
+ *
+ * @param {{
+ *   name: string,
+ *   cmd: () => Promise<unknown>,
+ *   timeout?: number,
+ *   retries?: number,
+ *   fallback?: () => Promise<unknown>,
+ *   baseDir?: string,
+ *   statePath?: string,
+ *   emit?: (ev: unknown) => void,
+ * }} opts
+ * @returns {Promise<{
+ *   status: 'ok' | 'degraded' | 'down',
+ *   latency_ms: number,
+ *   attempts: number,
+ *   fallback_used: boolean,
+ *   error?: string,
+ * }>}
+ */
+async function probe(opts) {
+  if (!opts || typeof opts.name !== 'string' || opts.name.length === 0) {
+    throw new TypeError('probe: name (string) required');
+  }
+  if (typeof opts.cmd !== 'function') {
+    throw new TypeError('probe: cmd (async fn) required');
+  }
+  const timeout = opts.timeout ?? 5000;
+  const retries = Math.max(1, opts.retries ?? 3);
+  const path = statePathFor(opts);
+
+  const start = Date.now();
+  let attempts = 0;
+  let lastError;
+
+  for (let i = 0; i < retries; i++) {
+    attempts += 1;
+    try {
+      const result = await withTimeout(Promise.resolve(opts.cmd()), timeout);
+      if (result) {
+        const outcome = {
+          status: /** @type {'ok'} */ ('ok'),
+          latency_ms: Date.now() - start,
+          attempts,
+          fallback_used: false,
+        };
+        await recordTransition(opts.name, outcome.status, path, opts.emit);
+        return outcome;
+      }
+      // falsy = soft-fail; retry
+      lastError = new Error('probe returned falsy');
+    } catch (err) {
+      lastError = err;
+    }
+    if (i < retries - 1) {
+      await sleep(delayMs(i));
+    }
+  }
+
+  // All retries failed. Try fallback if supplied.
+  if (typeof opts.fallback === 'function') {
+    try {
+      await opts.fallback();
+      const outcome = {
+        status: /** @type {'degraded'} */ ('degraded'),
+        latency_ms: Date.now() - start,
+        attempts,
+        fallback_used: true,
+        error: lastError && lastError.message ? lastError.message : String(lastError),
+      };
+      await recordTransition(opts.name, outcome.status, path, opts.emit);
+      return outcome;
+    } catch {
+      /* fall through to down */
+    }
+  }
+
+  const outcome = {
+    status: /** @type {'down'} */ ('down'),
+    latency_ms: Date.now() - start,
+    attempts,
+    fallback_used: false,
+    error: lastError && lastError.message ? lastError.message : String(lastError),
+  };
+  await recordTransition(opts.name, outcome.status, path, opts.emit);
+  return outcome;
+}
+
+/** Sleep for `ms` milliseconds. */
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Compare against cached state. If status differs, emit a
+ * `connection.status_change` event (when an `emit` callback is supplied)
+ * and overwrite the cached value atomically.
+ *
+ * @param {string} name
+ * @param {string} status
+ * @param {string} statePath
+ * @param {undefined | ((ev: unknown) => void)} emit
+ */
+async function recordTransition(name, status, statePath, emit) {
+  const state = loadState(statePath);
+  const previous = state[name];
+  if (previous === status) return; // no transition
+  state[name] = status;
+  saveState(statePath, state);
+  if (typeof emit === 'function') {
+    try {
+      emit({
+        type: 'connection.status_change',
+        timestamp: new Date().toISOString(),
+        sessionId: process.env.GDD_SESSION_ID || 'unknown',
+        payload: { name, from: previous ?? 'unknown', to: status },
+      });
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[connection-probe] emit failed: ${err && err.message ? err.message : String(err)}\n`,
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+module.exports = {
+  probe,
+  statePathFor,
+  loadState,
+  saveState,
+  DEFAULT_STATE_PATH,
+};

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