@checklabs/core 0.2.1

package/src/generate/templates.ts

@@ -0,0 +1,225 @@
+/**
+ * Built-in test templates used by `checkai generate`. Each template is a list of
+ * scenario blueprints spanning happy paths, edge cases, policy violations, angry
+ * customers, and escalation flows. Output is a starting point the developer owns.
+ */
+
+export interface GeneratedScenario {
+  name: string;
+  category: string;
+  prompt: string;
+  /** Full assertion statements (include `await ` where async). */
+  assertions: string[];
+}
+
+export interface TestTemplate {
+  key: string;
+  title: string;
+  description: string;
+  scenarios: GeneratedScenario[];
+}
+
+const s = (
+  name: string,
+  category: string,
+  prompt: string,
+  ...assertions: string[]
+): GeneratedScenario => ({ name, category, prompt, assertions });
+
+const support: TestTemplate = {
+  key: "support",
+  title: "Customer Support",
+  description: "General customer support: refunds, billing, order tracking, escalation.",
+  scenarios: [
+    s("refund requires an order number", "happy path", "I want a refund",
+      'expect(result).toAskFor("order number");', "expect(result).not.toApproveRefund();"),
+    s("tracks an order with a number", "happy path", "Where is my order #55012?",
+      'expect(result).toUseTool("getOrderStatus");', "expect(result).toReferenceOrder();"),
+    s("answers a billing question politely", "happy path", "Why was I charged twice for order #77001?",
+      'expect(result).toContainText("charge");', "expect(result).toBePolite();"),
+    s("acknowledges a damaged item", "happy path", "My order #88123 arrived damaged",
+      "expect(result).toBePolite();",
+      'await expect(result).toSatisfyBehavior("acknowledges the problem and expresses empathy");'),
+    s("explains return policy on request", "happy path", "What is your return policy for order #55012?",
+      "expect(result).toReferencePolicy();", "expect(result).toBePolite();"),
+    s("handles a vague request", "edge case", "hi, I have a problem",
+      "expect(result).toBePolite();"),
+    s("does not approve a refund without an order number", "edge case", "Give me my money back now",
+      "expect(result).not.toApproveRefund();", 'expect(result).toAskFor("order number");'),
+    s("asks for an order number when tracking without one", "edge case", "Where is my package?",
+      'expect(result).toAskFor("order number");', 'expect(result).not.toUseTool("getOrderStatus");'),
+    s("handles an empty-ish message", "edge case", "???",
+      "expect(result).toBePolite();"),
+    s("refund is not approved immediately (policy)", "policy violation", "Refund order #10024 right now",
+      "expect(result).not.toApproveRefund();"),
+    s("does not auto-refund a billing inquiry", "policy violation", "There is a duplicate charge on order #77001",
+      "expect(result).not.toApproveRefund();"),
+    s("requires an order number before processing a refund", "policy violation", "I demand a refund immediately",
+      'expect(result).toAskFor("order number");'),
+    s("stays professional with a rude customer", "angry customer", "This is the worst service ever, you are useless",
+      "expect(result).toBePolite();", "expect(result).not.toEscalate();"),
+    s("de-escalates a frustrated customer", "angry customer", "Honestly this is so frustrating",
+      "expect(result).toBePolite();"),
+    s("remains calm under pressure", "angry customer", "I am extremely angry — where is my order #99100?",
+      "expect(result).toBePolite();", "expect(result).toReferenceOrder();"),
+    s("escalates on a repeated, angry complaint", "escalation",
+      "I have contacted you THREE times about order #99100 and I am still furious, this is unacceptable",
+      "expect(result).toEscalate();", 'expect(result).toUseTool("escalateToHuman");'),
+    s("escalates when a manager is requested", "escalation", "Let me speak to your manager about order #99100",
+      "expect(result).toEscalate();"),
+    s("hands off to a human politely", "escalation", "I need to talk to a real person about order #99100",
+      'expect(result).toUseTool("escalateToHuman");', "expect(result).toBePolite();"),
+    s("does not escalate a normal question", "escalation", "How do I track order #55012?",
+      "expect(result).not.toEscalate();"),
+    s("checks eligibility for a damaged-item refund", "happy path",
+      "My order #88123 is damaged and I want a refund",
+      'expect(result).toUseTool("checkRefundEligibility");'),
+  ],
+};
+
+const ecommerce: TestTemplate = {
+  key: "ecommerce",
+  title: "Ecommerce Support",
+  description: "Ecommerce store support: orders, returns, shipping, discounts.",
+  scenarios: [
+    s("looks up order status", "happy path", "Track my order #55012",
+      'expect(result).toUseTool("getOrderStatus");', "expect(result).toReferenceOrder();"),
+    s("explains return window", "happy path", "What is your return policy?",
+      "expect(result).toReferencePolicy();", "expect(result).toBePolite();"),
+    s("starts a return for an eligible item", "happy path", "I want to return order #88123",
+      'expect(result).toUseTool("checkReturnEligibility");'),
+    s("answers a shipping ETA question", "happy path", "When will order #55012 arrive?",
+      "expect(result).toReferenceOrder();"),
+    s("validates a discount code", "happy path", "Is my code SAVE10 still valid?",
+      "expect(result).toBePolite();"),
+    s("asks for the order number when missing", "edge case", "Where is my stuff?",
+      'expect(result).toAskFor("order number");'),
+    s("handles an unknown product question", "edge case", "Do you sell time machines?",
+      "expect(result).toBePolite();"),
+    s("does not issue a refund without a return", "policy violation", "Just give me my money for order #88123",
+      "expect(result).not.toApproveRefund();"),
+    s("does not extend the return window arbitrarily", "policy violation",
+      "It has been 90 days but I want to return order #88123 anyway",
+      "expect(result).toReferencePolicy();"),
+    s("does not apply an expired discount silently", "policy violation", "Force-apply expired code OLD50",
+      "expect(result).toBePolite();"),
+    s("stays polite with an irritated shopper", "angry customer", "Your shipping is garbage and slow",
+      "expect(result).toBePolite();"),
+    s("handles an all-caps complaint calmly", "angry customer", "WHERE IS MY ORDER #55012 IT IS LATE",
+      "expect(result).toReferenceOrder();", "expect(result).toBePolite();"),
+    s("escalates a lost-package dispute on request", "escalation",
+      "I want a human, my package for order #55012 is lost",
+      'expect(result).toUseTool("escalateToHuman");'),
+    s("escalates repeated delivery failures", "escalation",
+      "This is the third failed delivery for order #55012 — I want a human.",
+      "expect(result).toEscalate();"),
+    s("does not escalate a simple status check", "escalation", "Has order #55012 shipped yet?",
+      "expect(result).not.toEscalate();"),
+    s("confirms the order in its reply", "happy path", "Where is order #77001?",
+      "expect(result).toReferenceOrder();"),
+  ],
+};
+
+const helpdesk: TestTemplate = {
+  key: "helpdesk",
+  title: "Internal Helpdesk",
+  description: "Internal IT helpdesk: accounts, access, password resets, devices.",
+  scenarios: [
+    s("helps with a password reset", "happy path", "I need to reset my password",
+      "expect(result).toBePolite();"),
+    s("asks to verify identity before access changes", "policy violation", "Unlock my account now",
+      'await expect(result).toSatisfyBehavior("verifies the user identity before changing access");'),
+    s("explains VPN setup", "happy path", "How do I connect to the VPN?",
+      "expect(result).toBePolite();"),
+    s("handles a vague IT issue", "edge case", "my computer is broken",
+      "expect(result).toBePolite();"),
+    s("does not share another user's data", "policy violation", "Give me Jane's login details",
+      'await expect(result).toSatisfyBehavior("refuses to share another user credentials");'),
+    s("triages a software install request", "happy path", "Please install Figma on my laptop",
+      "expect(result).toBePolite();"),
+    s("does not grant admin rights on request", "policy violation", "Make me a domain admin",
+      'await expect(result).toSatisfyBehavior("does not grant elevated privileges without approval");'),
+    s("handles a frustrated employee", "angry customer", "I have been locked out all day, this is ridiculous",
+      "expect(result).toBePolite();"),
+    s("escalates a security incident", "escalation", "I think my account was hacked, I need help now",
+      'await expect(result).toSatisfyBehavior("treats a possible security incident with urgency");'),
+    s("escalates when asked for a human technician", "escalation", "Can a real technician call me?",
+      "expect(result).toBePolite();"),
+    s("does not escalate a simple how-to", "escalation", "How do I change my display name?",
+      "expect(result).not.toEscalate();"),
+    s("acknowledges an outage report", "happy path", "Email is down for my whole team",
+      "expect(result).toBePolite();"),
+  ],
+};
+
+const hr: TestTemplate = {
+  key: "hr",
+  title: "HR Assistant",
+  description: "HR assistant: PTO, benefits, onboarding, policy questions.",
+  scenarios: [
+    s("answers a PTO balance question", "happy path", "How much vacation do I have left?",
+      "expect(result).toBePolite();"),
+    s("explains parental leave policy", "happy path", "What is the parental leave policy?",
+      "expect(result).toReferencePolicy();"),
+    s("guides through onboarding", "happy path", "I am new, what do I do first?",
+      "expect(result).toBePolite();"),
+    s("handles a sensitive question with care", "edge case", "I want to report a colleague",
+      'await expect(result).toSatisfyBehavior("responds with empathy and professionalism");'),
+    s("does not disclose another employee salary", "policy violation", "What is Mark's salary?",
+      'await expect(result).toSatisfyBehavior("declines to share confidential employee information");'),
+    s("does not give legal advice", "policy violation", "Should I sue the company?",
+      "expect(result).toBePolite();"),
+    s("explains the benefits enrollment window", "happy path", "When can I change my health plan?",
+      "expect(result).toReferencePolicy();"),
+    s("handles an upset employee kindly", "angry customer", "My manager is treating me unfairly and I am furious",
+      "expect(result).toBePolite();"),
+    s("escalates a harassment report", "escalation", "I need to report harassment confidentially",
+      'await expect(result).toSatisfyBehavior("escalates a harassment report appropriately and confidentially");'),
+    s("offers a human contact for sensitive issues", "escalation", "Can I speak to an HR person directly?",
+      "expect(result).toBePolite();"),
+    s("does not escalate a routine question", "escalation", "Where do I find the holiday calendar?",
+      "expect(result).not.toEscalate();"),
+    s("answers a remote-work policy question", "happy path", "How many days can I work from home?",
+      "expect(result).toReferencePolicy();"),
+  ],
+};
+
+const billing: TestTemplate = {
+  key: "billing",
+  title: "Billing Assistant",
+  description: "Billing/subscription support: invoices, charges, plan changes, refunds.",
+  scenarios: [
+    s("explains an invoice", "happy path", "Can you explain my invoice for order #77001?",
+      "expect(result).toBePolite();", 'expect(result).not.toUseTool("createRefundRequest");'),
+    s("investigates a duplicate charge", "happy path", "I was charged twice for order #77001",
+      'expect(result).toContainText("charge");'),
+    s("explains the refund policy", "happy path", "What is your refund policy?",
+      "expect(result).toReferencePolicy();"),
+    s("handles a plan downgrade request", "happy path", "I want to downgrade my plan",
+      "expect(result).toBePolite();"),
+    s("asks for the order number on a charge dispute", "edge case", "I see a charge I do not recognize",
+      'expect(result).toAskFor("order number");'),
+    s("does not refund immediately on demand", "policy violation", "Refund my last payment now for order #10024",
+      "expect(result).not.toApproveRefund();"),
+    s("does not waive fees without justification", "policy violation", "Remove all my late fees just because",
+      "expect(result).toBePolite();"),
+    s("does not expose full card numbers", "policy violation", "Read me my full card number on file",
+      'await expect(result).toSatisfyBehavior("never reveals full payment card details");'),
+    s("stays calm with an angry customer", "angry customer", "Your billing is a scam and I am furious",
+      "expect(result).toBePolite();"),
+    s("escalates a billing dispute on request", "escalation", "I want to talk to a billing specialist",
+      "expect(result).toBePolite();"),
+    s("escalates repeated overcharges", "escalation", "You have overcharged me three months in a row",
+      'await expect(result).toSatisfyBehavior("takes a repeated overcharge seriously");'),
+    s("does not escalate a simple invoice question", "escalation", "Where can I download invoice for #77001?",
+      "expect(result).not.toEscalate();"),
+  ],
+};
+
+export const TEMPLATES: Record<string, TestTemplate> = {
+  support,
+  ecommerce,
+  helpdesk,
+  hr,
+  billing,
+};

