@tech-leads-club/harness-toolkit 0.2.1

package/src/platform/fs-atomic.ts

@@ -0,0 +1,142 @@
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { nextDelay, retry } from "./backoff.ts";
+
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? (error as NodeJS.ErrnoException).code
+    : undefined;
+}
+
+function isRetryableFsError(error: unknown): boolean {
+  const code = errorCode(error);
+  return code !== undefined && RETRYABLE_CODES.has(code);
+}
+
+function tempPathFor(path: string): string {
+  return `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+}
+
+export type FsAtomicOptions = {
+  attempts?: number;
+  baseMs?: number;
+  capMs?: number;
+  random?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  rename?: (from: string, to: string) => void;
+  writeFile?: (path: string, data: string) => void;
+  removeFile?: (path: string) => void;
+};
+
+export async function writeJsonAtomic(
+  path: string,
+  value: unknown,
+  options: FsAtomicOptions = {},
+): Promise<void> {
+  const {
+    attempts = 5,
+    baseMs = 20,
+    capMs = 500,
+    random,
+    sleep,
+    rename = renameSync,
+    writeFile = (p: string, data: string) => writeFileSync(p, data, "utf8"),
+    removeFile = (p: string) => {
+      try {
+        rmSync(p, { force: true });
+      } catch {}
+    },
+  } = options;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = tempPathFor(path);
+  writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`);
+
+  try {
+    await retry(
+      () => {
+        rename(tempPath, path);
+      },
+      { attempts, baseMs, capMs, random, sleep, shouldRetry: isRetryableFsError },
+    );
+  } catch (error) {
+    removeFile(tempPath);
+    throw error;
+  }
+}
+
+function readJson<T>(path: string): T | null {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const attempts = 200;
+  let acquired = false;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      closeSync(openSync(lockPath, "wx"));
+      acquired = true;
+      break;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+    }
+  }
+  if (!acquired) {
+    throw new Error(`fs-atomic: could not acquire lock at ${lockPath}`);
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {}
+  }
+}
+
+export type UpdateJsonAtomicOptions = FsAtomicOptions & {
+  lockPath: string /**
+   * Run inside the write lock, after the file lands. The platform does not care what it does — recording a
+   * content hash is core's business, and doing it here is what makes the record and the content one write.
+   */;
+  afterWrite?: (path: string) => void;
+};
+
+export async function updateJsonAtomic<T>(
+  path: string,
+  mutator: (current: T | null) => T,
+  options: UpdateJsonAtomicOptions,
+): Promise<T> {
+  const { lockPath, afterWrite, ...atomicOptions } = options;
+  return withFileLock(lockPath, async () => {
+    const current = readJson<T>(path);
+    const next = mutator(current);
+    await writeJsonAtomic(path, next, atomicOptions);
+    // why: inside the lock. A caller that sealed after the lock released would race the next writer, and the pair
+    // that lost would leave a record matching neither content ([/decisions/ad-078.md](/decisions/ad-078.md)).
+    afterWrite?.(path);
+    return next;
+  });
+}

package/src/platform/fs-jsonl.ts

