@jokerized/getresearchdone 0.4.1

package/bin/gd.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+require('tsx/cjs');
+require('./gd.ts');

package/bin/gd.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+'use strict';
+
+const { join } = require('path') as typeof import('path');
+const { readFileSync, existsSync } = require('fs') as typeof import('fs');
+
+const {
+  parseFlags,
+  classifyCommand,
+}: {
+  parseFlags: (argv: string[]) => {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+    verbose: boolean;
+    cwd?: string;
+    backend?: string;
+    model?: string;
+    positional: string[];
+    passthrough: string[];
+  };
+  classifyCommand: (command: string, subcommand?: string) => 'tool' | 'agent' | 'unknown';
+} = require('../lib/cli/index');
+
+const {
+  runToolCommand,
+}: {
+  runToolCommand: (
+    command: string,
+    subcommand: string | undefined,
+    extraArgs: string[],
+    jsonFlag: boolean,
+    cwd: string,
+    passthrough?: string[]
+  ) => { exitCode: number; stdout: string; stderr: string };
+} = require('../lib/cli/tools');
+
+const {
+  runAgentCommand,
+}: {
+  runAgentCommand: (
+    command: string,
+    args: string[],
+    opts: {
+      cwd: string;
+      backend: string;
+      json: boolean;
+      verbose: boolean;
+      model?: string;
+      timeout?: number;
+    }
+  ) => void;
+} = require('../lib/cli/agent');
+
+const flags = parseFlags(process.argv.slice(2));
+
+// --version
+if (flags.version) {
+  try {
+    // Handle both bin/ (source) and dist/bin/ (compiled) locations
+    let pkgPath = join(__dirname, '..', 'package.json');
+    if (!existsSync(pkgPath)) pkgPath = join(__dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version: string };
+    process.stdout.write(`gd v${pkg.version}\n`);
+  } catch {
+    process.stdout.write('gd (unknown version)\n');
+  }
+  process.exit(0);
+}
+
+const command = flags.positional[0];
+const subcommand = flags.positional[1];
+const extraArgs = flags.positional.slice(2);
+
+// --help with no command, or no command at all
+if (!command || (flags.help && !command)) {
+  printHelp();
+  process.exit(0);
+}
+
+// Per-command --help
+if (flags.help) {
+  printCommandHelp(command);
+  process.exit(0);
+}
+
+const cwd = flags.cwd || process.cwd();
+let classification = classifyCommand(command, subcommand);
+
+// Codex r23 P2: `gd execute-phase <N> --dry-run` should hit the tool
+// dry-run preview, not the agent execute path. Override the agent
+// classification when the user passes --dry-run on an agent command
+// that exposes a tool-side dry-run handler.
+const DRYRUN_TOOL_OVERRIDES = new Set(['execute-phase']);
+if (
+  classification === 'agent' &&
+  DRYRUN_TOOL_OVERRIDES.has(command) &&
+  (extraArgs.includes('--dry-run') || flags.passthrough.includes('--dry-run'))
+) {
+  classification = 'tool';
+}
+
+if (classification === 'tool') {
+  const result = runToolCommand(command, subcommand, extraArgs, flags.json, cwd, flags.passthrough);
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exit(result.exitCode);
+} else if (classification === 'agent') {
+  const { detectBackend }: { detectBackend: (cwd: string) => string } = require('../lib/backend');
+  const backend = flags.backend || detectBackend(cwd);
+  runAgentCommand(command, flags.positional.slice(1), {
+    cwd,
+    backend,
+    json: flags.json,
+    verbose: flags.verbose,
+    model: flags.model,
+  });
+} else {
+  process.stderr.write(`Unknown command: ${command}\nRun "gd --help" for usage.\n`);
+  process.exit(1);
+}
+
+function printHelp(): void {
+  process.stdout.write(`gd — Get Research Done CLI
+
+Usage: gd <command> [args] [--json] [--help] [--version]
+
+Hero verbs (the closed loop):
+  init                 Bootstrap a new R&D project from a template
+  plan-phase <N>       Compose PLAN.md (Ouroboros context auto-injected)
+  execute-phase <N>    Run plans (wave-parallel + worktree-isolated)
+  verify-phase <N>     Reflection-loop verifier with Evidence Standard
+  autopilot            Run N phases end-to-end (the closed loop)
+  evolve               Autonomous self-improvement loop
+  health               Drift score + blockers + Ouroboros status
+  think                One-shot project briefing aggregating all primitives
+  singularity          % of recent LOC authored by gd evolve itself
+
+Workflow:
+  new-milestone        Start a new milestone cycle
+  autoplan             Auto-generate milestones from discoveries
+  progress             Show project progress
+  resume-project       Restore project context
+  pause-work           Save work state for later
+  quick                Execute small ad-hoc tasks
+
+Research:
+  survey <topic>       SoTA landscape scan
+  deep-dive <paper>    Paper deep analysis
+  compare-methods      Compare research methods
+  feasibility <topic>  Paper-to-production gap analysis
+
+Planning:
+  product-plan         Product-level planning
+  discuss-phase <N>    Brainstorm before planning
+  add-phase            Add a new phase
+  insert-phase         Insert phase between existing ones
+  remove-phase         Remove an unstarted phase
+
+Evaluation:
+  assess-baseline      Current performance baseline
+  eval-report <N>      Collect and analyze results
+  iterate <N>          Iteration loop on failed metrics
+  verify-work          Validate features with metrics
+
+Configuration:
+  settings             Configure workflow settings
+  principles           Create/edit project principles
+  discover [area]      Discover codebase standards
+  tracker-setup        Configure issue tracker
+
+Tools (deterministic, fast):
+  state <sub>          State management
+  verify <sub>         Verification suite (incl. \`verify mechanical\`)
+  phase <sub>          Phase lifecycle ops
+  scaffold <sub>       Directory scaffolding
+  frontmatter <sub>    YAML frontmatter CRUD
+  tracker <sub>        Issue tracker sync
+  roadmap <sub>        Roadmap queries
+  init <sub>           Workflow init contexts (internal)
+  version              Print version
+  phases               List all phases
+
+Ouroboros primitives (see docs/ouroboros-loop.md):
+  dead-end <sub>       DEAD-ENDS.md registry CRUD + promote-from-phase
+  genome <sub>         GENOME.md init / show / snapshot
+  plan-tournament      Score candidate PLAN.md files
+  scan                 Prompt-injection scanner
+
+Auxiliary (run \`gd <cmd> --help\` for details):
+  diagnose, blame, budget, impact, freshness, rollback, estimate,
+  estimate-phase, forecast-phase, check-plans, check-assumptions,
+  deps, deps-risk, knowledge, knowhow, eval, tail, watch,
+  research-gaps, import-knowhow, import-knowledge, export-research,
+  import-research, metrics
+
+Note: dashboard, health-check, coverage-report, phase-time-budget,
+todo-duplicates, markdown-split, and setup are DEPRECATED — see
+docs/DEPRECATIONS.md for the v0.4.x trim plan.
+
+Global Flags:
+  --json               Machine-parseable JSON output
+  --help               Show help text
+  --verbose            Extended output
+  --version            Print version and exit
+  --cwd <path>         Override working directory
+  --backend <id>       Force a specific backend (agent commands only)
+  --model <name>       Override model (agent commands only)
+
+Run "gd <command> --help" for command-specific usage.
+`);
+}
+
+function printCommandHelp(cmd: string): void {
+  const resolvedCmd = cmd;
+  // Handle both bin/ (source) and dist/bin/ (compiled) locations
+  let cmdFile = join(__dirname, '..', 'commands', `${resolvedCmd}.md`);
+  if (!existsSync(cmdFile)) cmdFile = join(__dirname, '..', '..', 'commands', `${resolvedCmd}.md`);
+  if (existsSync(cmdFile)) {
+    const content = readFileSync(cmdFile, 'utf-8');
+    const match = content.match(/description:\s*(.+)/);
+    if (match) {
+      process.stdout.write(`gd ${cmd}: ${match[1].trim()}\n\n`);
+    }
+  }
+  process.stdout.write(`Usage: gd ${cmd} [args] [--json] [--verbose]\n`);
+}

