@jokerized/getresearchdone 0.4.1

package/lib/cli/adapters.ts

@@ -0,0 +1,41 @@
+'use strict';
+
+import type { BackendAdapter } from '../types';
+
+const {
+  ADAPTERS,
+  checkBinary,
+}: {
+  ADAPTERS: Record<string, BackendAdapter>;
+  checkBinary: (binary: string) => boolean;
+} = require('../scheduler');
+
+export interface CliAdapter {
+  binary: string;
+  buildArgs(prompt: string, opts: { model?: string; verbose?: boolean }): string[];
+}
+
+/**
+ * Derives a CliAdapter from the scheduler's BackendAdapter by adapting
+ * the buildArgs signature (SpawnOpts → simpler cli opts).
+ */
+function toCliAdapter(adapter: BackendAdapter): CliAdapter {
+  return {
+    binary: adapter.binary,
+    buildArgs(prompt: string, opts: { model?: string; verbose?: boolean }): string[] {
+      return adapter.buildArgs(prompt, { model: opts.model });
+    },
+  };
+}
+
+export function getAdapter(backend: string): CliAdapter {
+  const adapter = ADAPTERS[backend] || ADAPTERS.claude;
+  return toCliAdapter(adapter);
+}
+
+export function checkBackendAvailable(backend: string): boolean {
+  const adapter = ADAPTERS[backend] || ADAPTERS.claude;
+  return checkBinary(adapter.binary);
+}
+
+module.exports = { getAdapter, checkBackendAvailable };

package/lib/cli/agent.ts

