@tech-leads-club/harness-toolkit 0.2.1

package/tools/price-lookup.ts

@@ -0,0 +1,57 @@
+import { emitJson, takeJsonFlag } from "../src/platform/cli-output.ts";
+import {
+  type CostEstimate,
+  estimateCostUsd,
+  type PriceResolution,
+  resolveModelPrice,
+} from "../src/platform/pricing.ts";
+
+export type PriceLookupArgs = { model: string; provider: string };
+export type PriceLookupResult = {
+  model: string;
+  provider: string;
+  resolved: PriceResolution | undefined;
+  per1M: CostEstimate;
+};
+
+export function parsePriceLookupArgs(argv: readonly string[]): PriceLookupArgs | null {
+  const model = argv[0];
+  if (!model) {
+    return null;
+  }
+  return { model, provider: argv[1] ?? "" };
+}
+
+export function lookupPrice(args: PriceLookupArgs): PriceLookupResult {
+  const resolved = resolveModelPrice(args.provider, args.model);
+  const per1M = estimateCostUsd(args.provider, args.model, {
+    inputTokens: 1_000_000,
+    outputTokens: 1_000_000,
+  });
+  return { model: args.model, provider: args.provider, resolved, per1M };
+}
+
+function main(): void {
+  const { json, rest } = takeJsonFlag(process.argv.slice(2));
+  const args = parsePriceLookupArgs(rest);
+  if (!args) {
+    console.error("usage: tlc harness prices lookup <model-id> [provider]");
+    console.error(
+      "   or: node --experimental-strip-types tools/price-lookup.ts <model-id> [provider]  (dev)",
+    );
+    process.exit(1);
+  }
+  const result = lookupPrice(args);
+  if (json) {
+    emitJson(result);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+  if (!result.resolved) {
+    process.exit(2);
+  }
+}
+
+if (import.meta.main) {
+  main();
+}

package/tools/refresh-model-prices.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HARNESS_HOME = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CURSOR_DOCS_URL = "https://cursor.com/docs/models-and-pricing.md";
+const LITELLM_URL =
+  "https://raw.githubusercontent.com/BerriAI/litellm/main/litellm/model_prices_and_context_window_backup.json";
+
+type PriceEntry = {
+  displayName?: string;
+  provider?: string;
+  promptPer1M?: number;
+  completionPer1M?: number;
+  cacheWritePer1M?: number;
+  cacheReadPer1M?: number;
+  pool?: "cursor_models" | "other_models" | "auto" | "unknown";
+  billing?: "metered" | "included" | "unknown";
+  contextWindow?: number;
+};
+
+function slugify(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/\(.*?\)/g, "")
+    .replace(/[^a-z0-9.+]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function parseMoney(cell: string): number | undefined {
+  const t = cell.trim();
+  if (!t || t === "-" || t === "—" || t.toLowerCase() === "n/a") {
+    return undefined;
+  }
+  const m = t.replace(/,/g, "").match(/\$?\s*([0-9]*\.?[0-9]+)/);
+  if (!m) {
+    return undefined;
+  }
+  return Number(m[1]);
+}
+
+function stripCell(cell: string): string {
+  return cell
+    .trim()
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/\*\*/g, "")
+    .trim();
+}
+
+function inferPool(displayName: string, provider: string): PriceEntry["pool"] {
+  const n = displayName.toLowerCase();
+  if (n === "auto cost" || n.startsWith("auto ")) {
+    return "auto";
+  }
+  if (provider.toLowerCase() === "cursor" || n.includes("composer") || n.includes("grok 4.5")) {
+    return "cursor_models";
+  }
+  return "other_models";
+}
+
+function parseCursorDocs(md: string): Record<string, PriceEntry> {
+  const out: Record<string, PriceEntry> = {};
+  const lines = md.split("\n");
+  let inTable = false;
+
+  for (const line of lines) {
+    if (!line.startsWith("|")) {
+      if (inTable) {
+        break;
+      }
+      continue;
+    }
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.length < 6) {
+      continue;
+    }
+    const [cell0 = "", cell1 = "", cell2 = "", cell3 = "", cell4 = "", cell5 = ""] = cells;
+    if (cell0.toLowerCase() === "model" || cell0.startsWith("---") || cell0.includes("---")) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable) {
+      continue;
+    }
+
+    const displayName = stripCell(cell0);
+    const provider = stripCell(cell1);
+    const promptPer1M = parseMoney(cell2);
+    const cacheWritePer1M = parseMoney(cell3);
+    const cacheReadPer1M = parseMoney(cell4);
+    const completionPer1M = parseMoney(cell5);
+    if (!displayName || promptPer1M === undefined || completionPer1M === undefined) {
+      continue;
+    }
+
+    const key = slugify(displayName);
+    out[key] = {
+      displayName,
+      provider,
+      promptPer1M,
+      completionPer1M,
+      cacheWritePer1M,
+      cacheReadPer1M,
+      pool: inferPool(displayName, provider),
+      billing: "metered",
+    };
+  }
+
+  return out;
+}
+
+type LiteLlmEntry = {
+  max_input_tokens?: number;
+  max_tokens?: number;
+  input_cost_per_token?: number;
+  output_cost_per_token?: number;
+  cache_read_input_token_cost?: number;
+  cache_creation_input_token_cost?: number;
+  litellm_provider?: string;
+};
+
+function parseLiteLlm(raw: Record<string, LiteLlmEntry>): Record<string, PriceEntry> {
+  const out: Record<string, PriceEntry> = {};
+  for (const [id, entry] of Object.entries(raw)) {
+    if (id === "sample_spec") {
+      continue;
+    }
+    const contextWindow =
+      typeof entry.max_input_tokens === "number" ? entry.max_input_tokens : entry.max_tokens;
+    const compact: PriceEntry = {
+      displayName: id,
+      provider: entry.litellm_provider,
+      pool: "unknown",
+      billing: "metered",
+    };
+    if (typeof contextWindow === "number" && contextWindow > 0) {
+      compact.contextWindow = contextWindow;
+    }
+    if (typeof entry.input_cost_per_token === "number" && typeof entry.output_cost_per_token === "number") {
+      compact.promptPer1M = entry.input_cost_per_token * 1_000_000;
+      compact.completionPer1M = entry.output_cost_per_token * 1_000_000;
+    } else {
+      continue;
+    }
+    if (typeof entry.cache_read_input_token_cost === "number") {
+      compact.cacheReadPer1M = entry.cache_read_input_token_cost * 1_000_000;
+    }
+    if (typeof entry.cache_creation_input_token_cost === "number") {
+      compact.cacheWritePer1M = entry.cache_creation_input_token_cost * 1_000_000;
+    }
+    out[id] = compact;
+    const slug = slugify(id);
+    if (slug !== id && !out[slug]) {
+      out[slug] = { ...compact, displayName: id };
+    }
+  }
+  return out;
+}
+
+const mode = (process.argv[2] ?? "all").toLowerCase();
+
+if (mode === "all" || mode === "cursor") {
+  const res = await fetch(CURSOR_DOCS_URL);
+  if (!res.ok) {
+    console.error(`Failed to fetch Cursor docs: ${res.status}`);
+    process.exit(1);
+  }
+  const md = await res.text();
+  const cursor = parseCursorDocs(md);
+  const count = Object.keys(cursor).length;
+  if (count === 0) {
+    console.error("Parsed 0 Cursor models — docs table format may have changed");
+    process.exit(1);
+  }
+  const path = join(HARNESS_HOME, "model-prices.cursor.json");
+  writeFileSync(
+    path,
+    `${JSON.stringify({ _meta: { source: CURSOR_DOCS_URL, refreshedAt: new Date().toISOString() }, ...cursor }, null, 2)}\n`,
+  );
+  console.log(`Cursor catalog: ${count} models → ${path}`);
+}
+
+if (mode === "all" || mode === "litellm") {
+  const res = await fetch(LITELLM_URL);
+  if (!res.ok) {
+    console.error(`Failed to fetch LiteLLM prices: ${res.status}`);
+    process.exit(1);
+  }
+  const raw = (await res.json()) as Record<string, LiteLlmEntry>;
+  const litellm = parseLiteLlm(raw);
+  const path = join(HARNESS_HOME, "model-prices.litellm.json");
+  writeFileSync(
+    path,
+    `${JSON.stringify({
+      _meta: {
+        source: LITELLM_URL,
+        refreshedAt: new Date().toISOString(),
+        count: Object.keys(litellm).length,
+      },
+      ...litellm,
+    })}\n`,
+  );
+  console.log(`LiteLLM catalog: ${Object.keys(litellm).length} models → ${path}`);
+}

