@hegemonart/get-design-done 1.21.0 → 1.22.0

package/scripts/lib/redact.cjs

@@ -0,0 +1,122 @@
+/**
+ * redact.cjs — secret scrubbing for event-stream payloads (Plan 22-02).
+ *
+ * Deep-walks a value, replacing any string that matches a known secret
+ * pattern with a `[REDACTED:<type>]` placeholder. Non-mutating — returns
+ * a new structure; the input is not modified.
+ *
+ * Called from `event-stream/writer.ts` at serialize time so every event
+ * that hits disk (and every bus subscriber) sees the redacted form.
+ *
+ * Patterns are intentionally conservative: false-positives on redaction
+ * are low-cost (logged telemetry becomes slightly harder to read); false-
+ * negatives (real secrets leaking) are high-cost. When in doubt, match.
+ *
+ * Adding a pattern: append an entry to `PATTERNS` with a stable `type`
+ * key. The type string is the label emitted into the placeholder.
+ */
+
+'use strict';
+
+/** @type {Array<{type: string, re: RegExp}>} */
+const PATTERNS = [
+  // PEM first — must redact before generic base64 patterns would hit.
+  {
+    type: 'pem',
+    re: /-----BEGIN [A-Z ]+-----[\s\S]+?-----END [A-Z ]+-----/g,
+  },
+  // JWT — 3 dot-separated base64url segments, beginning with eyJ.
+  {
+    type: 'jwt',
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  },
+  // Anthropic API keys (sk-ant-…) — matched before generic sk- to win.
+  {
+    type: 'anthropic',
+    re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+  },
+  // Stripe live secret key.
+  {
+    type: 'stripe',
+    re: /\bsk_live_[A-Za-z0-9]{20,}\b/g,
+  },
+  // Slack tokens — xoxb/xoxp/xoxa/xoxr/xoxs.
+  {
+    type: 'slack',
+    re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  },
+  // GitHub personal access token.
+  {
+    type: 'github_pat',
+    re: /\bghp_[A-Za-z0-9]{36,}\b/g,
+  },
+  // AWS access key ID.
+  {
+    type: 'aws',
+    re: /\bAKIA[0-9A-Z]{16}\b/g,
+  },
+  // Generic OpenAI-style sk-… (last in the sk-* family — lower priority
+  // than anthropic/stripe which start with `sk_live_`/`sk-ant-`).
+  {
+    type: 'sk',
+    re: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  },
+];
+
+/**
+ * Redact every secret-shaped substring in `s`, returning the scrubbed
+ * string. Patterns are applied in `PATTERNS` order — more-specific
+ * patterns (anthropic, stripe) first so they win over the generic
+ * `sk-` catch-all.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function redactString(s) {
+  if (typeof s !== 'string' || s.length < 10) return s;
+  let out = s;
+  for (const { type, re } of PATTERNS) {
+    re.lastIndex = 0; // safety: `g` flag carries state across calls
+    out = out.replace(re, `[REDACTED:${type}]`);
+  }
+  return out;
+}
+
+/**
+ * Deep-walk `value`, redacting every string encountered. Arrays and
+ * plain objects recurse; everything else returns unchanged.
+ *
+ * Cycle-safe via a WeakSet.
+ *
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {unknown}
+ */
+function redact(value, seen) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return redactString(value);
+  if (typeof value !== 'object') return value;
+
+  const visited = seen ?? new WeakSet();
+  if (visited.has(/** @type {object} */ (value))) return value;
+  visited.add(/** @type {object} */ (value));
+
+  if (Array.isArray(value)) {
+    return value.map((v) => redact(v, visited));
+  }
+
+  // Plain object. Don't try to preserve class instances — event payloads
+  // are expected to be JSON-shaped bags.
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const key of Object.keys(/** @type {object} */ (value))) {
+    out[key] = redact(/** @type {Record<string, unknown>} */ (value)[key], visited);
+  }
+  return out;
+}
+
+module.exports = {
+  redact,
+  redactString,
+  PATTERNS,
+};

package/scripts/lib/trajectory/index.cjs