package/bin/grd-manifest.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+require('tsx/cjs');
+require('./grd-manifest.ts');

package/bin/grd-manifest.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GRD Manifest — SHA256-based file tracking for self-update system
+ *
+ * Usage: node grd-manifest.js <command>
+ *
+ * Commands:
+ *   generate                    Generate grd-file-manifest.json with SHA256 hashes
+ *   detect                      Detect local modifications vs manifest
+ *   save-patches [--dir path]   Save modified files to grd-local-patches/
+ *   load-patches [--dir path]   Read patch backup metadata
+ */
+
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+const crypto = require('crypto') as typeof import('crypto');
+
+const MANIFEST_FILE = 'grd-file-manifest.json';
+const PATCH_DIR = 'grd-local-patches';
+const BACKUP_META = 'backup-meta.json';
+
+// Files/dirs to exclude from manifest
+const EXCLUDE: ReadonlySet<string> = new Set([
+  MANIFEST_FILE,
+  PATCH_DIR,
+  '.git',
+  'node_modules',
+  '.DS_Store',
+]);
+
+// ─── Interfaces ──────────────────────────────────────────────────────────────
+
+interface ManifestData {
+  version: string;
+  timestamp: string;
+  file_count: number;
+  files: Record<string, string>;
+}
+
+interface Modification {
+  file: string;
+  expected: string;
+  actual: string;
+}
+
+interface DetectionResult {
+  error?: string;
+  version?: string;
+  total_tracked?: number;
+  modifications: Modification[];
+  additions: string[];
+  deletions: string[];
+  clean: boolean;
+}
+
+interface PatchSaveResult {
+  saved: boolean;
+  reason?: string;
+  error?: string;
+  patch_dir?: string;
+  from_version?: string;
+  timestamp?: string;
+  files?: string[];
+  additions?: string[];
+  deletions?: string[];
+}
+
+interface PatchLoadResult {
+  found: boolean;
+  reason?: string;
+  patch_dir?: string;
+  from_version?: string;
+  timestamp?: string;
+  files?: string[];
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getPluginRoot(): string {
+  return path.dirname(__dirname);
+}
+
+function sha256(filePath: string): string {
+  const content: Buffer = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function walkDir(dir: string, base: string): string[] {
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (EXCLUDE.has(entry.name)) continue;
+    const fullPath: string = path.join(dir, entry.name);
+    const relPath: string = path.relative(base, fullPath);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, base));
+    } else if (entry.isFile()) {
+      results.push(relPath);
+    }
+  }
+  return results.sort();
+}
+
+function readVersion(pluginRoot: string): string {
+  const versionFile: string = path.join(pluginRoot, 'VERSION');
+  if (fs.existsSync(versionFile)) {
+    return fs.readFileSync(versionFile, 'utf-8').trim();
+  }
+  return 'unknown';
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+function generateManifest(pluginRoot: string): ManifestData {
+  const files: string[] = walkDir(pluginRoot, pluginRoot);
+  const hashes: Record<string, string> = {};
+  for (const file of files) {
+    const fullPath: string = path.join(pluginRoot, file);
+    hashes[file] = sha256(fullPath);
+  }
+
+  const manifest: ManifestData = {
+    version: readVersion(pluginRoot),
+    timestamp: new Date().toISOString(),
+    file_count: Object.keys(hashes).length,
+    files: hashes,
+  };
+
+  const manifestPath: string = path.join(pluginRoot, MANIFEST_FILE);
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+  return manifest;
+}
+
+function detectModifications(pluginRoot: string): DetectionResult {
+  const manifestPath: string = path.join(pluginRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) {
+    return {
+      error: 'No manifest found. Run: node bin/grd-manifest.js generate',
+      modifications: [],
+      additions: [],
+      deletions: [],
+      clean: false,
+    };
+  }
+
+  const manifest: ManifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  const modifications: Modification[] = [];
+  const additions: string[] = [];
+  const deletions: string[] = [];
+
+  // Check existing manifest entries
+  for (const [file, expectedHash] of Object.entries(manifest.files)) {
+    const fullPath: string = path.join(pluginRoot, file);
+    if (!fs.existsSync(fullPath)) {
+      deletions.push(file);
+    } else {
+      const currentHash: string = sha256(fullPath);
+      if (currentHash !== expectedHash) {
+        modifications.push({
+          file,
+          expected: expectedHash,
+          actual: currentHash,
+        });
+      }
+    }
+  }
+
+  // Check for new files
+  const currentFiles: string[] = walkDir(pluginRoot, pluginRoot);
+  for (const file of currentFiles) {
+    if (!manifest.files[file]) {
+      additions.push(file);
+    }
+  }
+
+  return {
+    version: manifest.version,
+    total_tracked: Object.keys(manifest.files).length,
+    modifications,
+    additions,
+    deletions,
+    clean: modifications.length === 0 && additions.length === 0 && deletions.length === 0,
+  };
+}
+
+function savePatches(pluginRoot: string, patchDirOverride?: string | null): PatchSaveResult {
+  const detection: DetectionResult = detectModifications(pluginRoot);
+  if (detection.error) return { saved: false, error: detection.error };
+  if (detection.clean) return { saved: false, reason: 'No modifications detected' };
+
+  const patchDir: string = patchDirOverride || path.join(pluginRoot, PATCH_DIR);
+  fs.mkdirSync(patchDir, { recursive: true });
+
+  const savedFiles: string[] = [];
+
+  for (const mod of detection.modifications) {
+    const srcPath: string = path.join(pluginRoot, mod.file);
+    const destPath: string = path.join(patchDir, mod.file);
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.copyFileSync(srcPath, destPath);
+    savedFiles.push(mod.file);
+  }
+
+  const meta = {
+    from_version: detection.version,
+    timestamp: new Date().toISOString(),
+    files: savedFiles,
+    additions: detection.additions,
+    deletions: detection.deletions,
+  };
+
+  fs.writeFileSync(path.join(patchDir, BACKUP_META), JSON.stringify(meta, null, 2) + '\n', 'utf-8');
+
+  return { saved: true, patch_dir: patchDir, ...meta };
+}
+
+function loadPatches(pluginRoot: string, patchDirOverride?: string | null): PatchLoadResult {
+  const patchDir: string = patchDirOverride || path.join(pluginRoot, PATCH_DIR);
+  const metaPath: string = path.join(patchDir, BACKUP_META);
+
+  if (!fs.existsSync(metaPath)) {
+    return { found: false, reason: `No patches found at ${patchDir}` };
+  }
+
+  const meta: { from_version?: string; timestamp?: string; files?: string[] } = JSON.parse(
+    fs.readFileSync(metaPath, 'utf-8')
+  );
+  return { found: true, patch_dir: patchDir, ...meta };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function main(): void {
+  const args: string[] = process.argv.slice(2);
+  const command: string | undefined = args[0];
+  const pluginRoot: string = getPluginRoot();
+
+  const dirIndex: number = args.indexOf('--dir');
+  const dirOverride: string | null = dirIndex !== -1 ? args[dirIndex + 1] : null;
+
+  let result: ManifestData | DetectionResult | PatchSaveResult | PatchLoadResult;
+
+  switch (command) {
+    case 'generate':
+      result = generateManifest(pluginRoot);
+      console.log(
+        JSON.stringify(
+          {
+            status: 'ok',
+            version: (result as ManifestData).version,
+            file_count: (result as ManifestData).file_count,
+            path: path.join(pluginRoot, MANIFEST_FILE),
+          },
+          null,
+          2
+        )
+      );
+      break;
+
+    case 'detect':
+      result = detectModifications(pluginRoot);
+      console.log(JSON.stringify(result, null, 2));
+      if ((result as DetectionResult).error) process.exit(1);
+      break;
+
+    case 'save-patches':
+      result = savePatches(pluginRoot, dirOverride);
+      console.log(JSON.stringify(result, null, 2));
+      if ((result as PatchSaveResult).error) process.exit(1);
+      break;
+
+    case 'load-patches':
+      result = loadPatches(pluginRoot, dirOverride);
+      console.log(JSON.stringify(result, null, 2));
+      break;
+
+    default:
+      console.error('Usage: node grd-manifest.js <generate|detect|save-patches|load-patches>');
+      process.exit(1);
+  }
+}
+
+main();

package/bin/grd-mcp-server.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+require('tsx/cjs');
+require('./grd-mcp-server.ts');

package/bin/grd-mcp-server.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GRD MCP Server -- Entry point wiring lib/mcp-server.ts to stdin/stdout as MCP stdio transport.
+ *
+ * Reads JSON-RPC 2.0 messages from stdin (newline-delimited JSON), dispatches to McpServer,
+ * writes responses to stdout. Runs until stdin closes (EOF).
+ *
+ * Usage: node bin/grd-mcp-server.js
+ *
+ * Created in Phase 16 Plan 01 (MCP Server).
+ * Migrated to TypeScript in Phase 63 Plan 04.
+ */
+
+
+/** JSON-RPC 2.0 message received on stdin */
+interface JsonRpcMessage {
+  jsonrpc?: string;
+  method?: string;
+  id?: number | string | null;
+  params?: Record<string, unknown>;
+}
+
+/** JSON-RPC 2.0 response written to stdout */
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number | string | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** McpServer class shape for typed instantiation */
+interface McpServerInstance {
+  handleMessage(message: JsonRpcMessage): JsonRpcResponse | Promise<JsonRpcResponse> | null;
+}
+
+interface McpServerConstructor {
+  new (options?: { cwd?: string }): McpServerInstance;
+}
+
+const {
+  McpServer,
+}: {
+  McpServer: McpServerConstructor;
+} = require('../lib/mcp-server');
+
+const server: McpServerInstance = new McpServer({ cwd: process.cwd() });
+
+let buffer: string = '';
+
+process.stdin.setEncoding('utf-8');
+
+process.stdin.on('data', (chunk: string) => {
+  buffer += chunk;
+
+  // Process complete lines
+  let newlineIdx: number;
+  while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+    const line: string = buffer.slice(0, newlineIdx).trim();
+    buffer = buffer.slice(newlineIdx + 1);
+
+    // Skip empty lines
+    if (!line) continue;
+
+    let message: JsonRpcMessage;
+    try {
+      message = JSON.parse(line) as JsonRpcMessage;
+    } catch (_e: unknown) {
+      // Malformed JSON -- write parse error response
+      const errorResponse: JsonRpcResponse = {
+        jsonrpc: '2.0' as const,
+        id: null,
+        error: { code: -32700, message: 'Parse error' },
+      };
+      process.stdout.write(JSON.stringify(errorResponse) + '\n');
+      continue;
+    }
+
+    const response: JsonRpcResponse | Promise<JsonRpcResponse> | null =
+      server.handleMessage(message);
+
+    // Notifications return null -- no response needed
+    if (response !== null && response !== undefined) {
+      // Handle both sync responses and async (Promise) responses
+      Promise.resolve(response).then((r: JsonRpcResponse | null) => {
+        if (r !== null && r !== undefined) {
+          process.stdout.write(JSON.stringify(r) + '\n');
+        }
+      });
+    }
+  }
+});
+
+process.stdin.on('end', () => {
+  // Handle any remaining data in buffer
+  const remaining: string = buffer.trim();
+  if (remaining) {
+    try {
+      const message: JsonRpcMessage = JSON.parse(remaining) as JsonRpcMessage;
+      const response: JsonRpcResponse | Promise<JsonRpcResponse> | null =
+        server.handleMessage(message);
+
+      Promise.resolve(response).then((r: JsonRpcResponse | null) => {
+        if (r !== null && r !== undefined) {
+          process.stdout.write(JSON.stringify(r) + '\n');
+        }
+      });
+    } catch (_e: unknown) {
+      const errorResponse: JsonRpcResponse = {
+        jsonrpc: '2.0' as const,
+        id: null,
+        error: { code: -32700, message: 'Parse error' },
+      };
+      process.stdout.write(JSON.stringify(errorResponse) + '\n');
+    }
+  }
+
+  process.exit(0);
+});
+
+process.stdin.on('error', () => {
+  process.exit(0);
+});

package/bin/grd-tools.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+require('tsx/cjs');
+require('./grd-tools.ts');