claude-all-hands 1.0.1 → 1.0.3

package/.claude/envoy/src/lib/observability.ts

@@ -0,0 +1,262 @@
+/**
+ * Observability system for claude-envoy.
+ * Dual system: metrics.jsonl (analytics) + envoy.log (detailed traces).
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { getProjectRoot, getBranch } from "./git.js";
+
+/**
+ * Derive plan_name from branch.
+ * Worktree branches follow pattern: feature-foo/implementation-1-A
+ * Plan name is the parent branch before /implementation-*
+ */
+export function getPlanName(branch?: string | null): string | undefined {
+  const b = branch ?? getBranch();
+  if (!b) return undefined;
+  // Strip /implementation-* suffix if present
+  const match = b.match(/^(.+?)\/implementation-/);
+  return match ? match[1] : b;
+}
+
+// --- Types ---
+
+export type LogLevel = "info" | "warn" | "error";
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  command: string;
+  plan_name?: string;
+  branch?: string;
+  caller?: string;
+  args?: Record<string, unknown>;
+  result?: "success" | "error";
+  duration_ms?: number;
+  context?: Record<string, unknown>;
+}
+
+export interface MetricEvent {
+  type: string;
+  timestamp: string;
+  plan_name?: string;
+  branch?: string;
+  [key: string]: unknown;
+}
+
+// --- File Paths ---
+
+function getObservabilityDir(): string {
+  return join(getProjectRoot(), ".claude");
+}
+
+function getLogPath(): string {
+  return join(getObservabilityDir(), "envoy.log");
+}
+
+function getMetricsPath(): string {
+  return join(getObservabilityDir(), "metrics.jsonl");
+}
+
+// --- Ensure Directory Exists ---
+
+function ensureObservabilityDir(): void {
+  const dir = getObservabilityDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+// --- Logging ---
+
+/**
+ * Write a log entry to envoy.log.
+ */
+export function log(entry: Omit<LogEntry, "timestamp">): void {
+  ensureObservabilityDir();
+  const branch = getBranch() || undefined;
+  const fullEntry: LogEntry = {
+    timestamp: new Date().toISOString(),
+    branch,
+    plan_name: getPlanName(branch),
+    ...entry,
+  };
+  try {
+    appendFileSync(getLogPath(), JSON.stringify(fullEntry) + "\n");
+  } catch {
+    // Silent fail - observability should not break commands
+  }
+}
+
+/**
+ * Log an info-level entry.
+ */
+export function logInfo(
+  command: string,
+  context?: Record<string, unknown>,
+  args?: Record<string, unknown>
+): void {
+  log({ level: "info", command, context, args });
+}
+
+/**
+ * Log a warning-level entry.
+ */
+export function logWarn(
+  command: string,
+  context?: Record<string, unknown>,
+  args?: Record<string, unknown>
+): void {
+  log({ level: "warn", command, context, args });
+}
+
+/**
+ * Log an error-level entry.
+ */
+export function logError(
+  command: string,
+  context?: Record<string, unknown>,
+  args?: Record<string, unknown>
+): void {
+  log({ level: "error", command, context, args });
+}
+
+/**
+ * Log command start.
+ */
+export function logCommandStart(
+  command: string,
+  args?: Record<string, unknown>
+): void {
+  log({
+    level: "info",
+    command,
+    args,
+    result: undefined,
+    context: { phase: "start" },
+  });
+}
+
+/**
+ * Log command completion.
+ */
+export function logCommandComplete(
+  command: string,
+  result: "success" | "error",
+  duration_ms: number,
+  context?: Record<string, unknown>
+): void {
+  log({
+    level: result === "error" ? "error" : "info",
+    command,
+    result,
+    duration_ms,
+    context: { ...context, phase: "complete" },
+  });
+}
+
+// --- Metrics ---
+
+/**
+ * Append a metric event to metrics.jsonl.
+ */
+export function recordMetric(
+  event: { type: string } & Record<string, unknown>
+): void {
+  ensureObservabilityDir();
+  const branch = typeof event.branch === "string" ? event.branch : getBranch();
+  const planName = typeof event.plan_name === "string" ? event.plan_name : getPlanName(branch);
+  const fullEvent: MetricEvent = {
+    ...event,
+    timestamp: new Date().toISOString(),
+    branch: branch || undefined,
+    plan_name: planName,
+  };
+  try {
+    appendFileSync(getMetricsPath(), JSON.stringify(fullEvent) + "\n");
+  } catch {
+    // Silent fail - observability should not break commands
+  }
+}
+
+// --- Specific Metric Events ---
+
+export function recordPlanCreated(data: {
+  mode: string;
+  prompt_count: number;
+  has_variants: boolean;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "plan_created", ...data });
+}
+
+export function recordPlanCompleted(data: {
+  duration_ms: number;
+  prompt_count: number;
+  total_iterations: number;
+  gemini_calls: number;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "plan_completed", ...data });
+}
+
+export function recordPromptStarted(data: {
+  prompt_num: number;
+  variant?: string | null;
+  specialist?: string;
+  is_debug: boolean;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "prompt_started", ...data });
+}
+
+export function recordPromptCompleted(data: {
+  prompt_num: number;
+  variant?: string | null;
+  duration_ms: number;
+  iterations: number;
+  review_passes: number;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "prompt_completed", ...data });
+}
+
+export function recordGateCompleted(data: {
+  gate_type: string;
+  duration_ms: number;
+  user_refinements_count: number;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "gate_completed", ...data });
+}
+
+export function recordGeminiCall(data: {
+  endpoint: "audit" | "review" | "ask";
+  duration_ms: number;
+  success: boolean;
+  retries: number;
+  verdict?: string;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "gemini_call", ...data });
+}
+
+export function recordDiscoveryCompleted(data: {
+  specialist: string;
+  approach_count: number;
+  variant_count: number;
+  question_count: number;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "discovery_completed", ...data });
+}
+
+export function recordDocumentationExtracted(data: {
+  prompt_num: number;
+  variant?: string | null;
+  files_affected: number;
+  plan_name?: string;
+}): void {
+  recordMetric({ type: "documentation_extracted", ...data });
+}

