terramend 0.2.0

package/src/utils/log.ts

@@ -0,0 +1,432 @@
+/**
+ * Logging utilities that work well in both local and GitHub Actions environments
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as core from "@actions/core";
+import { table } from "table";
+import { type AgentUsage, formatCostUsd } from "#app/agents/shared";
+import { isGitHubActions, isInsideDocker } from "#app/utils/globals";
+
+// --- log prefix via AsyncLocalStorage ---
+
+type LogContext = { prefix: string };
+
+const logContext = new AsyncLocalStorage<LogContext>();
+
+const MAGENTA = "\x1b[35m";
+const RESET = "\x1b[0m";
+
+/** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
+export function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T> {
+  return logContext.run({ prefix }, fn);
+}
+
+function prefixLines(message: string): string {
+  const ctx = logContext.getStore();
+  if (!ctx) return message;
+  const colored = `${MAGENTA}${ctx.prefix}${RESET} `;
+  return message
+    .split("\n")
+    .map((line) => `${colored}${line}`)
+    .join("\n");
+}
+
+/** plain-text prefix (no ANSI) for GitHub Actions group names */
+function prefixPlain(name: string): string {
+  const ctx = logContext.getStore();
+  if (!ctx) return name;
+  return `${ctx.prefix} ${name}`;
+}
+
+// --- log sink ----------------------------------------------------------------
+
+type LogSink = "actions" | "stderr";
+
+let sink: LogSink = "actions";
+
+/**
+ * Route ALL log output to stderr instead of `@actions/core` (which writes to
+ * stdout). Required before starting a stdio MCP server: stdout is the JSON-RPC
+ * channel there, and a single stray diagnostic line corrupts the framing.
+ * The GitHub Action path never calls this — its sink stays `@actions/core`.
+ */
+export function setLogSink(next: LogSink): void {
+  sink = next;
+}
+
+/** info-level line via the active sink. */
+function emitInfo(line: string): void {
+  if (sink === "stderr") {
+    process.stderr.write(`${line}\n`);
+    return;
+  }
+  core.info(line);
+}
+
+const isRunnerDebugEnabled = () => core.isDebug();
+
+const isLocalDebugEnabled = () =>
+  process.env.LOG_LEVEL === "debug" || process.env.ACTIONS_STEP_DEBUG === "true";
+
+const isDebugEnabled = () => isLocalDebugEnabled() || isRunnerDebugEnabled();
+
+/** timestamp prefix for debug mode — empty string when debug is off */
+function ts(): string {
+  return isDebugEnabled() ? `[${new Date().toISOString()}] ` : "";
+}
+
+/**
+ * Format arguments into a single string for logging
+ */
+function formatArgs(args: unknown[]): string {
+  return args
+    .map((arg) => {
+      if (typeof arg === "string") return arg;
+      if (arg instanceof Error) return `${arg.message}\n${arg.stack}`;
+      return JSON.stringify(arg);
+    })
+    .join(" ");
+}
+
+/**
+ * Start a collapsed group (GitHub Actions) or regular group (local)
+ */
+function startGroup(name: string): void {
+  const prefixed = prefixPlain(name);
+  if (sink === "stderr") {
+    emitInfo(`▼ ${prefixed}`);
+    return;
+  }
+  if (isGitHubActions) {
+    core.startGroup(prefixed);
+  } else {
+    console.group(prefixed);
+  }
+}
+
+/**
+ * End a collapsed group
+ */
+function endGroup(): void {
+  if (sink === "stderr") return;
+  if (isGitHubActions) {
+    core.endGroup();
+  } else {
+    console.groupEnd();
+  }
+}
+
+/**
+ * Run a callback within a collapsed group
+ */
+function group(name: string, fn: () => void): void {
+  startGroup(name);
+  fn();
+  endGroup();
+}
+
+/**
+ * Print a formatted box with text (for console output)
+ */
+function boxString(
+  text: string,
+  options?: {
+    title?: string;
+    maxWidth?: number;
+    indent?: string;
+    padding?: number;
+  },
+): string {
+  const { title, maxWidth = 80, indent = "", padding = 1 } = options || {};
+
+  const lines = text.trim().split("\n");
+  const wrappedLines: string[] = [];
+
+  for (const line of lines) {
+    if (line.length <= maxWidth - padding * 2) {
+      wrappedLines.push(line);
+    } else {
+      const words = line.split(" ");
+      let currentLine = "";
+
+      for (const word of words) {
+        const testLine = currentLine ? `${currentLine} ${word}` : word;
+        if (testLine.length <= maxWidth - padding * 2) {
+          currentLine = testLine;
+        } else {
+          if (currentLine) {
+            wrappedLines.push(currentLine);
+            currentLine = "";
+          }
+          // wrap long words by breaking them into chunks
+          const maxLineLength = maxWidth - padding * 2;
+          let remainingWord = word;
+          while (remainingWord.length > maxLineLength) {
+            wrappedLines.push(remainingWord.substring(0, maxLineLength));
+            remainingWord = remainingWord.substring(maxLineLength);
+          }
+          currentLine = remainingWord;
+        }
+      }
+
+      if (currentLine) {
+        wrappedLines.push(currentLine);
+      }
+    }
+  }
+
+  const maxLineLength = Math.max(...wrappedLines.map((line) => line.length));
+  const contentBoxWidth = maxLineLength + padding * 2;
+
+  // ensure box width is at least as wide as the title line when title exists
+  const titleLineLength = title ? ` ${title} `.length : 0;
+  const boxWidth = Math.max(contentBoxWidth, titleLineLength);
+
+  let result = "";
+
+  if (title) {
+    const titleLine = ` ${title} `;
+    const titlePadding = Math.max(0, boxWidth - titleLine.length);
+    result += `${indent}┌${titleLine}${"─".repeat(titlePadding)}┐\n`;
+  }
+
+  if (!title) {
+    result += `${indent}┌${"─".repeat(boxWidth)}┐\n`;
+  }
+
+  for (const line of wrappedLines) {
+    const paddedLine = line.padEnd(maxLineLength);
+    result += `${indent}│${" ".repeat(padding)}${paddedLine}${" ".repeat(padding)}│\n`;
+  }
+
+  result += `${indent}└${"─".repeat(boxWidth)}┘`;
+
+  return result;
+}
+
+/**
+ * Print a formatted box with text
+ */
+function box(
+  text: string,
+  options?: {
+    title?: string;
+    maxWidth?: number;
+  },
+): void {
+  const boxContent = boxString(text, options);
+  emitInfo(prefixLines(boxContent));
+}
+
+/**
+ * Overwrite the job summary with the given text.
+ * Skips if:
+ * - Not in GitHub Actions
+ * - Running inside Docker (CI tests inherit host env vars but can't access host paths)
+ * - GITHUB_STEP_SUMMARY not set
+ */
+export async function writeSummary(text: string): Promise<void> {
+  if (!isGitHubActions) return;
+
+  // CI tests run in Docker with GITHUB_ACTIONS=true inherited from host,
+  // but the GITHUB_STEP_SUMMARY path points to a host filesystem location
+  // that doesn't exist inside the container
+  if (isInsideDocker) return;
+
+  if (!process.env.GITHUB_STEP_SUMMARY) return;
+
+  await core.summary.addRaw(text).write({ overwrite: true });
+}
+
+/**
+ * Print a formatted table using the table package
+ */
+function printTable(
+  rows: Array<Array<{ data: string; header?: boolean } | string>>,
+  options?: {
+    title?: string;
+  },
+): void {
+  const { title } = options || {};
+
+  // Convert rows to string arrays for the table package
+  const tableData = rows.map((row) =>
+    row.map((cell) => {
+      if (typeof cell === "string") {
+        return cell;
+      }
+      return cell.data;
+    }),
+  );
+
+  const formatted = table(tableData);
+
+  if (title) {
+    emitInfo(prefixLines(`\n${title}`));
+  }
+  emitInfo(prefixLines(`\n${formatted}\n`));
+}
+
+/**
+ * Print a separator line
+ */
+function separator(length: number = 50): void {
+  const separatorText = "─".repeat(length);
+  emitInfo(prefixLines(separatorText));
+}
+
+/**
+ * Main logging utility object - import this once and access all utilities
+ */
+export const log = {
+  /** Print info message */
+  info: (...args: unknown[]): void => {
+    emitInfo(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print a warning message. Use only for warnings that should be displayed in the job summary. */
+  warning: (...args: unknown[]): void => {
+    if (sink === "stderr") {
+      emitInfo(prefixLines(`${ts()}warning: ${formatArgs(args)}`));
+      return;
+    }
+    core.warning(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print an error message. Use only for errors that should be displayed in the job summary. */
+  error: (...args: unknown[]): void => {
+    if (sink === "stderr") {
+      emitInfo(prefixLines(`${ts()}error: ${formatArgs(args)}`));
+      return;
+    }
+    core.error(prefixLines(`${ts()}${formatArgs(args)}`));
+  },
+
+  /** Print success message */
+  success: (...args: unknown[]): void => {
+    emitInfo(prefixLines(`${ts()}» ${formatArgs(args)}`));
+  },
+
+  /** Print debug message (only when debug mode is enabled) */
+  debug: (...args: unknown[]): void => {
+    if (sink === "actions" && isRunnerDebugEnabled()) {
+      core.debug(prefixLines(formatArgs(args)));
+      return;
+    }
+    if (isLocalDebugEnabled()) {
+      emitInfo(prefixLines(`${ts()}[DEBUG] ${formatArgs(args)}`));
+    }
+  },
+
+  /** Print a formatted box with text */
+  box,
+
+  /** Print a formatted table using the table package */
+  table: printTable,
+
+  /** Print a separator line */
+  separator,
+
+  /** Start a collapsed group (GitHub Actions) or regular group (local) */
+  startGroup,
+
+  /** End a collapsed group */
+  endGroup,
+
+  /** Run a callback within a collapsed group */
+  group,
+
+  /** Log tool call information to console with formatted output */
+  toolCall: ({ toolName, input }: { toolName: string; input: unknown }): void => {
+    const inputFormatted = formatJsonValue(input);
+    const output = inputFormatted !== "{}" ? `» ${toolName}(${inputFormatted})` : `» ${toolName}()`;
+
+    log.info(output.trimEnd());
+  },
+};
+
+/**
+ * Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
+ */
+export function formatJsonValue(value: unknown): string {
+  const compact = JSON.stringify(value);
+  return compact.length > 80 || compact.includes("\n") ? JSON.stringify(value, null, 2) : compact;
+}
+
+/**
+ * Format a multi-line string with proper indentation for tool call output
+ * First line has the label, subsequent lines are indented 4 spaces
+ */
+export function formatIndentedField(label: string, content: string): string {
+  if (!content.includes("\n")) {
+    return `  ${label}: ${content}\n`;
+  }
+
+  const lines = content.split("\n");
+  let formatted = `  ${label}: ${lines[0]}\n`;
+  for (let i = 1; i < lines.length; i++) {
+    formatted += `    ${lines[i]}\n`;
+  }
+  return formatted;
+}
+
+/**
+ * format aggregated usage data as a markdown table for the GitHub step summary.
+ *
+ * columns mirror the per-run stdout token table emitted by `logTokenTable`
+ * (Input / Cache Read / Cache Write / Output / Total / Cost ($)) so the job
+ * summary and the in-run logs can be compared row-for-row.
+ *
+ * notes:
+ *   - `AgentUsage.inputTokens` is the sum of non-cached input + cache read
+ *     + cache write (set that way by both agent harnesses' `buildUsage`),
+ *     so the non-cached Input column is recovered by subtracting cache fields.
+ *   - `costUsd` is sourced from models.dev (OpenCode) or `total_cost_usd`
+ *     (Claude CLI). absent rows show `—` so per-agent coverage is obvious.
+ */
+export function formatUsageSummary(entries: AgentUsage[]): string {
+  if (entries.length === 0) return "";
+
+  const header = "| Agent | Input | Cache Read | Cache Write | Output | Total | Cost ($) |";
+  const separatorRow = "| --- | ---: | ---: | ---: | ---: | ---: | ---: |";
+  const fmt = (n: number) => n.toLocaleString("en-US");
+
+  const nonCachedInput = (e: AgentUsage): number =>
+    Math.max(0, e.inputTokens - (e.cacheReadTokens ?? 0) - (e.cacheWriteTokens ?? 0));
+  const totalFor = (e: AgentUsage): number =>
+    nonCachedInput(e) + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0) + e.outputTokens;
+  const costCell = (e: AgentUsage): string =>
+    typeof e.costUsd === "number" && e.costUsd > 0 ? formatCostUsd(e.costUsd) : "—";
+
+  const rows = entries.map(
+    (e) =>
+      `| ${e.agent} | ${fmt(nonCachedInput(e))} | ${fmt(e.cacheReadTokens ?? 0)} | ${fmt(e.cacheWriteTokens ?? 0)} | ${fmt(e.outputTokens)} | ${fmt(totalFor(e))} | ${costCell(e)} |`,
+  );
+
+  const totalsRows: string[] = [];
+  if (entries.length > 1) {
+    const totalInput = entries.reduce((sum, e) => sum + nonCachedInput(e), 0);
+    const totalOutput = entries.reduce((sum, e) => sum + e.outputTokens, 0);
+    const totalCacheRead = entries.reduce((sum, e) => sum + (e.cacheReadTokens ?? 0), 0);
+    const totalCacheWrite = entries.reduce((sum, e) => sum + (e.cacheWriteTokens ?? 0), 0);
+    const grandTotal = totalInput + totalCacheRead + totalCacheWrite + totalOutput;
+    const totalCostUsd = entries.reduce((sum, e) => sum + (e.costUsd ?? 0), 0);
+    const totalCostCell = totalCostUsd > 0 ? `**${formatCostUsd(totalCostUsd)}**` : "—";
+    totalsRows.push(
+      `| **Total** | **${fmt(totalInput)}** | **${fmt(totalCacheRead)}** | **${fmt(totalCacheWrite)}** | **${fmt(totalOutput)}** | **${fmt(grandTotal)}** | ${totalCostCell} |`,
+    );
+  }
+
+  return [
+    "<details>",
+    "<summary>Usage</summary>",
+    "",
+    header,
+    separatorRow,
+    ...rows,
+    ...totalsRows,
+    "",
+    "</details>",
+  ].join("\n");
+}

package/src/utils/normalizeEnv.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { normalizeEnv, sanitizeSecret } from "#app/utils/normalizeEnv";
+
+/**
+ * These tests pin the load-bearing invariants of secret sanitisation:
+ *   - sensitive values are trimmed before downstream code reads them
+ *   - whitespace-only values are NOT silently zeroed (leave env unchanged)
+ *   - case normalisation still happens
+ *
+ * Masking (`core.setSecret`) is delegated to `@actions/core` and trusted to
+ * work as documented — we don't spy on stdout to re-test the toolkit.
+ */
+
+describe("normalizeEnv: process.env state contract", () => {
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    // normalizeEnv() iterates the entire process.env, so the test must
+    // control it. snapshot + full wipe + restore is the cleanest isolation.
+    originalEnv = { ...process.env };
+    for (const k of Object.keys(process.env)) delete process.env[k];
+  });
+
+  afterEach(() => {
+    for (const k of Object.keys(process.env)) delete process.env[k];
+    Object.assign(process.env, originalEnv);
+  });
+
+  it("trims trailing newline from sensitive env vars", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-secret-value\n";
+    normalizeEnv();
+    expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-secret-value");
+  });
+
+  it("trims surrounding whitespace including \\r\\n and spaces", () => {
+    process.env.OPENAI_API_KEY = "  sk-openai-value\r\n  ";
+    normalizeEnv();
+    expect(process.env.OPENAI_API_KEY).toBe("sk-openai-value");
+  });
+
+  it("leaves clean sensitive values untouched", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-clean";
+    normalizeEnv();
+    expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-clean");
+  });
+
+  it("ignores non-sensitive env vars", () => {
+    process.env.NODE_ENV = "production\n";
+    normalizeEnv();
+    expect(process.env.NODE_ENV).toBe("production\n");
+  });
+
+  it("canonicalises case and trims the value", () => {
+    process.env.anthropic_api_key = "sk-ant-lowercase\n";
+    normalizeEnv();
+    expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-lowercase");
+    expect(process.env.anthropic_api_key).toBeUndefined();
+  });
+
+  it("preserves whitespace-only values rather than silently zeroing them", () => {
+    // contract: don't mutate when value is whitespace-only. caller sees the
+    // misconfigured value verbatim and either fails clearly downstream or
+    // logs a missing-key error.
+    process.env.ANTHROPIC_API_KEY = "   \n  ";
+    normalizeEnv();
+    expect(process.env.ANTHROPIC_API_KEY).toBe("   \n  ");
+  });
+
+  it("preserves embedded newlines (toolkit masks each line)", () => {
+    // multi-line PEMs aren't used in practice, but if one slipped in via a
+    // DB secret we don't want to silently mutate it. trim() only touches
+    // the ends; @actions/core handles per-line masking via the runner.
+    process.env.ANTHROPIC_API_KEY = "line1\nline2";
+    normalizeEnv();
+    expect(process.env.ANTHROPIC_API_KEY).toBe("line1\nline2");
+  });
+});
+
+describe("sanitizeSecret return value", () => {
+  it("returns the trimmed value for a sensitive secret with trailing newline", () => {
+    expect(sanitizeSecret("ANTHROPIC_API_KEY", "sk-ant-secret\n")).toBe("sk-ant-secret");
+  });
+
+  it("returns the value unchanged when no trimming is needed", () => {
+    expect(sanitizeSecret("ANTHROPIC_API_KEY", "sk-ant-clean")).toBe("sk-ant-clean");
+  });
+
+  it("returns null for whitespace-only input so caller can skip injection", () => {
+    expect(sanitizeSecret("ANTHROPIC_API_KEY", "   \n")).toBeNull();
+  });
+});

