@tech-leads-club/harness-toolkit 0.2.1

package/bin/tlc-exec

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]:-$0}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+BIN_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+exec node "$BIN_DIR/tlc-exec.mjs" "$@"

package/bin/tlc-exec.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+node "%~dp0tlc-exec.mjs" %*
+exit /b %ERRORLEVEL%

package/bin/tlc-exec.d.mts

@@ -0,0 +1,60 @@
+export const MIN_NODE_MAJOR: number;
+
+export function conventionalHarnessHome(home?: string): string;
+
+export function isPackagedCopy(candidate: string): boolean;
+
+export type HarnessHomeDeps = {
+  realpath: (path: string) => string;
+  home: () => string;
+  exists?: (path: string) => boolean;
+};
+
+export function resolveHarnessHome(
+  binDir: string,
+  env?: Record<string, string | undefined>,
+  invoked?: string,
+  deps?: HarnessHomeDeps,
+): string;
+
+export function bunExecutableName(platform?: string): string;
+
+export function findBunOnPath(
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): string | null;
+
+export function runtimeCachePath(harnessHome: string): string;
+
+export type RuntimeCache = { bunPath: string | null; checkedAt: string };
+
+export function readRuntimeCache(harnessHome: string): RuntimeCache | null;
+
+export function writeRuntimeCache(harnessHome: string, bunPath: string | null): RuntimeCache;
+
+export function resolveBunPath(
+  harnessHome: string,
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): string | null;
+
+export function entrySourceCandidates(harnessHome: string, entry: string): string[];
+
+export function resolveEntrySource(harnessHome: string, entry: string): string | null;
+
+export type RuntimeDecisionInput = {
+  harnessHome: string;
+  entry: string;
+  bunPath: string | null;
+  nodeMajor: number;
+  distExists: boolean;
+  srcPath: string | null;
+};
+
+export type RuntimeDecision =
+  | { kind: "run"; command: string; args: string[] }
+  | { kind: "error"; status: number; message: string };
+
+export function decideRuntime(input: RuntimeDecisionInput): RuntimeDecision;
+
+export function main(argv?: string[]): void;

