@hegemonart/get-design-done 1.28.8 → 1.30.0

package/scripts/lib/issue-reporter/cli-flag-report.cjs

@@ -0,0 +1,153 @@
+'use strict';
+/**
+ * cli-flag-report.cjs — Plan 30-04 D-11 `--report` flag plumbing.
+ *
+ * The `--report` flag is intentionally NOT available on every command.
+ * Per D-11 it is whitelisted to specific failure modes catalogued in
+ * `reference/known-failure-modes.md` with `propose_report: true`. The
+ * matcher (30-03) does not act on this flag; this module is where it
+ * gates which commands get the flag at all.
+ *
+ * The schema for known-failure-modes.md does NOT include a per-mode
+ * `command` field — the catalogue is regex-based, not command-keyed.
+ * The whitelist therefore lives here as an explicit set of command
+ * names whose plausible failures map to one or more propose_report=true
+ * entries. Adding a command to the whitelist is a deliberate maintainer
+ * choice; we do not auto-derive it to avoid surprising users with new
+ * `--report` flags appearing as the catalogue grows.
+ *
+ * Today (matching KFM-008 MCP unreachable + KFM-009 plugin file missing):
+ *   - `gdd:plan-phase`  — typically the first MCP-touching command
+ *   - `gdd:execute-phase` — typically the first plugin-file-touching command
+ *   - `gdd:report-issue` — the flag is meaningful on itself (force flow)
+ *
+ * Commands NOT on the whitelist silently do not see the flag —
+ * non-whitelisted argv parsing returns `{ report: false }` regardless
+ * of whether the user typed --report.
+ */
+
+const { listProposeReportModes } = require('./triage-matcher.cjs');
+
+/**
+ * Command whitelist — derived from CONTEXT D-11 + KFM-008/KFM-009 modes.
+ * Frozen to prevent accidental mutation at runtime.
+ *
+ * The intersection with listProposeReportModes() is checked at
+ * isReportFlagWhitelisted call time: if the catalogue is missing
+ * propose_report=true entries entirely, the flag is unavailable
+ * everywhere (defensive default).
+ */
+const COMMAND_WHITELIST = Object.freeze(new Set([
+  'gdd:plan-phase',
+  'gdd:execute-phase',
+  'gdd:report-issue',
+]));
+
+/**
+ * @param {string} commandName
+ * @param {{ listFn?: typeof listProposeReportModes }} [opts]
+ * @returns {boolean}
+ */
+function isReportFlagWhitelisted(commandName, opts) {
+  if (typeof commandName !== 'string' || commandName.length === 0) return false;
+  if (!COMMAND_WHITELIST.has(commandName)) return false;
+  const listFn = (opts && opts.listFn) || listProposeReportModes;
+  let modes;
+  try {
+    modes = listFn();
+  } catch {
+    modes = [];
+  }
+  // Defensive: if the catalogue lost all propose_report=true entries,
+  // the flag is unavailable everywhere.
+  return Array.isArray(modes) && modes.length > 0;
+}
+
+/**
+ * Install --report on the given command-line parser ONLY if the command
+ * is whitelisted. The function adapts to two parser shapes:
+ *
+ *   yargs-style: parser.option('report', { type: 'boolean', describe: ... })
+ *   commander-style: parser.option('--report', '...', false)
+ *
+ * Non-whitelisted commands → no-op. Returns true if the flag was
+ * installed, false otherwise.
+ *
+ * @param {object} parser
+ * @param {string} commandName
+ * @param {{ listFn?: typeof listProposeReportModes }} [opts]
+ * @returns {boolean}
+ */
+function installReportFlagOn(parser, commandName, opts) {
+  if (!isReportFlagWhitelisted(commandName, opts)) {
+    return false;
+  }
+  if (parser == null) return false;
+  // Try yargs-style first (named option with a config object).
+  if (typeof parser.option === 'function') {
+    try {
+      parser.option('report', {
+        type: 'boolean',
+        default: false,
+        describe:
+          'Propose a GitHub issue draft after a failure (D-11 whitelisted; consent required — no auto-submit).',
+      });
+      return true;
+    } catch {
+      // fall through to commander-style
+    }
+    try {
+      parser.option(
+        '--report',
+        'Propose a GitHub issue draft after a failure (D-11 whitelisted; consent required — no auto-submit).',
+        false
+      );
+      return true;
+    } catch {
+      // fall through
+    }
+  }
+  return false;
+}
+
+/**
+ * Parse `--report` out of an argv array.
+ *
+ * Cheap parser used by tests and by any caller that just wants to know
+ * whether the flag was passed. Non-whitelisted commands ALWAYS return
+ * `false` regardless of what's in argv — the flag is unavailable to them.
+ *
+ * @param {string} commandName
+ * @param {string[]} argv
+ * @param {{ listFn?: typeof listProposeReportModes }} [opts]
+ * @returns {{ report: boolean, forceReport: boolean }}
+ */
+function parseReportFlag(commandName, argv, opts) {
+  const whitelisted = isReportFlagWhitelisted(commandName, opts);
+  let report = false;
+  let forceReport = false;
+  if (Array.isArray(argv)) {
+    for (const a of argv) {
+      if (a === '--report') report = true;
+      else if (a === '--force-report') forceReport = true;
+      else if (typeof a === 'string' && a.startsWith('--report=')) {
+        const v = a.slice('--report='.length).toLowerCase();
+        report = v === 'true' || v === '1' || v === 'yes';
+      }
+    }
+  }
+  if (!whitelisted) {
+    // Whitelist gate: even if the user typed --report, the command does
+    // not expose it. Force-report is independent: it's a global modifier
+    // for the explicit /gdd:report-issue command path.
+    return { report: false, forceReport: forceReport && commandName === 'gdd:report-issue' };
+  }
+  return { report, forceReport };
+}
+
+module.exports = {
+  installReportFlagOn,
+  isReportFlagWhitelisted,
+  parseReportFlag,
+  COMMAND_WHITELIST,
+};