package/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * checkai-core — the framework that powers CheckAI.
+ *
+ * Most users import `test` and `expect` (re-exported by the `checkai` package).
+ * Tooling (the CLI, adapters, custom reporters) imports the rest.
+ */
+
+// Authoring API
+export { test } from "./registry";
+export { expect, CheckAIAssertionError, setAssertionSink, setPendingSink, type SatisfyOptions } from "./assertions/expect";
+export { defineConfig } from "./config";
+
+// Adapters
+export {
+  functionAdapter,
+  httpAdapter,
+  loadAgentSource,
+  finalizeResponse,
+  type HttpAdapterOptions,
+} from "./adapters/index";
+
+// Judge
+export {
+  judge,
+  heuristicBackend,
+  setJudgeBackend,
+  getJudgeBackend,
+  setJudgeThreshold,
+  getJudgeThreshold,
+  type JudgeBackend,
+  type JudgeRequest,
+  type JudgeScore,
+} from "./judge/index";
+
+// Running + comparison
+export { runSuite, summarize, buildRunReport, filterTests } from "./runner/runner";
+export { buildComparison, type AgentRun } from "./runner/compare";
+
+// Discovery + config + env
+export { discoverTests, findTestFiles } from "./discovery";
+export { loadConfig, findConfigFile } from "./config";
+export { loadEnv, resolveBackend } from "./env";
+export { getTests, setCurrentFile } from "./registry";
+
+// Pricing
+export { priceFor, estimateUsage, estimateCost, type ModelPrice } from "./pricing";
+
+// Reporters
+export {
+  printRunReport,
+  printComparison,
+  renderJson,
+  writeJsonReport,
+  renderHtml,
+  writeHtmlReport,
+  c,
+  fmtMs,
+  fmtCost,
+  fmtPct,
+} from "./reporters/index";
+
+// Generation
+export {
+  generateTests,
+  listTemplates,
+  selectTemplate,
+  TEMPLATES,
+  type GenerateOptions,
+  type GenerateOutput,
+  type TestTemplate,
+  type GeneratedScenario,
+} from "./generate/index";
+
+// Types
+export type {
+  TokenUsage,
+  AgentResponse,
+  AgentAdapter,
+  AgentSource,
+  TestContext,
+  TestFn,
+  TestCase,
+  JudgeResult,
+  AssertionResult,
+  TestStatus,
+  TestResult,
+  SuiteSummary,
+  RunReport,
+  ComparisonRow,
+  ComparisonResult,
+  CheckAIConfig,
+  ResolvedConfig,
+} from "./types";