@@ -0,0 +1,83 @@
+'use strict';
+
+const { spawnSync } = require('child_process') as typeof import('child_process');
+import type { CliAdapter } from './adapters';
+import type { JsonEnvelope } from './output';
+
+export interface AgentOpts {
+  cwd: string;
+  backend: string;
+  json: boolean;
+  verbose: boolean;
+  model?: string;
+  timeout?: number;
+}
+
+/**
+ * Build the prompt string for an agent command.
+ */
+export function buildPromptForCommand(command: string, args: string[]): string {
+  const argsStr = args.length > 0 ? ' ' + args.join(' ') : '';
+  return `/grd:${command}${argsStr}`;
+}
+
+/**
+ * Execute an agent command by spawning a backend subprocess.
+ */
+export function runAgentCommand(command: string, args: string[], opts: AgentOpts): void {
+  const {
+    getAdapter,
+    checkBackendAvailable,
+  }: {
+    getAdapter: (backend: string) => CliAdapter;
+    checkBackendAvailable: (backend: string) => boolean;
+  } = require('./adapters');
+  const {
+    formatJson,
+    formatError,
+  }: {
+    formatJson: (envelope: JsonEnvelope) => string;
+    formatError: (message: string, backend: string, exitCode: number) => string;
+  } = require('./output');
+
+  if (!checkBackendAvailable(opts.backend)) {
+    const msg = `Backend "${opts.backend}" CLI not found. Install it or set --backend to an available option.`;
+    if (opts.json) {
+      process.stdout.write(formatError(msg, opts.backend, 1) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    process.exit(1);
+  }
+
+  const prompt = buildPromptForCommand(command, args);
+  const adapter = getAdapter(opts.backend);
+  const cliArgs = adapter.buildArgs(prompt, { model: opts.model, verbose: opts.verbose });
+
+  const startTime = Date.now();
+  const result = spawnSync(adapter.binary, cliArgs, {
+    cwd: opts.cwd,
+    stdio: opts.json ? 'pipe' : 'inherit',
+    maxBuffer: 50 * 1024 * 1024,
+    timeout: opts.timeout || 120 * 60 * 1000,
+    env: { ...process.env },
+  });
+
+  const duration = Date.now() - startTime;
+  const exitCode = result.status ?? 1;
+
+  if (opts.json) {
+    const stdout = result.stdout?.toString() || '';
+    process.stdout.write(
+      formatJson({
+        status: exitCode === 0 ? 'ok' : 'error',
+        output: stdout,
+        meta: { backend: opts.backend, duration_ms: duration, exit_code: exitCode },
+      }) + '\n'
+    );
+  }
+
+  process.exit(exitCode);
+}
+
+module.exports = { buildPromptForCommand, runAgentCommand };

package/lib/cli/index.ts

@@ -0,0 +1,273 @@
+'use strict';
+
+export interface Flags {
+  json: boolean;
+  help: boolean;
+  version: boolean;
+  verbose: boolean;
+  cwd?: string;
+  backend?: string;
+  model?: string;
+  positional: string[];
+  passthrough: string[];
+}
+
+const TOOL_COMMANDS = new Set([
+  'state',
+  'verify',
+  'phase',
+  'scaffold',
+  'frontmatter',
+  'tracker',
+  'roadmap',
+  'init',
+  'milestone',
+  'validate',
+  'state-snapshot',
+  'summary-extract',
+  'history-digest',
+  'phase-plan-index',
+  'detect-backend',
+  'resolve-model',
+  'version',
+  'dashboard',
+  'health',
+  'health-check',
+  'coverage-report',
+  'quality-analysis',
+  'todo',
+  'worktree',
+  'search',
+  'generate-slug',
+  'config-set',
+  'config-diff',
+  'phase-detail',
+  'phase-risk',
+  'phase-readiness',
+  'milestone-health',
+  'decision-timeline',
+  'parallel-progress',
+  'find-phase',
+  'commit',
+  'verify-summary',
+  'template',
+  'current-timestamp',
+  'list-todos',
+  'verify-path-exists',
+  'config-ensure-section',
+  'phases',
+  'migrate-dirs',
+  'setup',
+  'citation-backlinks',
+  'eval-regression-check',
+  'phase-time-budget',
+  'import-knowledge',
+  'todo-duplicates',
+  'markdown-split',
+  'overstory',
+  'progress',
+  'knowhow',
+  'citation-graph',
+  'artifact-dag',
+  'benchmark-report',
+  'autoresearch',
+  'scan',
+  'metrics',
+  'dead-end',
+  'plan-tournament',
+  'think',
+  'genome',
+  // Codex r23 P2: Ouroboros r9/r10 commands need to reach the tool
+  // router via the public `gd` CLI. Without these entries
+  // classifyCommand falls through to "unknown command" or routes
+  // execute-phase --dry-run to the agent path.
+  'blame',
+  'budget',
+  'check-assumptions',
+  'check-plans',
+  'deps',
+  'deps-risk',
+  'diagnose',
+  'estimate',
+  'estimate-phase',
+  'eval',
+  'export-research',
+  'forecast-phase',
+  'freshness',
+  'impact',
+  'import-knowhow',
+  'import-research',
+  'knowledge',
+  'research-gaps',
+  'rollback',
+  'tail',
+  'todos',
+  'watch',
+  'singularity',
+  'plan-lint',
+  'plan-candidates',
+  'select-candidate',
+  'patterns',
+  'install',
+]);
+
+/**
+ * Canonical list of init workflow names. Used by both cli/index.ts (for
+ * classifyCommand disambiguation) and bin/grd-tools.ts (for init subcommand
+ * validation). Single source of truth — do not duplicate.
+ */
+export const INIT_WORKFLOWS: readonly string[] = [
+  'execute-phase',
+  'execute-parallel',
+  'plan-phase',
+  'new-project',
+  'new-milestone',
+  'quick',
+  'resume',
+  'verify-work',
+  'phase-op',
+  'todos',
+  'milestone-op',
+  'plan-milestone-gaps',
+  'map-codebase',
+  'progress',
+  'survey',
+  'deep-dive',
+  'feasibility',
+  'eval-plan',
+  'eval-report',
+  'assess-baseline',
+  'product-plan',
+  'iterate',
+  'autopilot',
+  'multi-milestone-autopilot',
+  'autoplan',
+  'autoresearch',
+  'evolve',
+  'wireup',
+  'debug',
+  'integration-check',
+  'migrate',
+  'plan-check',
+  'phase-research',
+  'code-review',
+  'project-researcher',
+  'research-synthesizer',
+  'roadmapper',
+  'verifier',
+];
+
+const INIT_TOOL_SUBS = new Set(INIT_WORKFLOWS);
+
+export const AGENT_COMMANDS = new Set([
+  'init',
+  'new-milestone',
+  'plan-phase',
+  'execute-phase',
+  'verify-phase',
+  'autopilot',
+  'autoplan',
+  'autoresearch',
+  'evolve',
+  'resume-project',
+  'pause-work',
+  'quick',
+  'migrate',
+  'survey',
+  'deep-dive',
+  'compare-methods',
+  'feasibility',
+  'product-plan',
+  'discuss-phase',
+  'list-phase-assumptions',
+  'long-term-roadmap',
+  'add-phase',
+  'insert-phase',
+  'remove-phase',
+  'complete-milestone',
+  'plan-milestone-gaps',
+  'assess-baseline',
+  'eval-report',
+  'iterate',
+  'verify-work',
+  'settings',
+  'principles',
+  'discover',
+  'tracker-setup',
+  'sync',
+  'check-todos',
+  'add-todo',
+  'map-codebase',
+  'update',
+  'reapply-patches',
+  'help',
+  'debug',
+  'requirement',
+]);
+
+const EVOLVE_TOOL_SUBS = new Set(['run', 'discover', 'state', 'advance', 'reset']);
+const SETTINGS_TOOL_SUBS = new Set(['token_profile', 'effort', 'phase_complete_llm_fallback']);
+
+export function parseFlags(argv: string[]): Flags {
+  const flags: Flags = {
+    json: false,
+    help: false,
+    version: false,
+    verbose: false,
+    positional: [],
+    passthrough: [],
+  };
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    } else if (arg === '--verbose') {
+      flags.verbose = true;
+    } else if (arg === '--cwd' && i + 1 < argv.length) {
+      flags.cwd = argv[++i];
+    } else if (arg === '--backend' && i + 1 < argv.length) {
+      flags.backend = argv[++i];
+    } else if (arg === '--model' && i + 1 < argv.length) {
+      flags.model = argv[++i];
+    } else if (arg.startsWith('--')) {
+      flags.passthrough.push(arg);
+      // If the next arg doesn't start with --, treat it as the value for this flag
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags.passthrough.push(argv[++i]);
+      }
+    } else {
+      flags.positional.push(arg);
+    }
+    i++;
+  }
+
+  return flags;
+}
+
+export function classifyCommand(
+  command: string,
+  subcommand?: string
+): 'tool' | 'agent' | 'unknown' {
+  if (command === 'evolve' && subcommand && EVOLVE_TOOL_SUBS.has(subcommand)) {
+    return 'tool';
+  }
+  if (command === 'settings' && subcommand && SETTINGS_TOOL_SUBS.has(subcommand)) {
+    return 'tool';
+  }
+  // `gd init <workflow>` → tool (init context), `gd init` (no args) → agent (project init)
+  if (command === 'init') {
+    if (subcommand && INIT_TOOL_SUBS.has(subcommand)) return 'tool';
+    return 'agent';
+  }
+  if (TOOL_COMMANDS.has(command)) return 'tool';
+  if (AGENT_COMMANDS.has(command)) return 'agent';
+  return 'unknown';
+}
+
+module.exports = { parseFlags, classifyCommand, TOOL_COMMANDS, AGENT_COMMANDS, INIT_WORKFLOWS };