package/scripts/lib/issue-reporter/consent-prompt.cjs

@@ -0,0 +1,231 @@
+'use strict';
+/**
+ * consent-prompt.cjs — Plan 30-04 D-03 consent gate.
+ *
+ * The ONE place where the user explicitly says "yes" before /gdd:report-issue
+ * submits anything. There is no auto-mode and no env-var bypass:
+ *
+ *   - Refuses (throws) if stdin is not a TTY (no piped 'y' from CI, no
+ *     non-interactive shells).
+ *   - Refuses (throws) if any process.env key matches /REPORT|ISSUE|AUTO_REPORT/i
+ *     AND has a truthy value (runtime belt + suspenders for the static test
+ *     in tests/report-issue-no-auto-submit-static.test.cjs).
+ *   - Treats any answer other than literal `y`/`yes` (case-insensitive) as
+ *     decline.
+ *
+ * After (optionally) opening the user's $EDITOR on the draft, RE-READS the
+ * draft from disk and returns the re-read title + body. This is what makes
+ * "edit before submit" work: the editor exit handler does not bind the
+ * content; the content is freshly loaded from the file path on every entry.
+ *
+ * EDITOR is a POSIX-standard user env (used by git, crontab, gh itself). It
+ * is intentionally NOT in the forbidden list — the static test only blocks
+ * names matching /REPORT|ISSUE|AUTO_REPORT/i.
+ *
+ * Pure dependencies: readline, child_process.spawnSync. No `fetch`, no
+ * `https`, no third-party packages.
+ */
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+const { spawnSync } = require('node:child_process');
+
+const { DESTINATION_REPO } = require('./destination.cjs');
+const { readDraft } = require('./draft-writer.cjs');
+
+const FORBIDDEN_ENV_RE = /(REPORT|ISSUE|AUTO_REPORT)/i;
+
+/**
+ * Scan process.env for any auto-submit bypass env var with a truthy value.
+ * If found, throws — D-03 runtime gate counterpart to the static test.
+ *
+ * Implementation note: we iterate Object.keys(process.env) so we can match
+ * substrings (REPORT, ISSUE, AUTO_REPORT). We never directly read a
+ * specific named env var here — that would itself fail the static-grep
+ * test in tests/report-issue-no-auto-submit-static.test.cjs (which only
+ * forbids `process.env.NAME` patterns).
+ *
+ * Truthy means: present, non-empty, not literal "0" / "false" / "no".
+ *
+ * @param {NodeJS.ProcessEnv} [env] — injection point for tests
+ */
+function rejectBypassEnv(env) {
+  const source = env || process.env;
+  const offenders = [];
+  for (const key of Object.keys(source)) {
+    if (!FORBIDDEN_ENV_RE.test(key)) continue;
+    const value = source[key];
+    if (value == null) continue;
+    const s = String(value).trim().toLowerCase();
+    if (s === '' || s === '0' || s === 'false' || s === 'no') continue;
+    offenders.push(key);
+  }
+  if (offenders.length > 0) {
+    throw new Error(
+      `refused: env var ${offenders.join(', ')} detected; /gdd:report-issue has no auto-mode by design (D-03)`
+    );
+  }
+}
+
+/**
+ * Open the user's $EDITOR on the draft file, blocking until it exits.
+ *
+ * @param {string} draftPath
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean} — true if an editor was spawned, false if EDITOR unset
+ */
+function openInEditor(draftPath, env) {
+  const source = env || process.env;
+  const editor = source.EDITOR;
+  if (typeof editor !== 'string' || editor.trim().length === 0) {
+    return false;
+  }
+  // Whole-string command: split on first space for editor + args.
+  const parts = editor.trim().split(/\s+/);
+  const cmd = parts[0];
+  const args = parts.slice(1).concat([draftPath]);
+  spawnSync(cmd, args, { stdio: 'inherit' });
+  return true;
+}
+
+/**
+ * Ask the user the single y/N question via readline. EOF / empty input
+ * counts as decline.
+ *
+ * @param {NodeJS.ReadableStream} input
+ * @param {NodeJS.WritableStream} output
+ * @returns {Promise<string>} — raw answer string
+ */
+function askYesNo(input, output) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output, terminal: false });
+    let answered = false;
+    const finish = (value) => {
+      if (answered) return;
+      answered = true;
+      try { rl.close(); } catch { /* noop */ }
+      resolve(value);
+    };
+    rl.question(
+      `Submit this issue to ${DESTINATION_REPO}? [y/N] `,
+      (answer) => finish(typeof answer === 'string' ? answer.trim() : '')
+    );
+    rl.on('close', () => finish(''));
+  });
+}
+
+function isAffirmative(answer) {
+  if (typeof answer !== 'string') return false;
+  const a = answer.trim().toLowerCase();
+  return a === 'y' || a === 'yes';
+}
+
+/**
+ * Build the human-facing summary printed before the y/N question.
+ *
+ * @param {{ title: string, body: string }} draft
+ * @param {string} draftPath
+ * @returns {string}
+ */
+function buildSummary(draft, draftPath) {
+  const head = String(draft.body || '').split(/\r?\n/).slice(0, 10).join('\n');
+  return [
+    '',
+    '--- /gdd:report-issue draft summary ---',
+    `Destination: ${DESTINATION_REPO}`,
+    `Draft path:  ${draftPath}`,
+    `Title:       ${draft.title}`,
+    'Body (first 10 lines):',
+    head,
+    '---',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The full consent flow.
+ *
+ *   1. Reject bypass env vars (throw).
+ *   2. Reject non-TTY stdin (throw).
+ *   3. (Optional) open $EDITOR on the draft and wait.
+ *   4. Re-read the draft from disk → final {title, body}.
+ *   5. Print summary.
+ *   6. Ask y/N via readline.
+ *   7. Return { consented, finalTitle, finalBody }.
+ *
+ * @param {{
+ *   draftPath: string,
+ *   openEditor?: boolean,
+ *   stdin?: NodeJS.ReadableStream,
+ *   stdout?: NodeJS.WritableStream,
+ *   env?: NodeJS.ProcessEnv,
+ *   askYesNo?: typeof askYesNo,
+ *   openInEditor?: typeof openInEditor
+ * }} opts
+ * @returns {Promise<{ consented: boolean, finalTitle: string, finalBody: string }>}
+ */
+async function promptConsent(opts) {
+  if (opts == null || typeof opts !== 'object') {
+    throw new Error('promptConsent: opts object required');
+  }
+  const draftPath = opts.draftPath;
+  if (typeof draftPath !== 'string' || draftPath.length === 0) {
+    throw new Error('promptConsent: draftPath required');
+  }
+
+  // Step 1: runtime env-var bypass gate (D-03).
+  rejectBypassEnv(opts.env);
+
+  // Step 2: TTY gate (D-03).
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+  // Allow tests to bypass the TTY check by injecting a stream that sets
+  // `isTTY = true` on itself (the public API contract is "interactive
+  // shell"; the underlying mechanism is the isTTY flag).
+  if (!stdin.isTTY) {
+    throw new Error(
+      'refused: /gdd:report-issue requires an interactive TTY (no auto-mode by design — D-03)'
+    );
+  }
+
+  // Step 3: optional editor (skipped if openEditor === false).
+  const editorFn = opts.openInEditor || openInEditor;
+  if (opts.openEditor !== false) {
+    try {
+      editorFn(draftPath, opts.env);
+    } catch {
+      // Editor failures are non-fatal — user can edit manually + still consent.
+    }
+  }
+
+  // Step 4: re-read the (possibly edited) draft. This is the key step
+  // that makes E1 + E2 pass — content is freshly loaded from disk.
+  const draft = readDraft(draftPath);
+
+  // Step 5: summary.
+  try {
+    stdout.write(buildSummary(draft, draftPath));
+  } catch {
+    // Best-effort UI; tests can inject stdout that throws.
+  }
+
+  // Step 6: ask y/N.
+  const ask = opts.askYesNo || askYesNo;
+  const answer = await ask(stdin, stdout);
+  const consented = isAffirmative(answer);
+
+  return {
+    consented,
+    finalTitle: draft.title,
+    finalBody: draft.body,
+  };
+}
+
+module.exports = {
+  promptConsent,
+  rejectBypassEnv,
+  isAffirmative,
+  buildSummary,
+  openInEditor,
+  askYesNo,
+};