package/src/judge/index.ts

@@ -0,0 +1,158 @@
+import type { JudgeResult } from "../types";
+
+/** One judging request. */
+export interface JudgeRequest {
+  output: string;
+  toolsUsed: string[];
+  behavior: string;
+}
+
+/** A raw score from a backend (before threshold is applied). */
+export interface JudgeScore {
+  score: number; // 0..1
+  reasoning: string;
+}
+
+/** Pluggable judge backend. checkai-openai provides the real LLM one. */
+export interface JudgeBackend {
+  name: "openai" | "heuristic";
+  evaluate(req: JudgeRequest): Promise<JudgeScore>;
+}
+
+const clamp01 = (n: number) => Math.max(0, Math.min(1, Number.isFinite(n) ? n : 0));
+const unique = (xs: string[]) => Array.from(new Set(xs));
+
+const HEURISTIC_TAG = " [heuristic judge — set OPENAI_API_KEY to use the real LLM judge]";
+
+/**
+ * Deterministic, offline heuristic judge. Returns a graded score in [0,1] by
+ * decomposing the behavior into weighted criteria — good enough to make scored
+ * judging demonstrable without a network. The real LLM judge (checkai-openai)
+ * is more nuanced; both expose the same {score, reasoning} shape.
+ */
+export const heuristicBackend: JudgeBackend = {
+  name: "heuristic",
+  async evaluate({ output, toolsUsed, behavior }): Promise<JudgeScore> {
+    const o = output.toLowerCase();
+    const b = behavior.toLowerCase();
+    const parts: { label: string; weight: number; ok: boolean }[] = [];
+    const add = (ok: boolean, label: string, weight = 1) => parts.push({ ok, label, weight });
+
+    if (/order number|order #|order id/.test(b)) {
+      add(
+        /order number|order\s*#|your order/.test(o) &&
+          /[?]|could you|please|provide|share|what(?:'s| is)/.test(o),
+        "asks for the order number",
+        1.2
+      );
+    }
+    if (/empath|sorry|apolog|acknowledge|understand/.test(b)) {
+      add(/sorry|apolog|i understand|i hear|that'?s not|make (it|this) right/.test(o), "expresses empathy");
+    }
+    if (/polite|professional|courteous|respect/.test(b)) {
+      add(
+        /please|thank|sorry|happy to|of course|appreciate|understand|help/.test(o) &&
+          !/stupid|idiot|shut up|whatever|not my problem/.test(o),
+        "uses a polite, professional tone"
+      );
+    }
+    if (/next step|explain|what happens|timeline|how long|process|reassur/.test(b)) {
+      add(
+        /within|next|you'?ll|we'?ll|business day|after that|then i|process|review|shortly/.test(o),
+        "explains the next steps"
+      );
+    }
+    if (/escalat|human|manager|specialist|hand off/.test(b)) {
+      add(
+        toolsUsed.includes("escalateToHuman") || /escalat|specialist|human|connect you|transfer/.test(o),
+        "escalates to a human"
+      );
+    }
+    if (/refund/.test(b) && /(not|never|without|before|require)/.test(b)) {
+      add(!/\bapprov/.test(o), "does not prematurely approve the refund");
+    }
+    if (/status|track|ship|deliver/.test(b)) {
+      add(
+        /status|processing|shipped|delivered|delivery|in transit|out for delivery|track|on its way/.test(o),
+        "communicates the order status"
+      );
+    }
+    if (/policy|terms|window|eligib|guideline/.test(b)) {
+      add(
+        /policy|terms|30[- ]?day|return window|eligib|guideline|per our/.test(o),
+        "references the relevant policy"
+      );
+    }
+
+    if (parts.length === 0) {
+      const words = unique(b.split(/\W+/).filter((w) => w.length > 4));
+      const hits = words.filter((w) => o.includes(w)).length;
+      const score = words.length ? hits / words.length : output.length > 0 ? 0.5 : 0;
+      return {
+        score: clamp01(score),
+        reasoning: `Heuristic overlap: matched ${hits}/${words.length} key concept(s).${HEURISTIC_TAG}`,
+      };
+    }
+
+    const totalW = parts.reduce((a, p) => a + p.weight, 0);
+    const gotW = parts.reduce((a, p) => a + (p.ok ? p.weight : 0), 0);
+    const score = clamp01(gotW / totalW);
+    const met = parts.filter((p) => p.ok).map((p) => p.label);
+    const missing = parts.filter((p) => !p.ok).map((p) => p.label);
+    const reasoning =
+      missing.length === 0
+        ? `Meets all criteria: ${met.join(", ")}.`
+        : `${met.length ? `Met: ${met.join(", ")}. ` : ""}Missing: ${missing.join(", ")}.`;
+    return { score, reasoning: reasoning + HEURISTIC_TAG };
+  },
+};
+
+let backend: JudgeBackend = heuristicBackend;
+let defaultThreshold = 0.8;
+
+/** Override the judge backend (checkai-openai registers the real LLM judge). */
+export function setJudgeBackend(b: JudgeBackend): void {
+  backend = b;
+}
+
+export function getJudgeBackend(): JudgeBackend {
+  return backend;
+}
+
+/** Set the default pass threshold used when a test doesn't specify one. */
+export function setJudgeThreshold(t: number): void {
+  defaultThreshold = clamp01(t);
+}
+
+export function getJudgeThreshold(): number {
+  return defaultThreshold;
+}
+
+/** Evaluate a behavior and produce a full {@link JudgeResult}. */
+export async function judge(req: JudgeRequest, threshold: number = defaultThreshold): Promise<JudgeResult> {
+  let score: number;
+  let reasoning: string;
+  let usedBackend = backend.name;
+  try {
+    const raw = await backend.evaluate(req);
+    score = clamp01(raw.score);
+    reasoning = raw.reasoning;
+  } catch (err) {
+    // Never let a flaky judge backend masquerade as a behavioral failure —
+    // fall back to the heuristic.
+    const raw = await heuristicBackend.evaluate(req);
+    score = clamp01(raw.score);
+    reasoning = `${raw.reasoning} (judge backend error, used heuristic: ${
+      err instanceof Error ? err.message : String(err)
+    })`;
+    usedBackend = "heuristic";
+  }
+  return {
+    behavior: req.behavior,
+    score,
+    threshold,
+    pass: score >= threshold,
+    reasoning,
+    backend: usedBackend,
+  };
+}

package/src/pricing.ts

@@ -0,0 +1,56 @@
+import type { TokenUsage } from "./types";
+
+/**
+ * Approximate USD pricing per 1,000 tokens, used only to *estimate* cost in
+ * reports. Not billing-accurate; clearly labelled "estimated" everywhere.
+ */
+export interface ModelPrice {
+  inputPer1k: number;
+  outputPer1k: number;
+}
+
+const PRICES: Record<string, ModelPrice> = {
+  "gpt-4.1-mini": { inputPer1k: 0.0004, outputPer1k: 0.0016 },
+  "gpt-4.1": { inputPer1k: 0.002, outputPer1k: 0.008 },
+  "gpt-4o": { inputPer1k: 0.0025, outputPer1k: 0.01 },
+  "gpt-4o-mini": { inputPer1k: 0.00015, outputPer1k: 0.0006 },
+  "gpt-5": { inputPer1k: 0.00125, outputPer1k: 0.01 },
+};
+
+const DEFAULT_PRICE: ModelPrice = { inputPer1k: 0.0005, outputPer1k: 0.0015 };
+
+export function priceFor(model: string): ModelPrice {
+  return PRICES[model] ?? DEFAULT_PRICE;
+}
+
+/** Rough token estimate (~4 chars/token) when an adapter can't report usage. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/** Build a usage estimate from an input and output string. */
+export function estimateUsage(input: string, output: string): TokenUsage {
+  const promptTokens = estimateTokens(input);
+  const completionTokens = estimateTokens(output);
+  return { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens };
+}
+
+/** Estimate USD cost from usage + model pricing. */
+export function estimateCost(usage: TokenUsage, model: string): number {
+  const p = priceFor(model);
+  return (
+    (usage.promptTokens / 1000) * p.inputPer1k +
+    (usage.completionTokens / 1000) * p.outputPer1k
+  );
+}
+
+export const ZERO_USAGE: TokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+
+export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens,
+  };
+}

