guild-agents 0.3.1 → 1.0.0

package/src/utils/trace.js

@@ -0,0 +1,400 @@
+/**
+ * trace.js — Structured trace file utilities for Guild workflows.
+ *
+ * Provides pure rendering functions (renderTrace, renderStep, renderSummary)
+ * that take data in and return strings out, with zero I/O. Also provides
+ * I/O functions (createTrace, finalizeTrace, listTraces, cleanTraces) for
+ * file operations on `.claude/guild/traces/`.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, unlinkSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { estimateTokens } from './learnings.js';
+
+/** @typedef {'default' | 'verbose' | 'debug'} TraceLevel */
+
+/**
+ * @typedef {Object} TraceContext
+ * @property {string} filePath - Absolute path to the trace file
+ * @property {string} workflow - Skill/workflow name
+ * @property {TraceLevel} level - Logging level
+ * @property {Date} started - Workflow start time
+ * @property {Array<TraceStep>} steps - Recorded steps
+ * @property {number} totalTokens - Running token total
+ */
+
+/**
+ * @typedef {Object} TraceStep
+ * @property {string} role - Agent role (e.g. 'tech-lead')
+ * @property {string} intent - Brief description of what the agent was asked
+ * @property {string} tier - Tier assignment (e.g. 'reasoning', 'execution')
+ * @property {string} model - Resolved model ID
+ * @property {boolean} fallback - Whether a fallback model was used
+ * @property {string} started - ISO-8601 timestamp
+ * @property {number} duration - Duration in seconds
+ * @property {number} tokens - Token count for this step
+ * @property {string} result - 'pass', 'fail', or 'skip'
+ * @property {string} [decision] - Verbose+: why this model was chosen
+ * @property {string} [reasoning] - Verbose+: agent's self-reported reasoning
+ * @property {string} [fullPrompt] - Debug only: complete prompt sent
+ * @property {string} [fullResponse] - Debug only: complete response received
+ */
+
+/**
+ * @typedef {Object} TraceSummary
+ * @property {string} result - 'pass' or 'fail'
+ * @property {boolean} testsPass - Whether tests passed
+ * @property {boolean} lintPass - Whether lint passed
+ */
+
+/**
+ * Resolves the trace level from CLI option flags.
+ * If both verbose and debug are set, debug wins (highest level).
+ * @param {Object} [options] - CLI options
+ * @param {boolean} [options.verbose] - Enable verbose logging
+ * @param {boolean} [options.debug] - Enable debug logging
+ * @returns {TraceLevel}
+ */
+export function resolveTraceLevel(options = {}) {
+  if (options.debug) return 'debug';
+  if (options.verbose) return 'verbose';
+  return 'default';
+}
+
+/**
+ * Formats a duration in milliseconds to HH:MM:SS string.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted as HH:MM:SS
+ */
+export function formatDuration(ms) {
+  const totalSeconds = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return [
+    String(hours).padStart(2, '0'),
+    String(minutes).padStart(2, '0'),
+    String(seconds).padStart(2, '0'),
+  ].join(':');
+}
+
+/**
+ * Creates a new trace context object. Creates the traces directory if needed.
+ * Does NOT write anything to disk — writing happens on finalize (lazy).
+ * @param {string} workflowName - Skill/workflow name (e.g. 'build-feature')
+ * @param {TraceLevel} level - Logging level
+ * @param {string} [tracesDir] - Directory for trace files (default: .claude/guild/traces/)
+ * @returns {TraceContext}
+ */
+export function createTrace(workflowName, level, tracesDir) {
+  const dir = tracesDir || join('.claude', 'guild', 'traces');
+  mkdirSync(dir, { recursive: true });
+
+  // Ensure traces directory is gitignored (local-only artifacts)
+  const gitignorePath = join(dir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, '*\n!.gitignore\n', 'utf8');
+  }
+
+  const now = new Date();
+  const timestamp = now.toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}Z$/, '')
+    .replace('T', 'T');
+  const filename = `guild-trace-${timestamp}.md`;
+
+  return {
+    filePath: join(dir, filename),
+    workflow: workflowName,
+    level,
+    started: now,
+    steps: [],
+    totalTokens: 0,
+  };
+}
+
+/**
+ * Records a step in the trace context. Pushes step data and updates token total.
+ * @param {TraceContext} traceCtx - The trace context from createTrace
+ * @param {TraceStep} stepData - The step data to record
+ * @returns {TraceContext} The same context (for chaining)
+ */
+export function recordStep(traceCtx, stepData) {
+  traceCtx.steps.push(stepData);
+  traceCtx.totalTokens += stepData.tokens || 0;
+  return traceCtx;
+}
+
+/**
+ * Renders a single step section as Markdown. PURE function — no I/O.
+ * Only includes decision/reasoning for verbose+. Only includes
+ * fullPrompt/fullResponse for debug level.
+ * @param {TraceStep} step - Step data
+ * @param {number} stepNumber - 1-based step index
+ * @param {TraceLevel} level - Current trace level
+ * @returns {string} Markdown string for the step
+ */
+export function renderStep(step, stepNumber, level) {
+  const lines = [];
+  lines.push(`### Step ${stepNumber} — ${step.role}: ${step.intent}`);
+  lines.push('');
+  lines.push('| Field | Value |');
+  lines.push('|-------|-------|');
+  lines.push(`| Tier | ${step.tier} |`);
+  lines.push(`| Model | ${step.model} |`);
+  lines.push(`| Fallback | ${step.fallback ? 'yes' : 'no'} |`);
+  lines.push(`| Started | ${step.started} |`);
+  lines.push(`| Duration | ${step.duration}s |`);
+  lines.push(`| Tokens | ${step.tokens} |`);
+  lines.push(`| Result | ${step.result} |`);
+
+  if ((level === 'verbose' || level === 'debug') && step.decision) {
+    lines.push('');
+    lines.push(`**Decision:** ${step.decision}`);
+  }
+  if ((level === 'verbose' || level === 'debug') && step.reasoning) {
+    lines.push(`**Reasoning:** ${step.reasoning}`);
+  }
+
+  if (level === 'debug' && step.fullPrompt) {
+    lines.push('');
+    lines.push('<details>');
+    lines.push('<summary>Full prompt</summary>');
+    lines.push('');
+    lines.push(step.fullPrompt);
+    lines.push('');
+    lines.push('</details>');
+  }
+
+  if (level === 'debug' && step.fullResponse) {
+    lines.push('');
+    lines.push('<details>');
+    lines.push('<summary>Full response</summary>');
+    lines.push('');
+    lines.push(step.fullResponse);
+    lines.push('');
+    lines.push('</details>');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Renders the summary section as Markdown. PURE function — no I/O.
+ * @param {TraceSummary} summary - Summary data
+ * @param {number} totalTokens - Total tokens across all steps
+ * @param {string} duration - Formatted duration string (HH:MM:SS)
+ * @returns {string} Markdown string for the summary
+ */
+export function renderSummary(summary, totalTokens, duration) {
+  const lines = [];
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- **Result**: ${summary.result}`);
+  lines.push(`- **Tests**: ${summary.testsPass ? 'pass' : 'fail'}`);
+  lines.push(`- **Lint**: ${summary.lintPass ? 'pass' : 'fail'}`);
+  lines.push(`- **Total tokens**: ${totalTokens}`);
+  lines.push(`- **Duration**: ${duration}`);
+  return lines.join('\n');
+}
+
+/**
+ * Renders a complete trace as a Markdown string. PURE function — no I/O.
+ * @param {TraceContext} traceCtx - Trace context with all steps
+ * @param {TraceSummary} summary - Final summary data
+ * @param {Date} [finished] - Finish time (default: new Date())
+ * @returns {string} Complete Markdown content
+ */
+export function renderTrace(traceCtx, summary, finished) {
+  const end = finished || new Date();
+  const durationMs = end.getTime() - traceCtx.started.getTime();
+  const durationStr = formatDuration(durationMs);
+
+  const lines = [];
+
+  // Header
+  lines.push(`# Guild Trace — ${traceCtx.workflow}`);
+  lines.push('');
+  lines.push(`> Level: ${traceCtx.level}`);
+  lines.push(`> Started: ${traceCtx.started.toISOString()}`);
+  lines.push(`> Finished: ${end.toISOString()}`);
+  lines.push(`> Duration: ${durationStr}`);
+  lines.push(`> Total tokens: ${traceCtx.totalTokens}`);
+  lines.push(`> Result: ${summary.result}`);
+
+  // Steps
+  lines.push('');
+  lines.push('## Steps');
+
+  for (let i = 0; i < traceCtx.steps.length; i++) {
+    lines.push('');
+    lines.push(renderStep(traceCtx.steps[i], i + 1, traceCtx.level));
+  }
+
+  // Summary
+  lines.push('');
+  lines.push(renderSummary(summary, traceCtx.totalTokens, durationStr));
+
+  return lines.join('\n');
+}
+
+/** Maximum token budget for execution summaries. */
+export const EXECUTION_SUMMARY_BUDGET = 500;
+
+/**
+ * Generates a compact execution summary for context injection.
+ * Designed for the learnings-extractor agent which runs on tier routine (Haiku).
+ * Pure function — no I/O.
+ *
+ * Dependency direction: trace.js imports estimateTokens from learnings.js.
+ * learnings.js must NOT import from trace.js.
+ *
+ * @param {TraceContext} traceCtx - The trace context with recorded steps
+ * @param {TraceSummary} summary - Final summary data (result, testsPass, lintPass)
+ * @param {Date} [finished] - Finish time (default: new Date())
+ * @returns {string} Plain text summary, estimated at <= 500 tokens
+ */
+export function generateExecutionSummary(traceCtx, summary, finished) {
+  const end = finished || new Date();
+  const durationMs = end.getTime() - traceCtx.started.getTime();
+  const durationStr = formatDuration(durationMs);
+
+  const headerLines = [
+    `Workflow: ${traceCtx.workflow}`,
+    `Result: ${summary.result}`,
+    `Steps: ${traceCtx.steps.length}`,
+    `Tokens: ${traceCtx.totalTokens}`,
+    `Duration: ${durationStr}`,
+  ];
+
+  const header = headerLines.join('\n') + '\n';
+
+  if (traceCtx.steps.length === 0) {
+    return header;
+  }
+
+  const stepLines = traceCtx.steps.map((step, i) =>
+    `${i + 1}. ${step.role}: ${step.intent} → ${step.result} (${step.tokens} tokens, ${step.duration}s)`
+  );
+
+  // Try full summary first
+  const full = header + '\n' + stepLines.join('\n');
+  if (estimateTokens(full) <= EXECUTION_SUMMARY_BUDGET) {
+    return full;
+  }
+
+  // Truncate step lines until within budget
+  const included = [];
+  for (let i = 0; i < stepLines.length; i++) {
+    const omissionNotice = `\n... (${traceCtx.steps.length - (i + 1)} steps omitted)`;
+    const candidate = header + '\n' + [...included, stepLines[i]].join('\n') + omissionNotice;
+    if (estimateTokens(candidate) > EXECUTION_SUMMARY_BUDGET) {
+      break;
+    }
+    included.push(stepLines[i]);
+  }
+
+  const omitted = traceCtx.steps.length - included.length;
+  if (included.length === 0) {
+    return header + `\n... (${omitted} steps omitted)`;
+  }
+  return header + '\n' + included.join('\n') + `\n... (${omitted} steps omitted)`;
+}
+
+/**
+ * Finalizes a trace: computes duration, renders markdown, writes to disk.
+ * @param {TraceContext} traceCtx - The trace context
+ * @param {TraceSummary} summary - Final summary data (result, testsPass, lintPass)
+ * @returns {{ filePath: string, duration: number, totalTokens: number, executionSummary: string }}
+ */
+export function finalizeTrace(traceCtx, summary) {
+  const finished = new Date();
+  const durationMs = finished.getTime() - traceCtx.started.getTime();
+  const content = renderTrace(traceCtx, summary, finished);
+
+  // Ensure directory exists (may have been cleaned between create and finalize)
+  const dir = dirname(traceCtx.filePath);
+  mkdirSync(dir, { recursive: true });
+
+  writeFileSync(traceCtx.filePath, content, 'utf8');
+
+  const executionSummary = generateExecutionSummary(traceCtx, summary, finished);
+
+  return {
+    filePath: traceCtx.filePath,
+    duration: durationMs,
+    totalTokens: traceCtx.totalTokens,
+    executionSummary,
+  };
+}
+
+/**
+ * Lists all trace files in the traces directory, sorted newest first.
+ * Parses the header of each file to extract metadata.
+ * Returns empty array if directory does not exist (no throw).
+ * @param {string} [tracesDir] - Directory to scan (default: .claude/guild/traces/)
+ * @returns {Array<{ filePath: string, workflow: string, date: string, level: string, result: string }>}
+ */
+export function listTraces(tracesDir) {
+  const dir = tracesDir || join('.claude', 'guild', 'traces');
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir)
+    .filter(f => f.startsWith('guild-trace-') && f.endsWith('.md'))
+    .sort()
+    .reverse();
+
+  return files.map(filename => {
+    const filePath = join(dir, filename);
+    const head = readFileSync(filePath, 'utf8').split('\n').slice(0, 10).join('\n');
+
+    const workflowMatch = head.match(/^# Guild Trace — (.+)$/m);
+    const levelMatch = head.match(/^> Level: (.+)$/m);
+    const resultMatch = head.match(/^> Result: (.+)$/m);
+    const startedMatch = head.match(/^> Started: (.+)$/m);
+
+    return {
+      filePath,
+      workflow: workflowMatch ? workflowMatch[1] : 'unknown',
+      date: startedMatch ? startedMatch[1] : 'unknown',
+      level: levelMatch ? levelMatch[1] : 'default',
+      result: resultMatch ? resultMatch[1] : 'unknown',
+    };
+  });
+}
+
+/**
+ * Deletes trace files older than maxAgeDays. If maxAgeDays is 0, deletes ALL traces.
+ * Returns count of deleted files. Returns 0 if directory does not exist (no throw).
+ * @param {number} maxAgeDays - Traces older than this many days are deleted (0 = delete all)
+ * @param {string} [tracesDir] - Directory to clean (default: .claude/guild/traces/)
+ * @returns {number} Count of deleted files
+ */
+export function cleanTraces(maxAgeDays, tracesDir) {
+  const dir = tracesDir || join('.claude', 'guild', 'traces');
+  if (!existsSync(dir)) return 0;
+
+  const files = readdirSync(dir)
+    .filter(f => f.startsWith('guild-trace-') && f.endsWith('.md'));
+
+  const now = Date.now();
+  const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+  let deleted = 0;
+
+  for (const filename of files) {
+    const filePath = join(dir, filename);
+    if (maxAgeDays === 0) {
+      unlinkSync(filePath);
+      deleted++;
+    } else {
+      const stat = statSync(filePath);
+      const ageMs = now - stat.mtimeMs;
+      if (ageMs > maxAgeMs) {
+        unlinkSync(filePath);
+        deleted++;
+      }
+    }
+  }
+
+  return deleted;
+}

package/src/utils/version.js

@@ -0,0 +1,90 @@
+/**
+ * version.js — Version detection and computation utilities for Guild CLI.
+ *
+ * Provides pure functions for parsing semver strings, detecting pre-release
+ * channels, computing next snapshot/beta/stable versions, and generating
+ * user-facing warning messages.
+ */
+
+/**
+ * Parses a semver string into its components.
+ * @param {string} version - The version string from package.json
+ * @returns {{ base: string, channel: string, prerelease: string|null }}
+ */
+export function parseVersion(version) {
+  const match = version.match(/^(\d+\.\d+\.\d+)(?:-(.+))?$/);
+  if (!match) {
+    return { base: version, channel: 'stable', prerelease: null };
+  }
+
+  const base = match[1];
+  const prerelease = match[2] || null;
+
+  let channel = 'stable';
+  if (prerelease?.startsWith('beta')) channel = 'beta';
+  else if (prerelease?.startsWith('snapshot')) channel = 'snapshot';
+
+  return { base, channel, prerelease };
+}
+
+/**
+ * Returns a warning string for pre-release versions, or null for stable.
+ * @param {string} version
+ * @returns {string|null}
+ */
+export function getPreReleaseWarning(version) {
+  const { channel } = parseVersion(version);
+
+  if (channel === 'snapshot') {
+    return 'Snapshot build: for development/testing only';
+  }
+  if (channel === 'beta') {
+    return 'Pre-release: may contain experimental changes';
+  }
+  return null;
+}
+
+/**
+ * Computes the next snapshot version.
+ * @param {string} currentVersion - e.g. "0.3.1" or "0.4.0-snapshot.20260225.1"
+ * @param {Date} [now=new Date()] - injectable for testing
+ * @returns {string} - e.g. "0.3.1-snapshot.20260225.1"
+ */
+export function computeSnapshotVersion(currentVersion, now = new Date()) {
+  const baseVersion = currentVersion.replace(/-.*$/, '');
+  const dateStr = now.toISOString().slice(0, 10).replace(/-/g, '');
+
+  let buildNum = 1;
+  const currentPrerelease = currentVersion.match(/-snapshot\.(\d+)\.(\d+)$/);
+  if (currentPrerelease && currentPrerelease[1] === dateStr) {
+    buildNum = parseInt(currentPrerelease[2], 10) + 1;
+  }
+
+  return `${baseVersion}-snapshot.${dateStr}.${buildNum}`;
+}
+
+/**
+ * Computes the next beta version.
+ * @param {string} currentVersion - e.g. "0.4.0" or "0.4.0-beta.2"
+ * @returns {string} - e.g. "0.4.0-beta.1" or "0.4.0-beta.3"
+ */
+export function computeBetaVersion(currentVersion) {
+  const baseVersion = currentVersion.replace(/-.*$/, '');
+
+  let betaNum = 1;
+  const currentBeta = currentVersion.match(/-beta\.(\d+)$/);
+  if (currentBeta) {
+    betaNum = parseInt(currentBeta[1], 10) + 1;
+  }
+
+  return `${baseVersion}-beta.${betaNum}`;
+}
+
+/**
+ * Computes the stable version by stripping any prerelease suffix.
+ * @param {string} currentVersion - e.g. "0.4.0-beta.3"
+ * @returns {string} - e.g. "0.4.0"
+ */
+export function computeStableVersion(currentVersion) {
+  return currentVersion.replace(/-.*$/, '');
+}