@jokerized/getresearchdone 0.4.1

package/lib/commands/quality.ts

@@ -0,0 +1,138 @@
+'use strict';
+
+/** GRD Commands/Quality -- Quality analysis and plugin setup operations */
+
+
+const fs = require('fs');
+const path = require('path');
+const {
+  output,
+  error,
+}: {
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+} = require('../utils');
+const {
+  runQualityAnalysis,
+}: {
+  runQualityAnalysis: (cwd: string, phaseNum: string) => QualityReport;
+} = require('../cleanup');
+
+// ─── Domain Types ────────────────────────────────────────────────────────────
+
+interface ComplexityViolation {
+  file: string;
+  line: number;
+  functionName: string;
+  complexity: number;
+}
+interface DeadExportViolation {
+  file: string;
+  exportName: string;
+}
+interface FileSizeViolation {
+  file: string;
+  lines: number;
+  threshold: number;
+}
+interface QualityReport {
+  skipped?: boolean;
+  reason?: string;
+  phase?: string;
+  timestamp?: string;
+  summary?: {
+    total_issues: number;
+    complexity_violations: number;
+    dead_exports: number;
+    oversized_files: number;
+  };
+  details?: {
+    complexity: ComplexityViolation[];
+    dead_exports: DeadExportViolation[];
+    file_size: FileSizeViolation[];
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Extract --flag value from args array. */
+function flag(args: string[], name: string, fallback?: string): string | undefined {
+  const i = args.indexOf(name);
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : fallback;
+}
+
+// ─── Quality Analysis ────────────────────────────────────────────────────────
+
+/** Run quality analysis for a phase. */
+function cmdQualityAnalysis(cwd: string, args: string[], raw: boolean): void {
+  const phaseNum = flag(args, '--phase');
+  if (!phaseNum) {
+    error(
+      '--phase flag required for quality-analysis. Usage: quality-analysis --phase <phase-number>. Add the --phase flag, e.g.: quality-analysis --phase 2'
+    );
+    return;
+  }
+  const report = runQualityAnalysis(cwd, phaseNum);
+  if (report.skipped) {
+    output(report, raw, report.reason);
+    return;
+  }
+
+  const lines: string[] = [
+    `Quality Analysis - Phase ${report.phase}`,
+    `Date: ${report.timestamp}`,
+    '',
+    `Total issues: ${report.summary?.total_issues}`,
+    `  Complexity violations: ${report.summary?.complexity_violations}`,
+    `  Dead exports: ${report.summary?.dead_exports}`,
+    `  Oversized files: ${report.summary?.oversized_files}`,
+  ];
+  if (report.details?.complexity && report.details.complexity.length > 0) {
+    lines.push('', 'Complexity Violations:');
+    for (const v of report.details.complexity)
+      lines.push(`  ${v.file}:${v.line} - ${v.functionName} (complexity: ${v.complexity})`);
+  }
+  if (report.details?.dead_exports && report.details.dead_exports.length > 0) {
+    lines.push('', 'Dead Exports:');
+    for (const v of report.details.dead_exports) lines.push(`  ${v.file} - ${v.exportName}`);
+  }
+  if (report.details?.file_size && report.details.file_size.length > 0) {
+    lines.push('', 'Oversized Files:');
+    for (const v of report.details.file_size)
+      lines.push(`  ${v.file} - ${v.lines} lines (threshold: ${v.threshold})`);
+  }
+  output(report, raw, lines.join('\n'));
+}
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+/** Output plugin configuration info for registering GRD as a Claude Code plugin. */
+function cmdSetup(_cwd: string, raw: boolean): void {
+  const packageRoot: string = path.resolve(__dirname, '..', '..');
+  const pluginJsonPath: string = path.join(packageRoot, '.claude-plugin', 'plugin.json');
+
+  if (!fs.existsSync(pluginJsonPath)) {
+    error('GRD installation not found. Run this command from a valid GRD installation.');
+    return;
+  }
+
+  const pluginDir: string = path.join(packageRoot, '.claude-plugin');
+  const result = {
+    package_root: packageRoot,
+    plugin_json: pluginJsonPath,
+    instructions: `Add to Claude Code settings:\n  "plugin_path": "${pluginDir}"`,
+  };
+  const rawText = [
+    'GRD plugin configured.',
+    `Package root: ${packageRoot}`,
+    `Plugin config: ${pluginJsonPath}`,
+    '',
+    'To use with Claude Code, add this plugin path to your Claude Code configuration:',
+    `  ${pluginDir}`,
+  ].join('\n');
+  output(result, raw, rawText);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = { cmdQualityAnalysis, cmdSetup };

package/lib/commands/rollback.ts

@@ -0,0 +1,195 @@
+'use strict';
+
+/** GRD Commands/Rollback -- Generate phase undo plan from git history */
+
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  output,
+  error,
+  execGit,
+}: {
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+  execGit: (cwd: string, args: string[], opts?: { allowBlocked?: boolean }) => { stdout: string; exitCode: number };
+} = require('../utils');
+const {
+  planningDir: getPlanningDir,
+}: {
+  planningDir: (cwd: string) => string;
+} = require('../paths');
+
+// ─── Domain Types ────────────────────────────────────────────────────────────
+
+interface RollbackResult {
+  phase: string;
+  branch: string;
+  merge_sha: string | null;
+  revert_commands: string[];
+  rollback_plan_path: string | null;
+  note: string;
+}
+
+// ─── Rollback ────────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Generate a safe undo plan for a completed phase.
+ *
+ * Reads git log for the branch named `grd/phase-{N}`, finds the merge commit SHA,
+ * generates `git revert` commands, and writes a step-by-step undo plan to
+ * `.planning/rollback-plan.md`. Optionally updates phase status to `rolled-back`.
+ * Never executes any git operations — output only.
+ *
+ * @param cwd - Project working directory
+ * @param phase - Phase number (e.g., "3" or "03")
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdRollback(cwd: string, phase: string, raw: boolean): void {
+  if (!phase) {
+    error('phase required. Usage: gd rollback <phase>');
+    return;
+  }
+
+  // Codex r10 P2: derive the branch name from the configured
+  // phase_branch_template (default `grd/{milestone}/{phase}-{slug}`).
+  // The legacy hardcoded `grd/phase-${phase}` matched nothing in
+  // current projects.
+  const { loadConfig } = require('../utils') as {
+    loadConfig: (cwd: string) => { phase_branch_template?: string };
+  };
+  const { findPhaseInternal } = require('../utils') as {
+    findPhaseInternal: (
+      cwd: string,
+      phase: string
+    ) => { found: boolean; phase_number?: string; phase_slug?: string | null } | null;
+  };
+  const { currentMilestone: currentMilestoneFn } = require('../paths') as {
+    currentMilestone: (cwd: string) => string;
+  };
+  const cfg = loadConfig(cwd);
+  const template = cfg.phase_branch_template || 'grd/{milestone}/{phase}-{slug}';
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  let ms = '';
+  try {
+    ms = currentMilestoneFn(cwd);
+  } catch {
+    /* milestone may not be set; template can still fill phase */
+  }
+  const slug = phaseInfo?.phase_slug ?? '';
+  const phaseNum = phaseInfo?.phase_number ?? phase;
+  const branchName = template
+    .replace('{milestone}', ms)
+    .replace('{phase}', phaseNum)
+    .replace('{slug}', slug)
+    .replace(/\/+/g, '/')
+    .replace(/-+$/, '');
+
+  // Find merge commit for the phase branch
+  const logResult = execGit(cwd, [
+    'log',
+    '--oneline',
+    '--merges',
+    '--all',
+    `--grep=Merge.*${branchName}`,
+    '-10',
+  ], { allowBlocked: true });
+
+  let mergeSha: string | null = null;
+  let isConfirmedMerge = false;
+  if (logResult.exitCode === 0 && logResult.stdout.trim()) {
+    const firstLine = logResult.stdout.trim().split('\n')[0];
+    mergeSha = firstLine.split(' ')[0] || null;
+    if (mergeSha) isConfirmedMerge = true;
+  }
+
+  // Fallback: look for branch tip SHA. Not necessarily a merge commit.
+  if (!mergeSha) {
+    const branchResult = execGit(cwd, ['rev-parse', '--verify', `${branchName}`], { allowBlocked: true });
+    if (branchResult.exitCode === 0 && branchResult.stdout.trim()) {
+      mergeSha = branchResult.stdout.trim();
+    }
+  }
+
+  // Codex r6 P2: `git revert -m 1 <sha>` already creates the revert
+  // commit (no --no-commit), so the prior `git commit --no-edit` would
+  // fail with "nothing to commit". Also, `-m 1` is invalid for
+  // non-merge commits, so the branch-tip fallback path needs a
+  // different command shape.
+  const revertCommands: string[] = [];
+  if (mergeSha && isConfirmedMerge) {
+    revertCommands.push(
+      `git revert -m 1 --no-edit ${mergeSha}  # Revert merge of ${branchName}`
+    );
+  } else if (mergeSha) {
+    revertCommands.push(
+      `# Branch tip ${mergeSha} may not be a merge commit. If it is, add \`-m 1\`:`
+    );
+    revertCommands.push(
+      `git revert --no-edit ${mergeSha}  # Revert tip of ${branchName}`
+    );
+  } else {
+    revertCommands.push(`# Could not locate merge commit for ${branchName}`);
+    revertCommands.push(`# Manual steps: git log --oneline --merges --all | grep "${branchName}"`);
+    revertCommands.push(`# Then: git revert -m 1 --no-edit <sha>`);
+  }
+
+  // Write rollback plan to .planning/rollback-plan.md
+  const planningDir = getPlanningDir(cwd);
+  const rollbackPlanPath = path.join(planningDir, 'rollback-plan.md');
+  let writtenPath: string | null = null;
+
+  const today = new Date().toISOString().split('T')[0];
+  const planContent = [
+    `# Rollback Plan — Phase ${phase}`,
+    ``,
+    `Generated: ${today}`,
+    `Branch: \`${branchName}\``,
+    `Merge SHA: ${mergeSha ?? '(not found — see manual steps below)'}`,
+    ``,
+    `## Steps`,
+    ``,
+    `1. Ensure your working tree is clean: \`git status\``,
+    `2. Switch to the integration branch: \`git checkout main\` (or your base branch)`,
+    `3. Run the revert commands below:`,
+    ``,
+    revertCommands.map((c) => `   \`\`\`\n   ${c}\n   \`\`\``).join('\n'),
+    ``,
+    `4. Verify tests pass: \`npm test\``,
+    `5. Update STATE.md phase ${phase} status to \`rolled-back\``,
+    ``,
+    `## Notes`,
+    ``,
+    `- This plan was generated automatically and does not execute any git operations.`,
+    `- Always review the revert diff before committing.`,
+    `- If the merge SHA is missing, locate it with: \`git log --oneline --merges --all\``,
+  ].join('\n');
+
+  try {
+    fs.mkdirSync(planningDir, { recursive: true });
+    fs.writeFileSync(rollbackPlanPath, planContent, 'utf-8');
+    writtenPath = path.relative(cwd, rollbackPlanPath);
+  } catch {
+    // Non-fatal — output result anyway
+  }
+
+  const result: RollbackResult = {
+    phase,
+    branch: branchName,
+    merge_sha: mergeSha,
+    revert_commands: revertCommands,
+    rollback_plan_path: writtenPath,
+    note: 'No git operations were executed. Review the plan before running revert commands.',
+  };
+
+  const summary = mergeSha
+    ? `Rollback plan for phase ${phase}: revert ${mergeSha}`
+    : `Rollback plan for phase ${phase}: merge SHA not found — manual steps generated`;
+
+  output(result, raw, summary);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = { cmdRollback };

package/lib/commands/scan.ts

@@ -0,0 +1,72 @@
+"use strict";
+
+/**
+ * GRD Commands/Scan -- Orchestrator for the prompt injection scanner.
+ *
+ * Composes lib/scan/injection and lib/scan/base64, loads the ignorefile,
+ * and produces a structured ScanReport. Does not touch process.exit or
+ * output formatting — the CLI dispatch layer handles that.
+ */
+
+import type { ScanHit } from "../scan/types";
+import type { IgnoreEntry } from "../scan/ignorefile";
+
+const { scanProse } = require("../scan/injection") as {
+  scanProse: (
+    files: string[],
+    opts: { ignoreEntries: IgnoreEntry[] },
+  ) => ScanHit[];
+};
+const { scanBase64 } = require("../scan/base64") as {
+  scanBase64: (
+    files: string[],
+    opts: { ignoreEntries: IgnoreEntry[] },
+  ) => ScanHit[];
+};
+const { loadIgnoreFile } = require("../scan/ignorefile") as {
+  loadIgnoreFile: (filePath: string) => IgnoreEntry[];
+};
+
+export type ScanMode = "staged" | "diff" | "file" | "all";
+
+export interface ScanReport {
+  version: 1;
+  mode: ScanMode;
+  scanned: number;
+  hits: ScanHit[];
+  exitCode: 0 | 1;
+}
+
+export interface RunScanOpts {
+  mode: ScanMode;
+  files: string[];
+  ignoreFilePath: string | null;
+  injectionOnly: boolean;
+  base64Only: boolean;
+}
+
+export function runScan(opts: RunScanOpts): ScanReport {
+  const { mode, files, ignoreFilePath, injectionOnly, base64Only } = opts;
+  const ignoreEntries = ignoreFilePath ? loadIgnoreFile(ignoreFilePath) : [];
+
+  const hits: ScanHit[] = [];
+  if (!base64Only) {
+    hits.push(...scanProse(files, { ignoreEntries }));
+  }
+  if (!injectionOnly) {
+    hits.push(...scanBase64(files, { ignoreEntries }));
+  }
+
+  const unignoredCount = hits.filter((h) => !h.ignored).length;
+  const exitCode: 0 | 1 = unignoredCount > 0 ? 1 : 0;
+
+  return {
+    version: 1,
+    mode,
+    scanned: files.length,
+    hits,
+    exitCode,
+  };
+}
+
+module.exports = { runScan };

package/lib/commands/search.ts

@@ -0,0 +1,300 @@
+'use strict';
+
+/** GRD Commands/Search -- Search, migration, and coverage report operations */
+
+
+const fs = require('fs');
+const path = require('path');
+const child_process = require('child_process');
+
+const {
+  safeReadFile,
+  loadConfig,
+  output,
+  error,
+}: {
+  safeReadFile: (p: string) => string | null;
+  loadConfig: (cwd: string) => Record<string, unknown> & { timeouts: Record<string, number> };
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+} = require('../utils');
+const {
+  currentMilestone,
+  planningDir: getPlanningDir,
+}: {
+  currentMilestone: (cwd: string) => string;
+  planningDir: (cwd: string) => string;
+} = require('../paths');
+
+// ─── Domain Types ────────────────────────────────────────────────────────────
+
+interface SearchMatch {
+  file: string;
+  line: number;
+  content: string;
+}
+
+interface MigrationEntry {
+  from: string;
+  to: string;
+  entries_to_move?: number;
+  entries_moved?: number;
+}
+
+interface MigrationError {
+  entry: string;
+  item: string;
+  error: string;
+}
+
+interface CoverageEntry {
+  module: string;
+  lines: number;
+  branches: number;
+  functions: number;
+  statements: number;
+}
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+/** Recursively collect all .md files under a directory. */
+function collectMarkdownFiles(dir: string): string[] {
+  const results: string[] = [];
+  try {
+    const entries: { isDirectory: () => boolean; isFile: () => boolean; name: string }[] =
+      fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectMarkdownFiles(fullPath));
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+    /* Directory doesn't exist or can't be read */
+  }
+  return results;
+}
+
+// ─── CLI: Search ─────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Search across all .planning/ markdown files for a text query.
+ * Returns file paths, line numbers, and matching lines.
+ */
+function cmdSearch(cwd: string, query: string, raw: boolean): void {
+  if (!query) {
+    error('Search query is required');
+    return;
+  }
+
+  const planningDir = getPlanningDir(cwd) as string;
+  const mdFiles = collectMarkdownFiles(planningDir);
+  const matches: SearchMatch[] = [];
+  const queryLower = query.toLowerCase();
+
+  for (const filePath of mdFiles) {
+    const content = safeReadFile(filePath);
+    if (!content) continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].toLowerCase().includes(queryLower)) {
+        matches.push({
+          file: path.relative(planningDir, filePath),
+          line: i + 1,
+          content: lines[i],
+        });
+      }
+    }
+  }
+
+  output({ matches, count: matches.length, query }, raw);
+}
+
+// ─── CLI: Migrate Dirs ──────────────────────────────────────────────────────
+
+/**
+ * CLI command: Migrate old-style flat .planning/ subdirectories to the
+ * milestone-scoped hierarchy under .planning/milestones/{milestone}/.
+ * Idempotent: running twice produces no changes on the second run.
+ */
+function cmdMigrateDirs(cwd: string, raw: boolean, dryRun?: boolean): void {
+  const milestone = currentMilestone(cwd);
+  const planningDir = getPlanningDir(cwd) as string;
+
+  const migrationMap = [
+    { name: 'phases', target: milestone },
+    { name: 'research', target: milestone },
+    { name: 'todos', target: milestone },
+    { name: 'quick', target: milestone },
+  ];
+
+  const movedDirectories: MigrationEntry[] = [];
+  const skipped: string[] = [];
+  const errors: MigrationError[] = [];
+
+  for (const entry of migrationMap) {
+    const oldDir = path.join(planningDir, entry.name);
+    if (!fs.existsSync(oldDir)) {
+      skipped.push(entry.name);
+      continue;
+    }
+
+    let contents: string[];
+    try {
+      contents = fs.readdirSync(oldDir);
+    } catch {
+      skipped.push(entry.name);
+      continue;
+    }
+    if (contents.length === 0) {
+      skipped.push(entry.name);
+      continue;
+    }
+
+    const targetDir = path.join(planningDir, 'milestones', entry.target, entry.name);
+
+    if (dryRun) {
+      movedDirectories.push({
+        from: entry.name,
+        to: path.join('milestones', entry.target, entry.name),
+        entries_to_move: contents.filter(
+          (item: string) => !fs.existsSync(path.join(targetDir, item))
+        ).length,
+      });
+      continue;
+    }
+
+    fs.mkdirSync(targetDir, { recursive: true });
+    let entriesMoved = 0;
+
+    for (const item of contents) {
+      const srcPath = path.join(oldDir, item);
+      const destPath = path.join(targetDir, item);
+      if (fs.existsSync(destPath)) continue;
+      try {
+        const srcStats = fs.statSync(srcPath);
+        if (srcStats.isDirectory()) {
+          fs.cpSync(srcPath, destPath, { recursive: true });
+        } else {
+          fs.cpSync(srcPath, destPath);
+        }
+        fs.rmSync(srcPath, { recursive: true, force: true });
+        entriesMoved++;
+      } catch (err: unknown) {
+        errors.push({ entry: entry.name, item, error: (err as Error).message });
+      }
+    }
+
+    if (entriesMoved > 0) {
+      movedDirectories.push({
+        from: entry.name,
+        to: path.join('milestones', entry.target, entry.name),
+        entries_moved: entriesMoved,
+      });
+    }
+  }
+
+  const alreadyMigrated = movedDirectories.length === 0;
+  const result = {
+    milestone,
+    moved_directories: movedDirectories,
+    skipped,
+    already_migrated: alreadyMigrated,
+    errors,
+    ...(dryRun ? { dry_run: true } : {}),
+  };
+  output(
+    result,
+    raw,
+    dryRun
+      ? `dry-run: would migrate ${movedDirectories.length} directory(ies)`
+      : JSON.stringify(result)
+  );
+}
+
+// ─── CLI: Coverage Report ───────────────────────────────────────────────────
+
+/**
+ * CLI command: Generate a structured coverage report identifying modules below threshold.
+ * Runs jest with json-summary reporter and parses the output.
+ */
+function cmdCoverageReport(cwd: string, options: { threshold?: number }, raw: boolean): void {
+  const threshold = options.threshold || 85;
+  const config = loadConfig(cwd);
+
+  const summaryPath = path.join(cwd, 'coverage', 'coverage-summary.json');
+  let coverageData: Record<
+    string,
+    {
+      lines: { pct: number };
+      branches: { pct: number };
+      functions: { pct: number };
+      statements: { pct: number };
+    }
+  >;
+  let summaryContent: string | undefined;
+  try {
+    child_process.execFileSync(
+      'npx',
+      ['jest', '--coverage', '--coverageReporters=json-summary', '--silent', '--forceExit'],
+      { cwd, encoding: 'utf-8', timeout: config.timeouts.jest_ms, stdio: 'pipe' }
+    );
+    summaryContent = fs.readFileSync(summaryPath, 'utf-8') as string;
+    coverageData = JSON.parse(summaryContent);
+  } catch (_e: unknown) {
+    if (fs.existsSync(summaryPath)) {
+      summaryContent = summaryContent || (fs.readFileSync(summaryPath, 'utf-8') as string);
+      coverageData = JSON.parse(summaryContent);
+    } else {
+      output({ error: 'Failed to generate coverage report', details: (_e as Error).message }, raw);
+      return;
+    }
+  }
+
+  const modules: CoverageEntry[] = [];
+  const belowThreshold: (CoverageEntry & { gap: number })[] = [];
+
+  for (const [filePath, data] of Object.entries(coverageData)) {
+    if (filePath === 'total') continue;
+    const relativePath = path.relative(cwd, filePath);
+    if (!relativePath.startsWith('lib/')) continue;
+
+    const entry: CoverageEntry = {
+      module: relativePath,
+      lines: data.lines.pct,
+      branches: data.branches.pct,
+      functions: data.functions.pct,
+      statements: data.statements.pct,
+    };
+    modules.push(entry);
+
+    if (data.lines.pct < threshold) {
+      belowThreshold.push({ ...entry, gap: +(threshold - data.lines.pct).toFixed(1) });
+    }
+  }
+
+  modules.sort((a, b) => a.lines - b.lines);
+  belowThreshold.sort((a, b) => a.lines - b.lines);
+
+  output(
+    {
+      threshold,
+      total_modules: modules.length,
+      below_threshold_count: belowThreshold.length,
+      all_above: belowThreshold.length === 0,
+      below_threshold: belowThreshold,
+      modules,
+    },
+    raw
+  );
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  cmdSearch,
+  cmdMigrateDirs,
+  cmdCoverageReport,
+};