@jokerized/getresearchdone 0.4.1

package/lib/metrics.ts

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * GRD Metrics -- In-memory counters for observability.
+ *
+ * Simple counter module. Each counter is a number keyed by an event
+ * name. Reset on process start. Scheduler, phase-complete-llm, and
+ * autopilot increment counters at event points; gd metrics reads
+ * them.
+ *
+ * For persistent metrics across processes, see future spec —
+ * current scope is single-process observability.
+ */
+
+const _counters: Map<string, number> = new Map();
+
+/**
+ * Increments the counter for the given event name by delta (default 1).
+ * Creates the counter if it doesn't exist.
+ */
+export function incrementCounter(name: string, delta: number = 1): void {
+  _counters.set(name, (_counters.get(name) || 0) + delta);
+}
+
+/**
+ * Returns a snapshot of all counters as a plain object. Safe to call
+ * repeatedly; does not reset counters.
+ */
+export function getCounters(): Record<string, number> {
+  const snapshot: Record<string, number> = {};
+  for (const [k, v] of _counters.entries()) {
+    snapshot[k] = v;
+  }
+  return snapshot;
+}
+
+/**
+ * Resets all counters to zero. Useful for tests; not currently exposed
+ * via CLI.
+ */
+export function resetCounters(): void {
+  _counters.clear();
+}
+
+module.exports = {
+  incrementCounter,
+  getCounters,
+  resetCounters,
+};

package/lib/overstory.ts