@@ -0,0 +1,126 @@
+/**
+ * trajectory/index.cjs — per-tool-call trajectory stream (Plan 22-03).
+ *
+ * Records every agent tool-use as one JSONL line at
+ *   `.design/telemetry/trajectories/<cycle>.jsonl`
+ *
+ * Why hash args/result instead of storing full content:
+ *   * keeps line size bounded regardless of argument payload
+ *   * de-identifies prompts that may contain user-private content
+ *   * still allows replay via dedup-by-hash if a future analyzer wants it
+ *
+ * Schema (one JSONL line):
+ *   {
+ *     ts:          ISO-8601 with ms,
+ *     session_id:  string | null,
+ *     cycle:       string,                  // 'current' if not supplied
+ *     agent:       string,                  // calling agent name
+ *     tool:        string,                  // 'Bash' / 'Edit' / 'mcp__…'
+ *     args_hash:   16-char sha256 prefix of canonical-JSON args
+ *     result_hash: 16-char sha256 prefix of canonical-JSON result
+ *     latency_ms:  number,
+ *     status:      'ok' | 'error',
+ *   }
+ *
+ * Side effects:
+ *   * appendFileSync to the trajectory file (atomic per line on POSIX/NT)
+ *   * NEVER throws — IO failure logs to stderr and returns silently
+ *   * Optionally appends a `tool_call.completed` event to the
+ *     event-stream so live subscribers can see the same call without
+ *     scanning trajectory files. Skipped if `event_stream` arg is null.
+ */
+
+'use strict';
+
+const { appendFileSync, mkdirSync } = require('node:fs');
+const { dirname, isAbsolute, join, resolve } = require('node:path');
+const { createHash } = require('node:crypto');
+
+const DEFAULT_TRAJECTORY_DIR = '.design/telemetry/trajectories';
+
+/**
+ * Compute a stable 16-char sha256-hex prefix for arbitrary JSON-shaped
+ * input. Falls back to `'0'.repeat(16)` if `JSON.stringify` throws.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function hashOf(value) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(value ?? null);
+  } catch {
+    return '0'.repeat(16);
+  }
+  return createHash('sha256').update(serialized ?? '').digest('hex').slice(0, 16);
+}
+
+/**
+ * Resolve the on-disk trajectory file for `cycle` against `baseDir`.
+ *
+ * @param {{baseDir?: string, cycle?: string, dir?: string}} [opts]
+ * @returns {string}
+ */
+function trajectoryPath(opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const dir = opts.dir ?? DEFAULT_TRAJECTORY_DIR;
+  const cycle = (opts.cycle ?? 'current').replace(/[^A-Za-z0-9._-]/g, '_');
+  const resolvedDir = isAbsolute(dir) ? dir : resolve(baseDir, dir);
+  return join(resolvedDir, `${cycle}.jsonl`);
+}
+
+/**
+ * Append one trajectory record. Returns the recorded line for tests
+ * that want to assert on shape without re-reading the file.
+ *
+ * @param {{
+ *   cycle?: string,
+ *   session_id?: string | null,
+ *   agent: string,
+ *   tool: string,
+ *   args?: unknown,
+ *   result?: unknown,
+ *   latency_ms?: number,
+ *   status?: 'ok' | 'error',
+ *   baseDir?: string,
+ *   path?: string,
+ * }} call
+ * @returns {string} the JSONL line that was appended (without trailing \n)
+ */
+function recordCall(call) {
+  const ts = new Date().toISOString();
+  const record = {
+    ts,
+    session_id: call.session_id ?? null,
+    cycle: call.cycle ?? 'current',
+    agent: call.agent,
+    tool: call.tool,
+    args_hash: hashOf(call.args),
+    result_hash: hashOf(call.result),
+    latency_ms: typeof call.latency_ms === 'number' ? call.latency_ms : 0,
+    status: call.status ?? 'ok',
+  };
+
+  const path = call.path ?? trajectoryPath({ baseDir: call.baseDir, cycle: record.cycle });
+  const line = JSON.stringify(record);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, line + '\n', { flag: 'a' });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[trajectory] write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  return line;
+}
+
+module.exports = {
+  recordCall,
+  trajectoryPath,
+  hashOf,
+  DEFAULT_TRAJECTORY_DIR,
+};

package/scripts/lib/transports/ws.cjs