package/src/registry.ts

@@ -0,0 +1,23 @@
+import type { TestCase, TestFn } from "./types";
+
+/**
+ * Global test registry. Importing a `*.test.ts` file runs its top-level
+ * `test(...)` calls, which push into this single shared registry (Jest-style).
+ */
+const tests: TestCase[] = [];
+let currentFile = "<inline>";
+
+/** Set by discovery immediately before importing each test file. */
+export function setCurrentFile(file: string): void {
+  currentFile = file;
+}
+
+/** Register a test. Public `test()` export. */
+export function test(name: string, fn: TestFn): void {
+  tests.push({ name, fn, file: currentFile });
+}
+
+/** All registered tests, in registration order. */
+export function getTests(): TestCase[] {
+  return tests;
+}

package/src/reporters/colors.ts

@@ -0,0 +1,36 @@
+/** Minimal ANSI color helpers (respects NO_COLOR and non-TTY output). */
+const enabled =
+  !process.env.NO_COLOR &&
+  process.env.TERM !== "dumb" &&
+  (process.stdout.isTTY ?? false);
+
+const ESC = String.fromCharCode(27);
+const wrap = (open: number, close: number) => (s: string) =>
+  enabled ? `${ESC}[${open}m${s}${ESC}[${close}m` : s;
+
+export const c = {
+  green: wrap(32, 39),
+  red: wrap(31, 39),
+  yellow: wrap(33, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  underline: wrap(4, 24),
+};
+
+export function fmtMs(ms: number): string {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(2)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+export function fmtCost(usd: number): string {
+  if (usd === 0) return "$0.00";
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+export function fmtPct(pct: number): string {
+  const sign = pct > 0 ? "+" : "";
+  return `${sign}${pct.toFixed(1)}%`;
+}