package/bin/tlc-exec.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const MIN_NODE_MAJOR = 24;
+
+export function conventionalHarnessHome(home = homedir()) {
+  return join(home, ".tlc", "harness");
+}
+
+function samePath(left, right, resolve) {
+  try {
+    return resolve(left) === resolve(right);
+  } catch {
+    return false;
+  }
+}
+
+// hazard: ESM resolves import.meta.url to the realpath, and the bash wrappers walk readlink before
+// invoking, so both binDir and argv[1] can name the checkout rather than the install path. Anything derived
+// from this value is written into hook files and compared by doctor, so the checkout leaking in here made
+// generated shims point at a directory that only exists on the machine that ran init.
+// invariant: the conventional path wins only when it resolves to the same runtime — verified, never assumed,
+// so a deliberately relocated install is left alone.
+/**
+ * why: an npm-installed copy lives under a directory npm replaces wholesale on update, so anything the runtime
+ * writes there is deleted by the next `npm i -g` — measured on the packed tarball, which put `runtime-cache.json`
+ * inside the package on its first run, where the global lesson tier and the cross-repository spool would follow.
+ *
+ * invariant: the installed runtime under the conventional home wins, and the npm copy is only the delivery
+ * vehicle plus the CLI shim that reaches it. Hooks already name the conventional path directly, so the hot path
+ * never asks this question.
+ */
+export function isPackagedCopy(candidate) {
+  return candidate.split(/[/\\]/).includes("node_modules");
+}
+
+export function resolveHarnessHome(
+  binDir,
+  env = process.env,
+  invoked = process.argv[1],
+  deps = { realpath: realpathSync, home: homedir, exists: existsSync },
+) {
+  const fromEnv = env.TLC_HOME?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  const candidate = invoked?.endsWith("tlc-exec.mjs") ? join(dirname(invoked), "..") : join(binDir, "..");
+  const conventional = conventionalHarnessHome(deps.home());
+  if (conventional !== candidate && samePath(conventional, candidate, deps.realpath)) {
+    return conventional;
+  }
+  // invariant: only when that home actually holds a runtime. Before `tlc harness install` has ever run there is
+  // nothing there, and the package has to be able to run itself in order to put it there.
+  const exists = deps.exists ?? existsSync;
+  if (isPackagedCopy(candidate) && exists(join(conventional, "bin", "tlc-exec.mjs"))) {
+    return conventional;
+  }
+  return candidate;
+}
+
+export function bunExecutableName(platform = process.platform) {
+  return platform === "win32" ? "bun.exe" : "bun";
+}
+
+export function findBunOnPath(env = process.env, platform = process.platform) {
+  const pathValue = env.PATH ?? "";
+  const bunName = bunExecutableName(platform);
+  for (const dir of pathValue.split(delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    const candidate = join(dir, bunName);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function runtimeCachePath(harnessHome) {
+  return join(harnessHome, "state", "runtime-cache.json");
+}
+
+export function readRuntimeCache(harnessHome) {
+  const cachePath = runtimeCachePath(harnessHome);
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+    if (parsed && typeof parsed === "object" && "bunPath" in parsed) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * hazard: this used to write unconditionally. On the first run of an npm-installed copy the home is still the
+ * package, so it dropped a cache file into global `node_modules` — harmless on a prefix you own, and `EACCES`
+ * on one installed with sudo, which would crash the bootstrap before it could install anything. The cache is
+ * derived, so failing to write it costs one PATH scan per invocation and nothing else.
+ */
+export function writeRuntimeCache(harnessHome, bunPath) {
+  const record = { bunPath, checkedAt: new Date().toISOString() };
+  if (isPackagedCopy(harnessHome)) {
+    return record;
+  }
+  try {
+    const cachePath = runtimeCachePath(harnessHome);
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, `${JSON.stringify(record)}\n`);
+  } catch {
+    // why: an unwritable runtime home degrades to probing every time, which is correct and merely slower.
+  }
+  return record;
+}
+
+export function resolveBunPath(harnessHome, env = process.env, platform = process.platform) {
+  const cached = readRuntimeCache(harnessHome);
+  if (cached) {
+    return cached.bunPath;
+  }
+  const found = findBunOnPath(env, platform);
+  writeRuntimeCache(harnessHome, found);
+  return found;
+}
+
+export function entrySourceCandidates(harnessHome, entry) {
+  return [
+    entry === "tlc-cli" ? join(harnessHome, "bin", "tlc-cli.ts") : null,
+    join(harnessHome, "src", "entrypoints", `${entry}.ts`),
+    join(harnessHome, "src", `${entry}.ts`),
+    join(harnessHome, "tools", `${entry}.ts`),
+  ].filter((candidate) => candidate !== null);
+}
+
+export function resolveEntrySource(harnessHome, entry) {
+  for (const candidate of entrySourceCandidates(harnessHome, entry)) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExists, srcPath }) {
+  const distPath = join(harnessHome, "dist", `${entry}.mjs`);
+  if (bunPath && srcPath && distExists) {
+    return { kind: "run", command: bunPath, args: ["run", srcPath] };
+  }
+  if (nodeMajor >= MIN_NODE_MAJOR && distExists) {
+    return { kind: "run", command: process.execPath, args: [distPath] };
+  }
+  if (bunPath && srcPath) {
+    return { kind: "run", command: bunPath, args: ["run", srcPath] };
+  }
+  if (nodeMajor >= MIN_NODE_MAJOR) {
+    return {
+      kind: "error",
+      status: 1,
+      message: [
+        `tlc: Node ${process.version} found, but dist/${entry}.mjs is missing.`,
+        `  Run: ${join(harnessHome, "bin", "tlc-build")}`,
+      ].join("\n"),
+    };
+  }
+  if (nodeMajor > 0 && nodeMajor < MIN_NODE_MAJOR) {
+    return {
+      kind: "error",
+      status: 1,
+      message: [
+        `tlc: no supported hook runtime (Node ${process.version}, Bun not found).`,
+        "  Either install Bun:  curl -fsSL https://bun.sh/install | bash",
+        `  or Node >= ${MIN_NODE_MAJOR}:     https://nodejs.org/`,
+        "  Then reload the editor session. Until then this hook does nothing.",
+      ].join("\n"),
+    };
+  }
+  return {
+    kind: "error",
+    status: 127,
+    message: [
+      `tlc: need Node.js ${MIN_NODE_MAJOR}+ with dist/, or Bun as optional fallback.`,
+      "  Install: https://nodejs.org/ (prefer 24 LTS or 26 Current)",
+    ].join("\n"),
+  };
+}
+
+function run(harnessHome, command, commandArgs, origin = harnessHome) {
+  const result = spawnSync(command, commandArgs, {
+    stdio: "inherit",
+    // why: `TLC_ORIGIN` is where this copy physically lives, which is not `TLC_HOME` once an npm-installed shim
+    // is driving the runtime installed under the conventional path. `tlc harness install` needs the former as
+    // its source and the latter as its destination, and nothing else in the runtime reads it.
+    env: {
+      ...process.env,
+      TLC_HOME: harnessHome,
+      TLC_ORIGIN: origin,
+      // hazard: derived once, by the outermost launcher, and inherited after that. `tlc harness install` reaches
+      // the tool through the CLI, so the launcher runs twice — and the second one saw the `TLC_HOME` the first
+      // one had just set, concluded the operator had chosen it, and installed the runtime on top of itself.
+      // Measured against the packed tarball: "runtime already at <package> — nothing to copy".
+      TLC_HOME_FROM_ENV: process.env.TLC_HOME_FROM_ENV ?? (process.env.TLC_HOME?.trim() ? "1" : "0"),
+    },
+    shell: false,
+  });
+  if (result.error) {
+    console.error(`tlc: failed to start ${command}: ${result.error.message}`);
+    process.exit(127);
+  }
+  process.exit(result.status ?? 1);
+}
+
+export function main(argv = process.argv) {
+  const binDir = dirname(fileURLToPath(import.meta.url));
+  const harnessHome = resolveHarnessHome(binDir);
+
+  const entry = argv[2];
+  if (!entry) {
+    console.error("usage: tlc-exec <entry> [args...]");
+    console.error("  entry: session-start | tool-before | stop | doctor | ...");
+    process.exit(2);
+  }
+  const args = argv.slice(3);
+
+  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+  const distExists = existsSync(join(harnessHome, "dist", `${entry}.mjs`));
+  const srcPath = resolveEntrySource(harnessHome, entry);
+  const bunPath = resolveBunPath(harnessHome);
+
+  const decision = decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExists, srcPath });
+  if (decision.kind === "error") {
+    console.error(decision.message);
+    process.exit(decision.status);
+  }
+  run(harnessHome, decision.command, [...decision.args, ...args], join(binDir, ".."));
+}
+
+if (import.meta.main) {
+  main();
+}