package/src/utils/normalizeEnv.ts

@@ -0,0 +1,106 @@
+import * as core from "@actions/core";
+import { log } from "#app/utils/cli";
+import { isSensitiveEnvName } from "#app/utils/secrets";
+
+/**
+ * Trim surrounding whitespace from a sensitive value and register it as a
+ * GitHub Actions log mask. Trailing newlines from terminal-copy paste are a
+ * common footgun: the value travels through GH Actions logs and any tool
+ * that re-emits parts of it leaks the unmasked tail. Trimming canonicalises
+ * the value so the mask matches exactly what downstream tools will print.
+ *
+ * Masking is delegated to `core.setSecret` (not raw `console.log`) so the
+ * toolkit percent-encodes `\r`/`\n`; the runner V2 parser decodes them and
+ * registers the full value plus every non-empty line as separate masks. That
+ * keeps us safe for embedded-newline values (PEMs, kubeconfigs, JSON blobs)
+ * even though they aren't currently used.
+ *
+ * Returns the trimmed value, or `null` when the input was whitespace-only —
+ * callers must leave `process.env` untouched in that case so a misconfigured
+ * value surfaces as a clear "missing key" downstream rather than silently
+ * mutating to the empty string.
+ */
+export function sanitizeSecret(key: string, value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    log.warning(
+      `» ${key} is whitespace-only — leaving env var unchanged. check your secret value.`,
+    );
+    return null;
+  }
+  if (trimmed !== value) {
+    log.warning(
+      `» stripped whitespace from ${key} (whitespace in secret values breaks GitHub Actions log masking)`,
+    );
+  }
+  core.setSecret(trimmed);
+  return trimmed;
+}
+
+/**
+ * Normalize environment variables to uppercase.
+ * This handles case-insensitive env var names (e.g., `anthropic_api_key` -> `ANTHROPIC_API_KEY`).
+ *
+ * If there are conflicts (same key with different capitalizations but different values),
+ * logs a warning and keeps the uppercase version.
+ *
+ * Also trims and masks sensitive values so accidental trailing whitespace
+ * doesn't defeat GitHub Actions log masking.
+ */
+export function normalizeEnv(): void {
+  const upperKeys = new Map<string, string[]>();
+
+  // group keys by their uppercase form
+  for (const key of Object.keys(process.env)) {
+    const upper = key.toUpperCase();
+    const existing = upperKeys.get(upper) || [];
+    existing.push(key);
+    upperKeys.set(upper, existing);
+  }
+
+  // process each group
+  for (const [upperKey, keys] of upperKeys) {
+    if (keys.length === 1) {
+      const key = keys[0]!;
+      if (key !== upperKey) {
+        // single key, just needs uppercasing
+        process.env[upperKey] = process.env[key];
+        delete process.env[key];
+      }
+      continue;
+    }
+
+    // multiple keys with different capitalizations
+    const values = keys.map((k) => process.env[k]);
+    const uniqueValues = new Set(values);
+
+    if (uniqueValues.size > 1) {
+      // conflict: different values for different capitalizations
+      log.warning(
+        `env var conflict: ${keys.join(", ")} have different values. using uppercase ${upperKey}.`,
+      );
+    }
+
+    // prefer the uppercase version if it exists, otherwise use the first one
+    const preferredKey = keys.find((k) => k === upperKey) || keys[0]!;
+    const preferredValue = process.env[preferredKey];
+
+    // delete all variants
+    for (const key of keys) {
+      delete process.env[key];
+    }
+
+    // set the uppercase version
+    process.env[upperKey] = preferredValue;
+  }
+
+  // trim + mask sensitive values after case normalisation so each key is
+  // visited exactly once with its final, canonical value
+  for (const key of Object.keys(process.env)) {
+    if (!isSensitiveEnvName(key)) continue;
+    const value = process.env[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    const sanitized = sanitizeSecret(key, value);
+    if (sanitized !== null) process.env[key] = sanitized;
+  }
+}