package/lib/cli/output.ts

@@ -0,0 +1,33 @@
+'use strict';
+
+export interface JsonEnvelope {
+  status: 'ok' | 'error';
+  data?: unknown;
+  output?: string;
+  error?: string;
+  meta: {
+    backend?: string;
+    duration_ms?: number;
+    exit_code?: number;
+  };
+}
+
+/**
+ * Format a JSON envelope for --json output.
+ */
+export function formatJson(envelope: JsonEnvelope): string {
+  return JSON.stringify(envelope, null, 2);
+}
+
+/**
+ * Format an error as a JSON envelope.
+ */
+export function formatError(message: string, backend: string, exitCode: number): string {
+  return formatJson({
+    status: 'error',
+    error: message,
+    meta: { backend, exit_code: exitCode },
+  });
+}
+
+module.exports = { formatJson, formatError };

package/lib/cli/scan-dispatch.ts

@@ -0,0 +1,130 @@
+"use strict";
+
+/**
+ * GRD CLI/ScanDispatch -- Pure file-resolution helpers for `gd scan`.
+ *
+ * Given a mode (staged/diff/file/all) and cwd, return the set of markdown
+ * files to scan. Kept separate from runScan so it can be unit-tested without
+ * filesystem state from the whole repo.
+ *
+ * SECURITY: all git calls use execFileSync('git', [args]) — never a shell
+ * string template. User-controlled values (e.g. --diff <base>) flow through
+ * as positional argv, not shell tokens.
+ */
+
+const fs = require("fs") as typeof import("fs");
+const path = require("path") as typeof import("path");
+const { execFileSync } =
+  require("child_process") as typeof import("child_process");
+
+import type { ScanMode } from "../commands/scan";
+
+export interface ResolveScanOpts {
+  mode: ScanMode;
+  cwd: string;
+  filePath?: string;
+  diffBase?: string;
+}
+
+const SCAN_DIRS = ["commands", "agents", "templates", "docs"];
+
+// Git pathspecs mirroring SCAN_DIRS, with docs/superpowers/ excluded to
+// match the _walkMarkdown behavior. Used by _resolveStaged and _resolveDiff.
+const SCAN_PATHSPECS: readonly string[] = [
+  "commands/**/*.md",
+  "agents/**/*.md",
+  "templates/**/*.md",
+  "docs/**/*.md",
+  ":(exclude)docs/superpowers/**",
+];
+
+export function resolveScanFiles(opts: ResolveScanOpts): string[] {
+  const { mode, cwd } = opts;
+  switch (mode) {
+    case "file":
+      return _resolveFile(opts);
+    case "all":
+      return _resolveAll(cwd);
+    case "staged":
+      return _resolveStaged(cwd);
+    case "diff":
+      return _resolveDiff(cwd, opts.diffBase || "origin/main");
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _resolveFile(opts: ResolveScanOpts): string[] {
+  if (!opts.filePath) {
+    throw new Error("--file mode requires a file path");
+  }
+  if (!fs.existsSync(opts.filePath)) {
+    throw new Error(`file not found: ${opts.filePath}`);
+  }
+  return [opts.filePath];
+}
+
+function _resolveAll(cwd: string): string[] {
+  const files: string[] = [];
+  for (const dir of SCAN_DIRS) {
+    const full = path.join(cwd, dir);
+    if (!fs.existsSync(full)) continue;
+    _walkMarkdown(full, files);
+  }
+  return files;
+}
+
+function _resolveStaged(cwd: string): string[] {
+  const out = _safeGit(
+    ["diff", "--cached", "--name-only", "--", ...SCAN_PATHSPECS],
+    cwd,
+  );
+  if (out === null) return [];
+  return _absolutizeAndFilter(out, cwd);
+}
+
+function _resolveDiff(cwd: string, base: string): string[] {
+  const out = _safeGit(
+    ["diff", "--name-only", `${base}...HEAD`, "--", ...SCAN_PATHSPECS],
+    cwd,
+  );
+  if (out === null) {
+    throw new Error(`git diff failed against base ${base}`);
+  }
+  return _absolutizeAndFilter(out, cwd);
+}
+
+function _safeGit(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+function _absolutizeAndFilter(raw: string, cwd: string): string[] {
+  return raw
+    .split("\n")
+    .filter((x) => x.length > 0)
+    .map((f) => path.join(cwd, f))
+    .filter((f) => fs.existsSync(f));
+}
+
+function _walkMarkdown(dir: string, out: string[]): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "superpowers" && path.basename(dir) === "docs")
+        continue;
+      _walkMarkdown(full, out);
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full);
+    }
+  }
+}
+
+module.exports = { resolveScanFiles };