package/bin/tlc.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+node "%~dp0tlc-exec.mjs" tlc-cli %*
+exit /b %ERRORLEVEL%

package/bin/tlc.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// why: npm's bin shim invokes its target with node on every platform, so the bash wrapper `bin/tlc` cannot be
+// the published entry — a shell script behind a generated .cmd is the classic broken global install on Windows.
+// The two wrappers stay for the git-clone route, which puts them on PATH directly.
+import { main } from "./tlc-exec.mjs";
+
+main([process.argv[0] ?? "node", process.argv[1] ?? "tlc", "tlc-cli", ...process.argv.slice(2)]);

package/bin/write-user-hooks.d.mts

@@ -0,0 +1,40 @@
+import type { ProviderWiring, WiringEntry } from "../src/contracts/index.ts";
+
+export type CursorHookDef = {
+  command: string;
+  timeout: number;
+  failClosed?: true;
+  matcher?: string;
+  loop_limit?: number;
+};
+
+export type CursorHooksDocument = {
+  version: 1;
+  hooks: Record<string, CursorHookDef[]>;
+};
+
+export function renderCursorHooksDocument(entries: readonly WiringEntry[]): CursorHooksDocument;
+
+export function isCursorWired(targetPath: string): boolean;
+
+export type ApplyOptions = { force?: boolean };
+
+export type CursorApplyResult =
+  | { status: "written"; target: string }
+  | { status: "unchanged"; target: string }
+  | { status: "refused"; target: string; reason: string };
+
+export function applyCursorWiring(wiring: ProviderWiring, options?: ApplyOptions): CursorApplyResult;
+
+export type ClaudeApplyResult =
+  | { status: "merged"; target: string }
+  | { status: "unchanged"; target: string }
+  | { status: "failed"; target: string; reason: string };
+
+export type ApplyResult = CursorApplyResult | ClaudeApplyResult;
+
+export function applyProviderWiring(wiring: ProviderWiring, options?: ApplyOptions): ApplyResult;
+
+export function isProviderHomePresent(wiring: ProviderWiring): boolean;
+
+export function main(): void;