@@ -0,0 +1,179 @@
+/**
+ * transports/ws.cjs — WebSocket event-stream transport (Plan 22-07).
+ *
+ * Optional dep: requires `ws`. probeOptional() returns null if absent;
+ * importer renders a clear install hint.
+ *
+ * Wire format:
+ *   * One event per WebSocket text frame, JSON-encoded.
+ *   * If `tailFrom` is supplied at startup, replay that file's contents
+ *     to each new connection BEFORE subscribing to live events.
+ *   * Live events come from a caller-supplied `subscribe(handler) →
+ *     unsub` — typically the event-stream bus's subscribeAll. Decoupling
+ *     keeps this CommonJS module independent of the TS bus implementation.
+ *
+ * Auth:
+ *   * `Authorization: Bearer <token>` header required on the upgrade.
+ *   * Mismatched / missing token → HTTP 401 close on the upgrade socket.
+ *
+ * Backpressure:
+ *   * Fire-and-forget. If a client's socket is not in OPEN state we drop
+ *     the event for that client and log a warning. No queue.
+ */
+
+'use strict';
+
+const http = require('node:http');
+const { readFileSync, existsSync } = require('node:fs');
+const { probeOptional } = require('../probe-optional.cjs');
+
+const ws = probeOptional('ws');
+if (!ws) {
+  // Importer (gdd-events.mjs) handles this throw and renders the hint.
+  throw new Error(
+    "ws module not installed (optional dep). Install via: npm i -D ws",
+  );
+}
+const { WebSocketServer } = ws;
+
+/**
+ * Synchronously read a JSONL events file and yield parsed objects.
+ * Matches reader.ts line semantics: skip blank lines + invalid JSON.
+ *
+ * @param {string} path
+ * @returns {Generator<Record<string, unknown>>}
+ */
+function* readEventsSync(path) {
+  if (!existsSync(path)) return;
+  const raw = readFileSync(path, 'utf8');
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      yield JSON.parse(line);
+    } catch {
+      /* skip invalid */
+    }
+  }
+}
+
+/**
+ * Start the WebSocket server. Returns a handle with `close()`.
+ *
+ * @param {{
+ *   port: number,
+ *   token: string,
+ *   tailFrom?: string,
+ *   subscribe?: (handler: (ev: unknown) => void) => () => void,
+ * }} opts
+ * @returns {Promise<{close: () => void, port: number}>}
+ */
+async function startServer(opts) {
+  if (typeof opts.port !== 'number' || !Number.isFinite(opts.port)) {
+    throw new TypeError('startServer: port (number) required');
+  }
+  if (typeof opts.token !== 'string' || opts.token.length < 8) {
+    throw new TypeError('startServer: token (string, ≥8 chars) required');
+  }
+
+  const httpServer = http.createServer((_req, res) => {
+    res.statusCode = 426; // Upgrade Required
+    res.setHeader('Content-Type', 'text/plain');
+    res.end('upgrade required');
+  });
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  /** @type {Set<import('ws').WebSocket>} */
+  const clients = new Set();
+
+  /** @type {() => void} */
+  let unsub = () => {};
+  if (typeof opts.subscribe === 'function') {
+    unsub = opts.subscribe((ev) => {
+      const frame = JSON.stringify(ev);
+      for (const client of clients) {
+        if (client.readyState === ws.OPEN) {
+          try {
+            client.send(frame);
+          } catch (err) {
+            try {
+              process.stderr.write(`[ws] send failed: ${err.message}\n`);
+            } catch {
+              /* swallow */
+            }
+          }
+        }
+      }
+    });
+  }
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    const auth = req.headers['authorization'];
+    if (!auth || auth !== `Bearer ${opts.token}`) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (client) => {
+      clients.add(client);
+
+      if (opts.tailFrom) {
+        try {
+          for (const ev of readEventsSync(opts.tailFrom)) {
+            try {
+              client.send(JSON.stringify(ev));
+            } catch {
+              break;
+            }
+          }
+        } catch (err) {
+          try {
+            process.stderr.write(`[ws] replay failed: ${err.message}\n`);
+          } catch {
+            /* swallow */
+          }
+        }
+      }
+
+      client.on('close', () => clients.delete(client));
+      client.on('error', () => clients.delete(client));
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(opts.port, () => resolve(undefined));
+  });
+
+  const addr = httpServer.address();
+  return {
+    port: typeof addr === 'object' && addr ? addr.port : opts.port,
+    close() {
+      try {
+        unsub();
+      } catch {
+        /* swallow */
+      }
+      for (const c of clients) {
+        try {
+          c.close();
+        } catch {
+          /* swallow */
+        }
+      }
+      clients.clear();
+      try {
+        wss.close();
+      } catch {
+        /* swallow */
+      }
+      try {
+        httpServer.close();
+      } catch {
+        /* swallow */
+      }
+    },
+  };
+}
+
+module.exports = { startServer, readEventsSync };