@@ -0,0 +1,270 @@
+'use strict';
+
+/**
+ * GRD Overstory Adapter -- Detection, plan dispatch, status polling, merge
+ *
+ * Wraps the `ov` CLI to use Overstory as an execution backend for GRD.
+ * Follows the same shell-out pattern as lib/worktree.ts.
+ *
+ * Requires: Overstory v0.8.0+ (stable --json output)
+ */
+
+import type {
+  OverstoryInfo,
+  OverstoryConfig,
+  SlingOpts,
+  SlingResult,
+  AgentStatus,
+  FleetStatus,
+  MergeResult,
+  OverstoryMailMessage,
+} from './types';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { safeReadJSON }: { safeReadJSON: (p: string, d: unknown) => unknown } = require('./utils');
+
+const MIN_VERSION = '0.8.0';
+const OV_MAX_AGENTS = 25;
+
+function compareSemver(a: string, b: string): number {
+  // Strip pre-release suffixes (e.g. '0.8.0-beta.1' -> '0.8.0')
+  const pa = a.split('-')[0].split('.').map(Number);
+  const pb = b.split('-')[0].split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
+/** Run an `ov` CLI command synchronously and return stdout. */
+function ovExec(cwd: string, args: string[], timeout: number): string {
+  return execFileSync('ov', args, {
+    cwd,
+    timeout,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }) as string;
+}
+
+const DEFAULT_OVERSTORY_CONFIG: OverstoryConfig = {
+  runtime: 'claude',
+  install_prompt: true,
+  poll_interval_ms: 5000,
+  merge_strategy: 'auto',
+  overlay_template: null,
+};
+
+function loadOverstoryConfig(cwd: string): OverstoryConfig {
+  const parsed = safeReadJSON(path.join(cwd, '.planning', 'config.json'), {}) as Record<
+    string,
+    unknown
+  >;
+  const ov = (parsed.overstory || {}) as Partial<OverstoryConfig>;
+  return { ...DEFAULT_OVERSTORY_CONFIG, ...ov };
+}
+
+function detectOverstory(cwd: string, preloadedConfig?: OverstoryConfig): OverstoryInfo | null {
+  const configPath = path.join(cwd, '.overstory', 'config.yaml');
+  if (!fs.existsSync(configPath)) return null;
+
+  let version: string;
+  try {
+    version = ovExec(cwd, ['--version'], 5000).trim().replace(/^v/, '');
+  } catch {
+    return null;
+  }
+
+  if (compareSemver(version, MIN_VERSION) < 0) return null;
+
+  const ovConfig = preloadedConfig || loadOverstoryConfig(cwd);
+  return {
+    available: true,
+    version,
+    config_path: configPath,
+    max_agents: OV_MAX_AGENTS,
+    default_runtime: ovConfig.runtime,
+    worktree_base: path.join(cwd, '.overstory', 'worktrees'),
+  };
+}
+
+function installOverstory(cwd: string): void {
+  const ovCfg = safeReadJSON(path.join(cwd, '.planning', 'config.json'), {}) as Record<string, unknown>;
+  const ovTimeouts = ovCfg.timeouts as Record<string, unknown> | undefined;
+  const probeMs: number = typeof ovTimeouts?.overstory_probe_ms === 'number' ? ovTimeouts.overstory_probe_ms : 5000;
+  const installMs: number = typeof ovTimeouts?.overstory_install_ms === 'number' ? ovTimeouts.overstory_install_ms : 120000;
+
+  try {
+    execFileSync('bun', ['--version'], {
+      timeout: probeMs,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    throw new Error(
+      'Overstory requires Bun. Install via: curl -fsSL https://bun.sh/install | bash'
+    );
+  }
+
+  execFileSync('bun', ['install', '-g', 'overstory'], {
+    cwd,
+    timeout: installMs,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  ovExec(cwd, ['init'], 30000);
+}
+
+function slingPlan(cwd: string, opts: SlingOpts): SlingResult {
+  // plan_path is consumed via the overlay; timeout_minutes is enforced by GRD's poll loop (ov stop)
+  const args = [
+    'sling',
+    `GRD plan ${opts.plan_id}: execute plan`,
+    '--runtime',
+    opts.runtime,
+    '--model',
+    opts.model,
+    '--overlay',
+    opts.overlay_path,
+  ];
+  return JSON.parse(ovExec(cwd, args, 60000)) as SlingResult;
+}
+
+/**
+ * Dispatch a plan via sling and poll until the agent reaches a terminal state.
+ *
+ * @param cwd - Working directory (project root)
+ * @param opts - Sling dispatch options (plan id, runtime, model, overlay path)
+ * @param pollIntervalMs - Milliseconds between each status poll
+ * @param mergeStrategy - 'auto' triggers mergeAgent() on completion; 'manual' skips it
+ * @returns Resolved promise with exit code, wall-clock duration, and agent id
+ */
+async function slingPlanAsync(
+  cwd: string,
+  opts: SlingOpts,
+  pollIntervalMs: number,
+  mergeStrategy: 'auto' | 'manual'
+): Promise<{ exitCode: number; duration: number; agentId: string }> {
+  const startTime = Date.now();
+  const result: SlingResult = slingPlan(cwd, opts);
+  const agentId = result.agent_id;
+
+  let exitCode: number;
+  while (true) {
+    await new Promise<void>((resolve) => setTimeout(resolve, pollIntervalMs));
+    const status: AgentStatus = getAgentStatus(cwd, agentId);
+    if (status.state === 'done') {
+      exitCode = status.exit_code ?? 0;
+      break;
+    }
+    if (status.state === 'failed') {
+      exitCode = status.exit_code ?? 1;
+      break;
+    }
+  }
+
+  if (mergeStrategy === 'auto') {
+    mergeAgent(cwd, agentId);
+  }
+
+  const duration = Date.now() - startTime;
+  return { exitCode, duration, agentId };
+}
+
+function getAgentStatus(cwd: string, agentId: string): AgentStatus {
+  return JSON.parse(ovExec(cwd, ['status', agentId, '--json'], 10000)) as AgentStatus;
+}
+
+function getFleetStatus(cwd: string): FleetStatus {
+  return JSON.parse(ovExec(cwd, ['status', '--json'], 10000)) as FleetStatus;
+}
+
+function mergeAgent(cwd: string, agentId: string): MergeResult {
+  // ov merge outputs JSON by default per Overstory's CLI contract
+  return JSON.parse(ovExec(cwd, ['merge', agentId, '--json'], 60000)) as MergeResult;
+}
+
+function stopAgent(cwd: string, agentId: string): void {
+  ovExec(cwd, ['stop', agentId], 10000);
+}
+
+function getAgentMail(cwd: string, agentId: string): OverstoryMailMessage[] {
+  const parsed = JSON.parse(ovExec(cwd, ['mail', '--agent', agentId, '--json'], 10000)) as {
+    messages: OverstoryMailMessage[];
+  };
+  return parsed.messages;
+}
+
+function nudgeAgent(cwd: string, agentId: string, message: string): void {
+  ovExec(cwd, ['nudge', agentId, '--', message], 10000);
+}
+
+function generateOverlay(
+  planContent: string,
+  context: {
+    phase_number: string;
+    plan_id: string;
+    milestone: string;
+    phase_dir: string;
+  }
+): string {
+  const summaryName = `${context.plan_id}-SUMMARY.md`;
+  return `# GRD Executor Task
+
+## Your Assignment
+
+${planContent}
+
+## GRD Conventions
+
+- Write your execution summary to \`${context.phase_dir}/${summaryName}\`
+- Use frontmatter: phase, plan, type, status, duration
+- Commit frequently with descriptive messages
+- Run tests before committing
+
+## Summary Format
+
+\`\`\`markdown
+---
+phase: ${context.phase_number}
+plan: ${context.plan_id.split('-')[1] || '01'}
+type: execution
+status: complete
+duration: Xmin
+---
+
+## One-Liner
+[Single sentence describing what was accomplished]
+
+## Changes Made
+- [File]: [What changed]
+
+## Verification
+- [Test/check]: [Result]
+\`\`\`
+`;
+}
+
+module.exports = {
+  MIN_VERSION,
+  DEFAULT_OVERSTORY_CONFIG,
+  compareSemver,
+  ovExec,
+  loadOverstoryConfig,
+  detectOverstory,
+  installOverstory,
+  slingPlan,
+  slingPlanAsync,
+  getAgentStatus,
+  getFleetStatus,
+  mergeAgent,
+  stopAgent,
+  getAgentMail,
+  nudgeAgent,
+  generateOverlay,
+};