package/bin/write-user-hooks.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { applyClaudeWiring } from "../src/providers/claude/claude.wiring.ts";
+import { providers } from "../src/providers/index.ts";
+
+const CURSOR_MARKER = "tlc-exec.mjs";
+
+function quoteIfNeeded(token) {
+  return token.includes(" ") ? `"${token}"` : token;
+}
+
+function commandStringFor(entry) {
+  return [entry.command, ...entry.args].map(quoteIfNeeded).join(" ");
+}
+
+export function renderCursorHooksDocument(entries) {
+  const hooks = {};
+  for (const entry of entries) {
+    const rendered = { command: commandStringFor(entry), timeout: entry.timeoutSeconds };
+    if (entry.failClosed) {
+      rendered.failClosed = true;
+    }
+    if (entry.matcher !== undefined) {
+      rendered.matcher = entry.matcher;
+    }
+    if (entry.loopLimit !== undefined) {
+      rendered.loop_limit = entry.loopLimit;
+    }
+    hooks[entry.hookEvent] = [...(hooks[entry.hookEvent] ?? []), rendered];
+  }
+  return { version: 1, hooks };
+}
+
+export function isCursorWired(targetPath) {
+  return existsSync(targetPath) && readFileSync(targetPath, "utf8").includes(CURSOR_MARKER);
+}
+
+export function applyCursorWiring(wiring, { force = false } = {}) {
+  const targetPath = wiring.target;
+  const document = renderCursorHooksDocument(wiring.entries);
+  const rendered = `${JSON.stringify(document, null, 2)}\n`;
+
+  if (existsSync(targetPath) && !force) {
+    if (isCursorWired(targetPath)) {
+      return { status: "unchanged", target: targetPath };
+    }
+    return {
+      status: "refused",
+      target: targetPath,
+      reason: `${targetPath} exists without harness entries — rerun with --force to overwrite, or merge manually.`,
+    };
+  }
+
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, rendered);
+  return { status: "written", target: targetPath };
+}
+
+export function applyProviderWiring(wiring, { force = false } = {}) {
+  if (wiring.strategy === "replace") {
+    return applyCursorWiring(wiring, { force });
+  }
+  const result = applyClaudeWiring(wiring.target, wiring.entries);
+  if (!result.ok) {
+    return { status: "failed", target: wiring.target, reason: result.error };
+  }
+  return { status: result.changed ? "merged" : "unchanged", target: wiring.target };
+}
+
+export function isProviderHomePresent(wiring) {
+  return existsSync(dirname(wiring.target));
+}
+
+function report(result) {
+  switch (result.status) {
+    case "written":
+      console.log(`hooks: wrote ${result.target}`);
+      return true;
+    case "merged":
+      console.log(`hooks: merged ${result.target}`);
+      return true;
+    case "unchanged":
+      console.log(`hooks: unchanged (${result.target})`);
+      return true;
+    case "refused":
+      console.error(`hooks: ${result.reason}`);
+      return false;
+    case "failed":
+      console.error(`hooks: failed to update ${result.target}: ${result.reason}`);
+      return false;
+    default:
+      return false;
+  }
+}
+
+export function main() {
+  const binDir = dirname(fileURLToPath(import.meta.url));
+  // hazard: ESM resolves import.meta.url to the realpath, so deriving the launcher from it bakes
+  // the checkout location into every hook. TLC_HOME is the install path and survives a move.
+  const harnessHome = process.env.TLC_HOME?.trim() || join(binDir, "..");
+  const launcherPath = join(harnessHome, "bin", "tlc-exec.mjs");
+  const force = process.argv.includes("--force");
+  let anyFailed = false;
+
+  for (const provider of providers) {
+    const wiring = provider.wiring({ launcherPath });
+    if (!isProviderHomePresent(wiring)) {
+      console.log(`hooks: ${provider.name} not installed — skipping (${dirname(wiring.target)} not found)`);
+      continue;
+    }
+    if (!report(applyProviderWiring(wiring, { force }))) {
+      anyFailed = true;
+    }
+  }
+
+  process.exitCode = anyFailed ? 1 : 0;
+}
+
+if (import.meta.main) {
+  main();
+}