@tekyzinc/gsd-t 3.24.10 → 3.25.11

package/bin/cli-preflight-checks/working-tree-state.cjs

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * working-tree-state — git working tree clean or matches dirtyTreeWhitelist.
+ *
+ * Severity: warn.
+ *
+ * Reads `dirtyTreeWhitelist: string[]` from `.gsd-t/.unattended/config.json`.
+ * Each dirty path from `git status --porcelain` must match the whitelist for
+ * the check to pass. Whitelist patterns use simple glob:
+ *   - `**`  matches any sequence of characters (including `/`)
+ *   - `*`   matches any non-`/` segment
+ *   - everything else is literal
+ *
+ * If the working tree is clean, the check passes with no whitelist consulted.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ID = 'working-tree-state';
+
+function _readWhitelist(projectDir) {
+  const cfgPath = path.join(projectDir, '.gsd-t', '.unattended', 'config.json');
+  if (!fs.existsSync(cfgPath)) return [];
+  let raw;
+  try { raw = fs.readFileSync(cfgPath, 'utf8'); } catch (_) { return []; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch (_) { return []; }
+  const list = parsed && parsed.dirtyTreeWhitelist;
+  if (!Array.isArray(list)) return [];
+  return list.filter((s) => typeof s === 'string' && s.length > 0);
+}
+
+function _porcelain(projectDir) {
+  const stdout = execSync('git status --porcelain', {
+    cwd: projectDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return String(stdout || '');
+}
+
+function _parseDirtyPaths(porcelain) {
+  // `git status --porcelain` output: "XY path" or "XY path1 -> path2" (rename).
+  // We take the (final) path; X/Y are status codes.
+  const out = [];
+  const lines = porcelain.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line || line.length < 4) continue;
+    let rest = line.slice(3);
+    // Handle quoted paths from git (when path contains special chars).
+    if (rest.startsWith('"') && rest.endsWith('"')) {
+      rest = rest.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    // Handle rename: "old -> new"
+    const renameIdx = rest.indexOf(' -> ');
+    if (renameIdx >= 0) rest = rest.slice(renameIdx + 4);
+    out.push(rest);
+  }
+  return out;
+}
+
+function _globToRegex(glob) {
+  // Escape regex specials except `*`, then expand `*` semantics.
+  // Use a placeholder dance so `**` becomes `.*` and `*` becomes `[^/]*`.
+  let s = '';
+  let i = 0;
+  while (i < glob.length) {
+    const ch = glob[i];
+    if (ch === '*' && glob[i + 1] === '*') {
+      s += '.*';
+      i += 2;
+      // Swallow optional trailing slash so `foo/**` matches `foo/anything`
+      // and also exactly `foo` is NOT matched (whitelisting expects the dir
+      // contents). Simpler semantic: just .* — caller can decide.
+      continue;
+    }
+    if (ch === '*') {
+      s += '[^/]*';
+      i++;
+      continue;
+    }
+    if (/[.+^${}()|[\]\\?]/.test(ch)) {
+      s += '\\' + ch;
+      i++;
+      continue;
+    }
+    s += ch;
+    i++;
+  }
+  return new RegExp('^' + s + '$');
+}
+
+function _matchesAny(p, patterns) {
+  for (const pat of patterns) {
+    if (_globToRegex(pat).test(p)) return true;
+  }
+  return false;
+}
+
+function run({ projectDir }) {
+  let porcelain;
+  try {
+    porcelain = _porcelain(projectDir);
+  } catch (err) {
+    return {
+      ok: false,
+      msg: 'git status failed: ' + (err && err.message || err),
+    };
+  }
+  const dirty = _parseDirtyPaths(porcelain);
+  if (dirty.length === 0) {
+    return { ok: true, msg: 'working tree clean' };
+  }
+
+  const whitelist = _readWhitelist(projectDir);
+  const unmatched = dirty.filter((p) => !_matchesAny(p, whitelist));
+
+  if (unmatched.length === 0) {
+    return {
+      ok: true,
+      msg: 'working tree dirty (' + dirty.length + ' path(s)) but all whitelisted',
+      details: { dirty: dirty.length, whitelisted: dirty.length },
+    };
+  }
+
+  return {
+    ok: false,
+    msg: unmatched.length + ' dirty path(s) outside whitelist',
+    details: {
+      dirty: dirty.length,
+      unmatched,
+      whitelist,
+    },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'warn',
+  run,
+  // Test-only exports
+  _readWhitelist,
+  _parseDirtyPaths,
+  _globToRegex,
+  _matchesAny,
+};

package/bin/cli-preflight.cjs

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * GSD-T CLI Preflight (M55 D1)
+ *
+ * Pluggable, deterministic, zero-dep state-precondition library + thin CLI.
+ *
+ * Pure inspector — no LLM spawn, no token spend, no side effects beyond reading
+ * the filesystem and running a small fixed list of read-only `git` / `lsof`
+ * commands inside individual checks.
+ *
+ * Contract: .gsd-t/contracts/cli-preflight-contract.md v1.0.0 STABLE.
+ *
+ * Hard rules (mirroring bin/parallelism-report.cjs):
+ *   1. Zero external runtime deps. Only Node built-ins.
+ *   2. Synchronous public API; never throws to the caller.
+ *   3. Per-check throws are caught, recorded, do not abort the run.
+ *   4. Deterministic output — sort `checks[]` by id, sort `notes[]`.
+ *   5. captureSpawn-exempt — see contract § captureSpawn Exemption.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = '1.0.0';
+const CHECKS_DIR_NAME = 'cli-preflight-checks';
+const VALID_SEVERITIES = new Set(['error', 'warn', 'info']);
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {string[]} [opts.checks]   restrict to these check ids (default = all built-ins)
+ * @param {string} [opts.mode='json'] informational; envelope is identical
+ * @returns {{ ok: boolean, schemaVersion: string, checks: object[], notes: string[] }}
+ */
+function runPreflight(opts) {
+  opts = opts || {};
+  const projectDir = opts.projectDir || '.';
+  const restrict = Array.isArray(opts.checks) ? new Set(opts.checks) : null;
+  const notes = [];
+
+  const registry = _loadRegistry(notes);
+
+  const selected = restrict
+    ? registry.filter((c) => restrict.has(c.id))
+    : registry;
+
+  const checkResults = [];
+  for (const check of selected) {
+    const result = _runOneCheck(check, { projectDir }, notes);
+    checkResults.push(result);
+  }
+
+  // Sort checks by id, ascending. Sort notes ascending.
+  checkResults.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  notes.sort();
+
+  const ok = !checkResults.some((c) => c.ok === false && c.severity === 'error');
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    ok,
+    checks: checkResults,
+    notes,
+  };
+}
+
+/**
+ * Render an envelope as a human-readable text summary.
+ * @param {object} envelope
+ * @returns {string}
+ */
+function renderText(envelope) {
+  const lines = [];
+  const status = envelope.ok ? 'OK' : 'FAIL';
+  lines.push('cli-preflight: ' + status + ' (schema v' + envelope.schemaVersion + ')');
+  lines.push('');
+  for (const c of envelope.checks) {
+    const icon = c.ok ? '✓' : (c.severity === 'error' ? '✗' : '!');
+    lines.push('  ' + icon + ' [' + c.severity.padEnd(5) + '] ' + c.id + ' — ' + c.msg);
+  }
+  if (envelope.notes && envelope.notes.length) {
+    lines.push('');
+    lines.push('Notes:');
+    for (const n of envelope.notes) lines.push('  - ' + n);
+  }
+  return lines.join('\n');
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+function _loadRegistry(notes) {
+  const dir = path.join(__dirname, CHECKS_DIR_NAME);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (err) {
+    notes.push('registry: checks dir unreadable (' + (err && err.message || err) + ')');
+    return [];
+  }
+
+  const checks = [];
+  for (const filename of entries) {
+    if (!filename.endsWith('.cjs')) continue;
+    const full = path.join(dir, filename);
+    let mod;
+    try {
+      mod = require(full);
+    } catch (err) {
+      notes.push('registry: ' + filename + ' load failed (' + (err && err.message || err) + ')');
+      continue;
+    }
+    if (!_isValidCheckModule(mod, filename)) {
+      notes.push('registry: ' + filename + ' malformed');
+      continue;
+    }
+    checks.push(mod);
+  }
+  // Sort registry deterministically too — order of execution doesn't affect
+  // output (results are sorted again before return) but stable order makes
+  // notes ordering predictable.
+  checks.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return checks;
+}
+
+function _isValidCheckModule(mod, filename) {
+  if (!mod || typeof mod !== 'object') return false;
+  if (typeof mod.id !== 'string' || !mod.id.length) return false;
+  if (!VALID_SEVERITIES.has(mod.severity)) return false;
+  if (typeof mod.run !== 'function') return false;
+  // Filename stem must match id, so a directory scan = a stable id namespace.
+  const stem = filename.replace(/\.cjs$/, '');
+  if (stem !== mod.id) return false;
+  return true;
+}
+
+function _runOneCheck(check, ctx, notes) {
+  let raw;
+  try {
+    raw = check.run(ctx);
+  } catch (err) {
+    const msg = 'check threw: ' + (err && err.message || String(err));
+    notes.push(check.id + ': ' + msg);
+    return {
+      id: check.id,
+      ok: false,
+      severity: check.severity,
+      msg,
+    };
+  }
+
+  if (!raw || typeof raw !== 'object' || typeof raw.ok !== 'boolean') {
+    const msg = 'check returned invalid shape';
+    notes.push(check.id + ': ' + msg);
+    return {
+      id: check.id,
+      ok: false,
+      severity: check.severity,
+      msg,
+    };
+  }
+
+  const out = {
+    id: check.id,
+    ok: raw.ok,
+    severity: check.severity,
+    msg: typeof raw.msg === 'string' ? raw.msg : '',
+  };
+  if (raw.details && typeof raw.details === 'object' && Object.keys(raw.details).length > 0) {
+    out.details = raw.details;
+  }
+  return out;
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+function _parseArgv(argv) {
+  const out = { projectDir: '.', mode: 'json', skip: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') {
+      out.projectDir = argv[++i] || '.';
+    } else if (a === '--json') {
+      out.mode = 'json';
+    } else if (a === '--text') {
+      out.mode = 'text';
+    } else if (a === '--skip') {
+      const list = argv[++i] || '';
+      out.skip = list.split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (a === '--help' || a === '-h') {
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function _printHelp() {
+  const lines = [
+    'Usage: node bin/cli-preflight.cjs [options]',
+    '',
+    'Options:',
+    '  --project DIR     Project root (default: .)',
+    '  --json            Print JSON envelope (default)',
+    '  --text            Print human-readable summary',
+    '  --skip id1,id2    Skip listed checks (each appends a note)',
+    '  --help            Show this help',
+    '',
+    'Exit codes:',
+    '  0  preflight ok',
+    '  4  preflight failed (>=1 error-severity check failed)',
+  ];
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+function _runCli(argv) {
+  const args = _parseArgv(argv);
+  if (args.help) {
+    _printHelp();
+    return 0;
+  }
+
+  // Build initial registry to know what's available, then filter via --skip.
+  const noteSink = [];
+  const registry = _loadRegistry(noteSink);
+  const allIds = registry.map((c) => c.id);
+  const skipSet = new Set(args.skip);
+  const selected = allIds.filter((id) => !skipSet.has(id));
+
+  const envelope = runPreflight({
+    projectDir: args.projectDir,
+    checks: selected,
+    mode: args.mode,
+  });
+
+  // Append `--skip` notes deterministically.
+  for (const id of args.skip) {
+    envelope.notes.push('skipped: ' + id);
+  }
+  envelope.notes.sort();
+
+  if (args.mode === 'text') {
+    process.stdout.write(renderText(envelope) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+  }
+  return envelope.ok ? 0 : 4;
+}
+
+if (require.main === module) {
+  const code = _runCli(process.argv.slice(2));
+  process.exit(code);
+}
+
+module.exports = {
+  runPreflight,
+  renderText,
+  SCHEMA_VERSION,
+  // Exposed for unit tests only; not part of the public contract.
+  _loadRegistry,
+  _isValidCheckModule,
+  _runOneCheck,
+  _parseArgv,
+};

package/bin/gsd-t-context-brief-kinds/design-verify.cjs

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * design-verify kind collector — points the Design Verification subagent
+ * at its design contract path(s), extracts Figma URL(s), and surfaces
+ * any screenshot manifest.
+ *
+ * Fail-CLOSED: requires at least one of:
+ *   - `.gsd-t/contracts/design-contract.md` (flat)
+ *   - `.gsd-t/contracts/design/INDEX.md` (hierarchical)
+ *
+ * The library enforces fail-closed via the FAIL_CLOSED_KINDS rule:
+ * if NEITHER required source is present, generateBrief raises
+ * EREQUIRED_MISSING. To express the OR-of-required-sources, the
+ * collector itself emits the structured error during `collect`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'design-verify';
+const FLAT_CONTRACT = '.gsd-t/contracts/design-contract.md';
+const HIER_INDEX = '.gsd-t/contracts/design/INDEX.md';
+const SCREENSHOT_MANIFEST = '.gsd-t/screenshots/manifest.json';
+
+function _readMaybe(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
+}
+
+function _figmaUrls(text) {
+  if (!text) return [];
+  const re = /https?:\/\/(?:www\.)?figma\.com\/[A-Za-z0-9_./?#=&%-]+/g;
+  const out = [];
+  const seen = new Set();
+  let m;
+  while ((m = re.exec(text)) != null) {
+    const u = m[0].replace(/[).,;]+$/, '');
+    if (seen.has(u)) continue;
+    seen.add(u);
+    out.push(u);
+  }
+  return out;
+}
+
+function _designContractsList(projectDir, recordSource) {
+  const out = [];
+  // Flat: design-contract*.md at top of contracts/
+  const contractsDir = path.join(projectDir, '.gsd-t', 'contracts');
+  let entries;
+  try { entries = fs.readdirSync(contractsDir); } catch (_) { entries = []; }
+  for (const f of entries) {
+    if (/^design.*\.md$/i.test(f)) {
+      const rel = '.gsd-t/contracts/' + f;
+      out.push(rel);
+      recordSource(rel);
+    }
+  }
+  // Hierarchical: .gsd-t/contracts/design/**/*.md
+  const designDir = path.join(contractsDir, 'design');
+  if (fs.existsSync(designDir)) {
+    const stack = [designDir];
+    while (stack.length) {
+      const cur = stack.pop();
+      let inner;
+      try { inner = fs.readdirSync(cur, { withFileTypes: true }); } catch (_) { continue; }
+      for (const ent of inner) {
+        const full = path.join(cur, ent.name);
+        if (ent.isDirectory()) {
+          stack.push(full);
+        } else if (ent.isFile() && full.endsWith('.md')) {
+          const rel = path.relative(projectDir, full);
+          out.push(rel);
+          recordSource(rel);
+        }
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+
+function collect(ctx) {
+  const { projectDir, recordSource } = ctx;
+
+  // Required-source OR check (library only knows AND-of-required, so we
+  // express the OR rule here).
+  const flatPresent = fs.existsSync(path.join(projectDir, FLAT_CONTRACT));
+  const hierPresent = fs.existsSync(path.join(projectDir, HIER_INDEX));
+  if (!flatPresent && !hierPresent) {
+    const err = new Error('design-verify: no design contract found (' +
+      FLAT_CONTRACT + ' or ' + HIER_INDEX + ')');
+    err.code = 'EREQUIRED_MISSING';
+    err.missing = [FLAT_CONTRACT, HIER_INDEX];
+    throw err;
+  }
+
+  const designPaths = _designContractsList(projectDir, recordSource);
+
+  // Pull all Figma URLs across every located design contract.
+  const figmaUrls = [];
+  const seen = new Set();
+  for (const rel of designPaths) {
+    const text = _readMaybe(path.join(projectDir, rel));
+    if (!text) continue;
+    for (const u of _figmaUrls(text)) {
+      if (seen.has(u)) continue;
+      seen.add(u);
+      figmaUrls.push(u);
+    }
+  }
+  figmaUrls.sort();
+
+  let screenshotManifest = null;
+  if (fs.existsSync(path.join(projectDir, SCREENSHOT_MANIFEST))) {
+    screenshotManifest = SCREENSHOT_MANIFEST;
+    recordSource(SCREENSHOT_MANIFEST);
+  }
+
+  return {
+    scope: { owned: [], notOwned: [], deliverables: [] },
+    constraints: [],
+    contracts: designPaths.map((p) => ({ path: p, status: 'UNKNOWN' })),
+    ancillary: {
+      designContractPaths: designPaths,
+      figmaUrls,
+      screenshotManifest,
+    },
+  };
+}
+
+module.exports = {
+  name: NAME,
+  // Library treats requiresSources as AND. design-verify uses the OR-of-two
+  // pattern instead, raising EREQUIRED_MISSING from inside collect().
+  requiresSources: [],
+  collect,
+  _figmaUrls,
+  _designContractsList,
+};