package/tools/test-env.mjs

@@ -0,0 +1,28 @@
+/**
+ * Loaded with `node --import` before every test file, so the suite answers from its own fixtures instead of
+ * from the shell that happened to start it.
+ *
+ * hazard: `projectDirFor` prefers `CLAUDE_PROJECT_DIR` over the payload's `cwd`, which is correct in
+ * production — the env var is the project root and `cwd` can be a subdirectory. Inside a Claude Code hook that
+ * variable is always set, so 22 tests that build a fixture in a temp directory silently read policy and state
+ * from the real repository instead. The suite passed from a shell and failed from inside a hook.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PROJECT_SCOPED_ENV } from "./test-env.names.mjs";
+
+for (const name of PROJECT_SCOPED_ENV) {
+  delete process.env[name];
+}
+
+/**
+ * hazard: `TLC_HOME` was left alone on the reasoning that it names which runtime and CI sets it deliberately. That
+ * held only while nothing machine-wide lived under it. The global lesson tier does, so a test calling `allLessons`
+ * without pinning the home read whichever lessons the developer happened to have promoted — green on a fresh
+ * machine, green in CI, red on mine the moment I promoted five ([/decisions/ad-042.md](/decisions/ad-042.md)).
+ *
+ * invariant: hermetic by default, opt in by assignment. A test that wants a runtime home sets one; a test that
+ * forgets gets an empty directory rather than a person's machine.
+ */
+process.env.TLC_HOME = mkdtempSync(join(tmpdir(), "tlc-test-home-"));

package/tools/test-env.names.d.mts

@@ -0,0 +1 @@
+export const PROJECT_SCOPED_ENV: string[];

package/tools/test-env.names.mjs

@@ -0,0 +1,14 @@
+/**
+ * The names only, with no side effect, so a test can read them without performing the cleanup it is checking.
+ *
+ * hazard: this list lived in `test-env.mjs` next to the `delete` loop, and the guard test imported it from
+ * there. Importing that module runs the loop, so the guard cleaned the very environment it was asserting about
+ * and could never fail. Data and effect are separate for that reason.
+ *
+ * invariant: only variables that name WHICH project. `TLC_HOME` names which runtime, is set deliberately by
+ * CI, and is part of what the suite exercises.
+ */
+// hazard: `CURSOR_PROJECT_DIR` was absent while `cursor.inbound.ts` prefers it over the payload's workspace
+// root — the same hole this list exists to close, for the other provider. A suite launched from inside a Cursor
+// hook would have read the real repository exactly as the Claude case did.
+export const PROJECT_SCOPED_ENV = ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "TLC_PROJECT_DIR"];