package/.claude/envoy/src/lib/paths.ts

@@ -0,0 +1,130 @@
+/**
+ * Plan directory path utilities.
+ */
+
+import { mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { getPlanDir } from "./git.js";
+import { logInfo } from "./observability.js";
+
+/**
+ * Plan directory structure subdirectories.
+ */
+const PLAN_SUBDIRS = [
+  "prompts",
+  "findings",
+  "findings/_archive",
+  "design",
+  "user_feedback",
+];
+
+/**
+ * Ensure the plan directory exists with all required subdirectories.
+ * Creates on demand if not present.
+ *
+ * @returns The plan directory path
+ */
+export function ensurePlanDir(): string {
+  const planDir = getPlanDir();
+
+  if (!existsSync(planDir)) {
+    logInfo("plans.create_dir", { path: planDir });
+    mkdirSync(planDir, { recursive: true });
+
+    // Create subdirectories
+    for (const subdir of PLAN_SUBDIRS) {
+      const subdirPath = join(planDir, subdir);
+      mkdirSync(subdirPath, { recursive: true });
+    }
+  }
+
+  return planDir;
+}
+
+/**
+ * Get paths for all standard plan files.
+ */
+export function getPlanPaths(): {
+  planDir: string;
+  plan: string;
+  userInput: string;
+  curator: string;
+  summary: string;
+  prompts: string;
+  findings: string;
+  design: string;
+  userFeedback: string;
+} {
+  const planDir = getPlanDir();
+  return {
+    planDir,
+    plan: join(planDir, "plan.md"),
+    userInput: join(planDir, "user_input.md"),
+    curator: join(planDir, "curator.md"),
+    summary: join(planDir, "summary.md"),
+    prompts: join(planDir, "prompts"),
+    findings: join(planDir, "findings"),
+    design: join(planDir, "design"),
+    userFeedback: join(planDir, "user_feedback"),
+  };
+}
+
+/**
+ * Get the prompt file path for a given prompt number and optional variant.
+ */
+export function getPromptPath(number: number, variant?: string | null): string {
+  const paths = getPlanPaths();
+  const filename = variant ? `${number}_${variant}.md` : `${number}.md`;
+  return join(paths.prompts, filename);
+}
+
+/**
+ * Get the findings file path for a given specialist.
+ */
+export function getFindingsPath(specialist: string): string {
+  const paths = getPlanPaths();
+  return join(paths.findings, `${specialist}.yaml`);
+}
+
+/**
+ * Get the user feedback file path (ephemeral, created by block commands).
+ */
+export function getUserFeedbackPath(id: string, ext: string = ".yaml"): string {
+  const paths = getPlanPaths();
+  return join(paths.userFeedback, `${id}${ext}`);
+}
+
+/**
+ * Check if a plan directory exists for the current branch.
+ */
+export function planExists(): boolean {
+  return existsSync(getPlanDir());
+}
+
+/**
+ * Get prompt identifier string (e.g., "1", "2_A", "3_B").
+ */
+export function getPromptId(number: number, variant: string | null): string {
+  return variant ? `${number}_${variant}` : `${number}`;
+}
+
+/**
+ * Parse prompt identifier string into number and variant.
+ */
+export function parsePromptId(id: string): { number: number; variant: string | null } {
+  const match = id.match(/^(\d+)(?:_([A-Z]))?$/);
+  if (!match) {
+    throw new Error(`Invalid prompt identifier: ${id}`);
+  }
+  return {
+    number: parseInt(match[1], 10),
+    variant: match[2] || null,
+  };
+}
+
+/**
+ * Get approach ID string: "{number}" or "{number}_{variant}"
+ */
+export function getApproachId(number: number, variant: string | null): string {
+  return variant ? `${number}_${variant}` : `${number}`;
+}

package/.claude/envoy/src/lib/plan-io.ts

@@ -0,0 +1,117 @@
+/**
+ * Plan file I/O operations.
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "fs";
+import { getBranch } from "./git.js";
+import { ensurePlanDir, getPlanPaths } from "./paths.js";
+import { readMarkdownFile, writeMarkdownWithFrontMatter } from "./markdown.js";
+
+export interface PlanFrontMatter {
+  stage: "draft" | "in_progress" | "completed";
+  branch_name: string;
+  audits: Array<{
+    review_context: string;
+    decision: "approved" | "needs_clarification" | "rejected";
+    total_questions: number;
+    were_changes_suggested: boolean;
+  }>;
+  reviews: Array<{
+    review_context: string;
+    decision: "approved" | "needs_changes" | "rejected";
+    total_questions: number;
+    were_changes_suggested: boolean;
+  }>;
+}
+
+/**
+ * Read plan.md and return parsed front matter + content.
+ */
+export function readPlan(): { frontMatter: PlanFrontMatter; content: string } | null {
+  const paths = getPlanPaths();
+  const result = readMarkdownFile(paths.plan);
+  if (!result) return null;
+  return {
+    frontMatter: result.frontMatter as unknown as PlanFrontMatter,
+    content: result.content,
+  };
+}
+
+/**
+ * Write plan.md with front matter and content.
+ */
+export function writePlan(frontMatter: Partial<PlanFrontMatter>, content: string): void {
+  const paths = getPlanPaths();
+  ensurePlanDir();
+
+  const defaults: PlanFrontMatter = {
+    stage: "draft",
+    branch_name: getBranch(),
+    audits: [],
+    reviews: [],
+  };
+
+  const merged = { ...defaults, ...frontMatter };
+  writeMarkdownWithFrontMatter(paths.plan, merged, content);
+}
+
+/**
+ * Update plan stage without modifying content.
+ */
+export function updatePlanStage(stage: PlanFrontMatter["stage"]): void {
+  const plan = readPlan();
+  if (!plan) return;
+
+  const updatedFrontMatter = { ...plan.frontMatter, stage };
+  const paths = getPlanPaths();
+  writeMarkdownWithFrontMatter(paths.plan, updatedFrontMatter, plan.content);
+}
+
+/**
+ * Read user_input.md content.
+ */
+export function readUserInput(): string | null {
+  const paths = getPlanPaths();
+  if (!existsSync(paths.userInput)) {
+    return null;
+  }
+  return readFileSync(paths.userInput, "utf-8");
+}
+
+/**
+ * Append content to user_input.md.
+ */
+export function appendUserInput(content: string): void {
+  const paths = getPlanPaths();
+  ensurePlanDir();
+
+  // Initialize file if it doesn't exist
+  if (!existsSync(paths.userInput)) {
+    writeFileSync(paths.userInput, "# User Input Log\n\n", "utf-8");
+  }
+
+  // Append with timestamp
+  const timestamp = new Date().toISOString();
+  const entry = `\n---\n**${timestamp}**\n\n${content}\n`;
+  appendFileSync(paths.userInput, entry, "utf-8");
+}
+
+/**
+ * Read summary.md content.
+ */
+export function readSummary(): string | null {
+  const paths = getPlanPaths();
+  if (!existsSync(paths.summary)) {
+    return null;
+  }
+  return readFileSync(paths.summary, "utf-8");
+}
+
+/**
+ * Write summary.md content.
+ */
+export function writeSummary(content: string): void {
+  const paths = getPlanPaths();
+  ensurePlanDir();
+  writeFileSync(paths.summary, content, "utf-8");
+}