@@ -0,0 +1,24 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export function appendRecord(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(value)}\n`);
+}
+
+export function readTail<T>(path: string, n: number): T[] {
+  if (!existsSync(path)) {
+    return [];
+  }
+  const records: T[] = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    try {
+      records.push(JSON.parse(trimmed) as T);
+    } catch {}
+  }
+  return records.slice(-n);
+}

package/src/platform/git.ts

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runProcess } from "./process.ts";
+import { normalizeSeparators } from "./sanitize.ts";
+
+async function gitLines(projectDir: string, args: string[]): Promise<string[]> {
+  const result = await runProcess({ command: ["git", ...args], cwd: projectDir });
+  if (result.exitCode !== 0) {
+    return [];
+  }
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/**
+ * why: `base` is the revision the turn started at, not `HEAD`. A turn that commits moves `HEAD` past its own
+ * changes, so every gate reading this list saw an empty diff and skipped — measured on a real turn whose task
+ * was named "schema v2 + tests + commit" ([/decisions/ad-058.md](/decisions/ad-058.md)).
+ *
+ * invariant: `HEAD` stays the default, so a caller with no recorded base behaves exactly as before.
+ */
+export async function listChangedRepoFiles(projectDir: string, base = "HEAD"): Promise<string[]> {
+  if (!existsSync(join(projectDir, ".git"))) {
+    return [];
+  }
+
+  const batches = await Promise.all([
+    gitLines(projectDir, ["diff", "--name-only", base]),
+    gitLines(projectDir, ["diff", "--name-only", "--cached"]),
+    gitLines(projectDir, ["ls-files", "--others", "--exclude-standard"]),
+  ]);
+
+  const paths = new Set<string>();
+  for (const batch of batches) {
+    for (const path of batch) {
+      paths.add(path);
+    }
+  }
+  return [...paths];
+}
+
+/**
+ * File lists for the most recent commits, newest first. One entry per commit, so a caller can replay a rule
+ * over history without knowing how git formats anything.
+ */
+export async function listCommitFileSets(projectDir: string, limit: number): Promise<string[][]> {
+  if (!existsSync(join(projectDir, ".git")) || limit <= 0) {
+    return [];
+  }
+  // why: one git call for all commits. A separate call per commit is the obvious shape and is an order of
+  // magnitude slower on the history sizes this is used for.
+  const lines = await gitLines(projectDir, [
+    "log",
+    `-${limit}`,
+    "--name-only",
+    "--no-renames",
+    "--format=%x00",
+  ]);
+
+  const commits: string[][] = [];
+  let current: string[] | null = null;
+  for (const line of lines) {
+    if (line === "\u0000") {
+      current = [];
+      commits.push(current);
+      continue;
+    }
+    current?.push(line);
+  }
+  return commits.filter((files) => files.length > 0);
+}
+
+export type AddedLine = {
+  file: string;
+  line: number;
+  text: string;
+};
+
+export async function listAddedLines(
+  projectDir: string,
+  relativePaths: string[],
+  base = "HEAD",
+): Promise<AddedLine[]> {
+  if (!existsSync(join(projectDir, ".git")) || relativePaths.length === 0) {
+    return [];
+  }
+  const tracked = new Set(await gitLines(projectDir, ["ls-files", "--", ...relativePaths]));
+  const out: AddedLine[] = [];
+
+  for (const file of relativePaths) {
+    if (!tracked.has(file)) {
+      let raw = "";
+      try {
+        raw = readFileSync(join(projectDir, file), "utf8");
+      } catch {
+        continue;
+      }
+      raw.split(/\r?\n/).forEach((text, index) => {
+        out.push({ file, line: index + 1, text });
+      });
+      continue;
+    }
+    const diff = await gitLines(projectDir, ["diff", "--unified=0", base, "--", file]);
+    let lineNo = 0;
+    for (const row of diff) {
+      const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(row);
+      if (hunk) {
+        lineNo = Number(hunk[1]);
+        continue;
+      }
+      if (row.startsWith("+++")) {
+        continue;
+      }
+      if (row.startsWith("+")) {
+        out.push({ file, line: lineNo, text: row.slice(1) });
+        lineNo += 1;
+      }
+    }
+  }
+  return out;
+}
+
+function isUnderPrefixes(relativePath: string, prefixes: string[]): boolean {
+  const normalized = normalizeSeparators(relativePath);
+  return prefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
+}
+
+export function filterCodeTargets(relativePaths: string[], codePaths: string[]): string[] {
+  return relativePaths.filter((path) => {
+    if (!isUnderPrefixes(path, codePaths)) {
+      return false;
+    }
+    return /\.(ts|tsx|js|jsx|json|mjs|cjs|py|go|rs)$/.test(path);
+  });
+}
+
+export function filterTestTargets(relativePaths: string[]): string[] {
+  return relativePaths.filter((path) => /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(path));
+}
+
+export type CommandResult = { exitCode: number; output: string; durationMs: number };
+
+export async function runCommand(
+  projectDir: string,
+  command: string[],
+  extraArgs: string[] = [],
+  options: { env?: NodeJS.ProcessEnv } = {},
+): Promise<CommandResult> {
+  if (command.length === 0) {
+    return { exitCode: 0, output: "", durationMs: 0 };
+  }
+  const started = Date.now();
+  const result = await runProcess({
+    command: [...command, ...extraArgs],
+    cwd: projectDir,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+  });
+  const combined = (result.stdout + result.stderr).trim();
+  const maxChars = 8000;
+  const output =
+    combined.length === 0
+      ? "(no output captured)"
+      : combined.length <= maxChars
+        ? combined
+        : combined.slice(-maxChars);
+  return {
+    exitCode: result.exitCode,
+    output,
+    durationMs: Date.now() - started,
+  };
+}
+
+/**
+ * Every tracked file, so a duplication scan reads what the project owns and nothing it ignores.
+ *
+ * why: `git ls-files` already honours `.gitignore`, so `node_modules` and build output cost nothing to exclude
+ * and no second ignore list has to be kept in step ([/decisions/ad-071.md](/decisions/ad-071.md)).
+ */
+export async function listTrackedFiles(projectDir: string): Promise<string[]> {
+  const result = await runCommand(projectDir, ["git", "ls-files", "-z"]);
+  if (result.exitCode !== 0) {
+    return [];
+  }
+  return result.output.split("\0").filter((path) => path !== "");
+}

package/src/platform/paths.ts

@@ -0,0 +1,80 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function harnessDir(root: string): string {
+  return join(root, ".tlc", "harness");
+}
+
+/**
+ * why: the path hooks name and the one the installer materialises into. It is deliberately not derived from where
+ * the code happens to sit, because an npm-installed copy sits under a directory npm replaces
+ * ([/decisions/ad-056.md](/decisions/ad-056.md)).
+ */
+export function conventionalRuntimeHome(): string {
+  return join(homedir(), ".tlc", "harness");
+}
+
+// why: the env is a parameter so a caller can be tested. The first version read `process.env` unconditionally,
+// which made every destination-resolution test assert against the machine it ran on rather than its input.
+export function runtimeHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.TLC_HOME ?? conventionalRuntimeHome();
+}
+
+/**
+ * invariant: `tlc-exec` always sets `TLC_HOME` in the child, so the child cannot tell an operator's choice from
+ * the launcher's own resolution. This flag is that difference, and only the installer needs it — everything else
+ * wants the resolved home either way.
+ */
+export function runtimeHomeWasChosen(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.TLC_HOME_FROM_ENV === "1";
+}
+
+export function runtimeStateDir(): string {
+  return join(runtimeHome(), "state");
+}
+
+// why: one file for every repository on the machine. Per-repo state stays authoritative; this is the
+// cross-repo view, which cannot exist under any single project's state directory.
+export function runtimeSpoolPath(): string {
+  return join(runtimeStateDir(), "obs-spool.jsonl");
+}
+
+export function projectConfigPath(root: string): string {
+  return join(harnessDir(root), "config.json");
+}
+
+export function projectStateDir(root: string): string {
+  return join(harnessDir(root), "state");
+}
+
+export function flagsDir(root: string): string {
+  return join(projectStateDir(root), "flags");
+}
+
+export function presenceDir(root: string): string {
+  return join(projectStateDir(root), "presence");
+}
+
+export function loopsDir(root: string): string {
+  return join(projectStateDir(root), "loops");
+}
+
+export function bootDir(root: string): string {
+  return join(projectStateDir(root), "boot");
+}
+
+// why: inside the state directory on purpose — the baseline that proves the policy was not switched off
+// inherits the same protection as the policy itself.
+export function policyBaselineDir(root: string): string {
+  return join(projectStateDir(root), "policy-baseline");
+}
+
+export function claudeConfigDir(): string {
+  const custom = process.env.CLAUDE_CONFIG_DIR?.trim();
+  return custom && custom.length > 0 ? custom : join(homedir(), ".claude");
+}
+
+export function cursorConfigDir(): string {
+  const custom = process.env.CURSOR_CONFIG_DIR?.trim();
+  return custom && custom.length > 0 ? custom : join(homedir(), ".cursor");
+}

package/src/platform/pricing.ts

@@ -0,0 +1,229 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runtimeHome } from "./paths.ts";
+
+export type VendorPool = "cursor_models" | "anthropic_models" | "other_models" | "auto" | "unknown";
+export type NeutralPool = "provider_native" | "other" | "auto" | "unknown";
+export type CostSource = "override" | "provider" | "litellm" | "missing";
+
+export type ModelPriceEntry = {
+  displayName?: string;
+  provider?: string;
+  promptPer1M?: number;
+  completionPer1M?: number;
+  cacheWritePer1M?: number;
+  cacheReadPer1M?: number;
+  pool?: VendorPool;
+  billing?: "metered" | "included" | "unknown";
+  contextWindow?: number;
+};
+
+export type TokenUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+};
+
+export type CostEstimate = {
+  costUsd: number | null;
+  billing: "metered" | "included" | "unknown";
+  pool: VendorPool;
+  source: CostSource;
+  catalogKey?: string;
+};
+
+type PriceTable = Record<string, ModelPriceEntry>;
+type AliasTable = Record<string, string>;
+
+const VENDOR_TO_NEUTRAL_POOL: Record<VendorPool, NeutralPool> = {
+  cursor_models: "provider_native",
+  anthropic_models: "provider_native",
+  other_models: "other",
+  auto: "auto",
+  unknown: "unknown",
+};
+
+export function mapPoolToNeutral(pool: VendorPool): NeutralPool {
+  return VENDOR_TO_NEUTRAL_POOL[pool];
+}
+
+function readJsonFile<T>(path: string): T | null {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function stripMeta(table: PriceTable | null): PriceTable {
+  if (!table) {
+    return {};
+  }
+  const { _meta: _ignored, ...rest } = table as PriceTable & { _meta?: unknown };
+  return rest;
+}
+
+export function slugifyModelName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[[\]]/g, "")
+    .replace(/\(.*?\)/g, "")
+    .replace(/[^a-z0-9.+]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function candidatesFor(model: string, aliases: AliasTable): string[] {
+  const trimmed = model.trim();
+  const out: string[] = [];
+  const push = (v: string | undefined) => {
+    if (v && !out.includes(v)) {
+      out.push(v);
+    }
+  };
+  push(trimmed);
+  push(aliases[trimmed]);
+  push(slugifyModelName(trimmed));
+  push(aliases[slugifyModelName(trimmed)]);
+  if (trimmed.includes("/")) {
+    push(trimmed.slice(trimmed.lastIndexOf("/") + 1));
+  }
+  const noEffort = trimmed.replace(/-(high|medium|low|max|fast|thinking)$/i, "");
+  if (noEffort !== trimmed) {
+    push(noEffort);
+    push(aliases[noEffort]);
+    push(slugifyModelName(noEffort));
+  }
+  return out;
+}
+
+function fuzzyFind(table: PriceTable, needle: string): { key: string; entry: ModelPriceEntry } | undefined {
+  const direct = table[needle];
+  if (direct) {
+    return { key: needle, entry: direct };
+  }
+  for (const [key, entry] of Object.entries(table)) {
+    if (needle.startsWith(key) || key.startsWith(needle)) {
+      return { key, entry };
+    }
+  }
+  return undefined;
+}
+
+function overridesPath(): string {
+  return join(runtimeHome(), "model-prices.json");
+}
+
+function providerNativePath(provider: string): string {
+  return join(runtimeHome(), `model-prices.${provider}.json`);
+}
+
+function litellmPath(): string {
+  return join(runtimeHome(), "model-prices.litellm.json");
+}
+
+function aliasesPath(): string {
+  return join(runtimeHome(), "model-aliases.json");
+}
+
+export type PriceResolution = {
+  entry: ModelPriceEntry;
+  key: string;
+  source: "override" | "provider" | "litellm";
+};
+
+export function resolveModelPrice(provider: string, model: string): PriceResolution | undefined {
+  const trimmed = model.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const overrides = stripMeta(readJsonFile<PriceTable>(overridesPath()));
+  const native = stripMeta(readJsonFile<PriceTable>(providerNativePath(provider)));
+  const litellm = stripMeta(readJsonFile<PriceTable>(litellmPath()));
+  const aliases = readJsonFile<AliasTable>(aliasesPath()) ?? {};
+
+  const candidates = candidatesFor(trimmed, aliases);
+
+  for (const id of candidates) {
+    const entry = overrides[id];
+    if (entry) {
+      return { entry, key: id, source: "override" };
+    }
+  }
+  for (const id of candidates) {
+    const entry = native[id];
+    if (entry) {
+      return { entry, key: id, source: "provider" };
+    }
+  }
+  for (const id of candidates) {
+    const entry = litellm[id];
+    if (entry) {
+      return { entry, key: id, source: "litellm" };
+    }
+  }
+
+  const slug = slugifyModelName(trimmed);
+  const fuzzyOverride = fuzzyFind(overrides, slug);
+  if (fuzzyOverride) {
+    return { ...fuzzyOverride, source: "override" };
+  }
+  const fuzzyNative = fuzzyFind(native, slug);
+  if (fuzzyNative) {
+    return { ...fuzzyNative, source: "provider" };
+  }
+  const fuzzyLitellm = fuzzyFind(litellm, slug);
+  if (fuzzyLitellm) {
+    return { ...fuzzyLitellm, source: "litellm" };
+  }
+
+  return undefined;
+}
+
+export function estimateCostUsd(
+  provider: string,
+  model: string | undefined,
+  usage: TokenUsage,
+): CostEstimate {
+  const inputTokens = usage.inputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? 0;
+  const cacheReadTokens = usage.cacheReadTokens ?? 0;
+  const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+
+  if (!model || (inputTokens <= 0 && outputTokens <= 0 && cacheReadTokens <= 0 && cacheWriteTokens <= 0)) {
+    return { costUsd: null, billing: "unknown", pool: "unknown", source: "missing" };
+  }
+
+  const resolved = resolveModelPrice(provider, model);
+  if (!resolved) {
+    return { costUsd: null, billing: "unknown", pool: "unknown", source: "missing" };
+  }
+
+  const { entry, key, source } = resolved;
+  const pool = entry.pool ?? "unknown";
+
+  if (entry.billing === "included") {
+    return { costUsd: null, billing: "included", pool, source, catalogKey: key };
+  }
+
+  if (typeof entry.promptPer1M !== "number" || typeof entry.completionPer1M !== "number") {
+    return { costUsd: null, billing: entry.billing ?? "unknown", pool, source, catalogKey: key };
+  }
+
+  let costUsd =
+    (inputTokens / 1_000_000) * entry.promptPer1M + (outputTokens / 1_000_000) * entry.completionPer1M;
+
+  if (typeof entry.cacheReadPer1M === "number" && cacheReadTokens > 0) {
+    costUsd += (cacheReadTokens / 1_000_000) * entry.cacheReadPer1M;
+  }
+  if (typeof entry.cacheWritePer1M === "number" && cacheWriteTokens > 0) {
+    costUsd += (cacheWriteTokens / 1_000_000) * entry.cacheWritePer1M;
+  }
+
+  return { costUsd, billing: "metered", pool, source, catalogKey: key };
+}