@tech-leads-club/harness-toolkit 0.2.4 → 0.3.0

package/tools/install-runtime.ts

@@ -1,6 +1,8 @@
+import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE } from "../bin/tlc-cli.ts";
+import { linkDir } from "../src/platform/links.ts";
 import { conventionalRuntimeHome, runtimeHome, runtimeHomeWasChosen } from "../src/platform/paths.ts";
 import { type Row, render, type Screen } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
@@ -23,9 +25,6 @@ export const RUNTIME_PAYLOAD = [
   "src",
   "tools",
   "config.example.json",
-  "model-aliases.json",
-  "model-prices.cursor.json",
-  "model-prices.json",
   "package.json",
 ] as const;
 
@@ -52,11 +51,12 @@ export function isShipped(relativePath: string): boolean {
 }
 
 export type InstallReport = {
-  kind: "copied" | "in-place";
+  kind: "copied" | "in-place" | "linked" | "relinked" | "refused";
   source: string;
   dest: string;
   entries: string[];
   missing: string[];
+  reason?: string;
 };
 
 /** The physical location of the copy that launched us, which is not the home once an npm shim is driving one. */
@@ -110,7 +110,62 @@ export function installRuntime(source: string, dest: string): InstallReport {
   return { kind: "copied", source, dest, entries, missing };
 }
 
+/**
+ * The contributor route: the runtime home points at a checkout, so an edit is live in the next hook with no
+ * install step.
+ *
+ * why it is here and not in a shell script: it was `ln -sfn` in bash and `mklink /J` in PowerShell, and the
+ * PowerShell one asked for Developer Mode. One `symlinkSync` covers all three platforms
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: the checkout is never written to, and a destination that is not already a link is refused rather
+ * than removed ([/decisions/ad-046.md](/decisions/ad-046.md)).
+ */
+export function linkRuntime(source: string, dest: string): InstallReport {
+  if (resolve(source) === resolve(dest)) {
+    return { kind: "in-place", source, dest, entries: [], missing: [] };
+  }
+  const outcome = linkDir(resolve(source), dest);
+  if (outcome.kind === "refused") {
+    return { kind: "refused", source, dest, entries: [], missing: [], reason: outcome.reason };
+  }
+  const missing = RUNTIME_PAYLOAD.filter((entry) => !existsSync(join(dest, entry)));
+  return { kind: outcome.kind === "relinked" ? "relinked" : "linked", source, dest, entries: [], missing };
+}
+
 export function installScreen(report: InstallReport): Screen {
+  if (report.kind === "refused") {
+    return {
+      title: "harness install",
+      sections: [{ rows: [{ label: "refused", value: report.reason ?? "", level: "fail" }] }],
+    };
+  }
+  if (report.kind === "linked" || report.kind === "relinked") {
+    return {
+      title: "harness install",
+      sections: [
+        {
+          rows: [
+            {
+              label: report.kind === "linked" ? "linked" : "relinked",
+              value: `${report.dest} → ${report.source}`,
+              level: "ok",
+            },
+            ...(report.missing.length > 0
+              ? [
+                  {
+                    label: "incomplete",
+                    value: `the checkout has no ${report.missing.join(", ")} — run the build`,
+                    level: "fail" as const,
+                  },
+                ]
+              : []),
+          ],
+        },
+      ],
+      footer: "an edit in the checkout is live in the next hook  ·  `npm link` puts `tlc` on PATH",
+    };
+  }
   if (report.kind === "in-place") {
     return {
       title: "harness install",
@@ -155,10 +210,38 @@ export function installDest(env: NodeJS.ProcessEnv = process.env): string {
   return runtimeHomeWasChosen(env) ? runtimeHome(env) : conventionalRuntimeHome();
 }
 
+/**
+ * The first price fetch, on the machine, at install time.
+ *
+ * why: prices are no longer in the package, so a fresh install has no catalogue at all until something fetches
+ * one. This is that something ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: never fails the install. An operator installing behind a proxy, on a plane, or against a page that
+ * moved still gets a working harness — they get no cost figures until the next refresh, which `doctor` reports.
+ */
+export function fetchPrices(dest: string, spawn = spawnSync): void {
+  const result = spawn(process.execPath, [join(dest, "bin", "tlc-exec.mjs"), "refresh-model-prices"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_HOME: dest },
+  });
+  if ((result.status ?? 1) !== 0) {
+    console.log("install: prices not fetched — cost estimates stay empty until `tlc harness prices refresh`");
+  }
+}
+
 if (import.meta.main) {
-  const source = originRoot();
+  /**
+   * why a flag rather than a second command: install is install. The only difference is whether the runtime home
+   * holds a copy of the package or points at a checkout ([/decisions/ad-097.md](/decisions/ad-097.md)).
+   */
+  const link = process.argv.includes("--link");
+  const source = link ? process.cwd() : originRoot();
   const dest = installDest();
-  const report = installRuntime(source, dest);
+  const report = link ? linkRuntime(source, dest) : installRuntime(source, dest);
   console.log(installReportText(report, createStyle()));
+  if (report.kind === "refused") {
+    process.exit(1);
+  }
+  fetchPrices(dest);
   process.exit(report.missing.length > 0 ? 1 : 0);
 }

package/tools/refresh-model-prices.ts

@@ -1,35 +1,97 @@
 #!/usr/bin/env node
-import { writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { coreFacade } from "../src/core/index.ts";
+import { runtimeHome } from "../src/platform/paths.ts";
+import {
+  cataloguePath,
+  FALLBACK_PLANE,
+  loadCatalogue,
+  type ModelPriceEntry,
+  overridesPath,
+  type PriceCatalogue,
+  type PriceTable,
+  slugifyModelName,
+} from "../src/platform/pricing.ts";
 
-const HARNESS_HOME = join(dirname(fileURLToPath(import.meta.url)), "..");
-const CURSOR_DOCS_URL = "https://cursor.com/docs/models-and-pricing.md";
+/**
+ * hazard: this was `dirname(import.meta.url)/..` — the directory the script lives in. Under an npm install that is
+ * inside the package, which npm replaces wholesale on the next update, so the refresh wrote prices into a directory
+ * that would be deleted while `pricing.ts` read `runtimeHome()` and never received them. The same reason the
+ * runtime is materialised outside the package at all ([/decisions/ad-056.md](/decisions/ad-056.md),
+ * [/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: written where it is read. One resolution, `runtimeHome()`, used by both sides.
+ */
+const HARNESS_HOME = runtimeHome();
+
+/**
+ * The plane a provider's own rates land in. It is the provider's id, because the catalogue is keyed by who bills
+ * the call and a second provider publishing its own rates is a new plane, not a new file.
+ */
+const PROVIDER_PLANE = "cursor";
+const PROVIDER_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;
-};
+/**
+ * The files this replaced. Left on disk they are stale duplicates of two planes and an alias table nothing reads,
+ * and the operator has no way to tell which one a price came from ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+const SUPERSEDED = [
+  `model-prices.${PROVIDER_PLANE}.json`,
+  "model-prices.litellm.json",
+  "model-aliases.json",
+] as const;
 
-function slugify(name: string): string {
-  return name
-    .trim()
-    .toLowerCase()
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-    .replace(/\(.*?\)/g, "")
-    .replace(/[^a-z0-9.+]+/g, "-")
-    .replace(/^-+|-+$/g, "");
+/**
+ * hazard: `model-prices.json` used to be the operator's overrides table, and it is the name this now writes. An
+ * operator who had put their own rates in it would have had them replaced by the first refresh. A flat table with
+ * no `planes` key is that old file, so it is moved to where overrides are read from rather than overwritten.
+ */
+function adoptLegacyOverrides(quiet: boolean): void {
+  const path = cataloguePath();
+  if (!existsSync(path)) {
+    return;
+  }
+  const parsed = loadCatalogue();
+  const keys = Object.keys(parsed).filter((key) => key !== "_meta");
+  if (parsed.planes !== undefined || keys.length === 0) {
+    return;
+  }
+  if (existsSync(overridesPath())) {
+    console.error(
+      `refresh: ${basename(path)} holds ${keys.length} legacy entries and ${basename(overridesPath())} already exists — merge them by hand`,
+    );
+    return;
+  }
+  renameSync(path, overridesPath());
+  if (!quiet) {
+    console.log(`refresh: moved ${keys.length} local overrides → ${overridesPath()}`);
+  }
 }
 
+/** invariant: only the exact names this replaced, only inside the runtime home. Nothing else is removed. */
+function retireSupersededFiles(quiet: boolean): void {
+  for (const name of SUPERSEDED) {
+    const path = join(HARNESS_HOME, name);
+    if (!existsSync(path)) {
+      continue;
+    }
+    rmSync(path, { force: true });
+    if (!quiet) {
+      console.log(`refresh: removed superseded ${name}`);
+    }
+  }
+}
+
+/**
+ * invariant: the key a model is written under is computed by the same function the lookup uses. There were two
+ * copies of this and they disagreed about parentheses, which is what let a variant overwrite its base model and be
+ * read back at the wrong price ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+const slugify = slugifyModelName;
+
 function parseMoney(cell: string): number | undefined {
   const t = cell.trim();
   if (!t || t === "-" || t === "—" || t.toLowerCase() === "n/a") {
@@ -50,7 +112,7 @@ function stripCell(cell: string): string {
     .trim();
 }
 
-function inferPool(displayName: string, provider: string): PriceEntry["pool"] {
+export function inferPool(displayName: string, provider: string): ModelPriceEntry["pool"] {
   const n = displayName.toLowerCase();
   if (n === "auto cost" || n.startsWith("auto ")) {
     return "auto";
@@ -61,16 +123,24 @@ function inferPool(displayName: string, provider: string): PriceEntry["pool"] {
   return "other_models";
 }
 
-function parseCursorDocs(md: string): Record<string, PriceEntry> {
-  const out: Record<string, PriceEntry> = {};
+/**
+ * hazard: this used to `break` on the first line that is not a table row, so it read the FIRST table and stopped.
+ * The page now carries three: the provider's own models, then the rest. The parser went from 43 models to 3
+ * overnight and the only guard was `count === 0`, so a mutilated catalogue overwrote a good one and read as a
+ * successful refresh ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: every table on the page, and the header row of each resets the column expectation rather than ending
+ * the parse.
+ */
+export function parseCursorDocs(md: string): PriceTable {
+  const out: PriceTable = {};
   const lines = md.split("\n");
   let inTable = false;
 
   for (const line of lines) {
     if (!line.startsWith("|")) {
-      if (inTable) {
-        break;
-      }
+      // why: leaving a table is not the end of the document. The next one may be a few lines down.
+      inTable = false;
       continue;
     }
     const cells = line
@@ -125,15 +195,15 @@ type LiteLlmEntry = {
   litellm_provider?: string;
 };
 
-function parseLiteLlm(raw: Record<string, LiteLlmEntry>): Record<string, PriceEntry> {
-  const out: Record<string, PriceEntry> = {};
+export function parseLiteLlm(raw: Record<string, LiteLlmEntry>): PriceTable {
+  const out: PriceTable = {};
   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 = {
+    const compact: ModelPriceEntry = {
       displayName: id,
       provider: entry.litellm_provider,
       pool: "unknown",
@@ -163,48 +233,145 @@ function parseLiteLlm(raw: Record<string, LiteLlmEntry>): Record<string, PriceEn
   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}`);
+/**
+ * Which planes a refresh may write, and what happens when one of them comes back mutilated.
+ *
+ * invariant: a plane is replaced only if the incoming table is not a large loss against what is already there, and
+ * a refused plane leaves the others alone. One bad fetch must not take a good catalogue down with it
+ * ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+export type PlaneUpdate = { plane: string; source: string; table: PriceTable };
+export type PlaneOutcome = { plane: string; accepted: boolean; reason: string; count: number };
+
+function planeCount(catalogue: PriceCatalogue, plane: string): number {
+  return Object.keys(catalogue.planes?.[plane] ?? {}).length;
+}
+
+export function applyPlanes(
+  existing: PriceCatalogue,
+  updates: readonly PlaneUpdate[],
+  now: Date,
+): { catalogue: PriceCatalogue; outcomes: PlaneOutcome[] } {
+  const planes: Record<string, PriceTable> = { ...(existing.planes ?? {}) };
+  const planeMeta = { ...(existing._meta?.planes ?? {}) };
+  const outcomes: PlaneOutcome[] = [];
+  let accepted = 0;
+
+  for (const update of updates) {
+    const count = Object.keys(update.table).length;
+    const verdict = coreFacade.pricing.mayReplace(planeCount(existing, update.plane), count);
+    outcomes.push({ plane: update.plane, accepted: verdict.replace, reason: verdict.reason, count });
+    if (!verdict.replace) {
+      continue;
+    }
+    planes[update.plane] = update.table;
+    planeMeta[update.plane] = { source: update.source, count, refreshedAt: now.toISOString() };
+    accepted += 1;
+  }
+
+  // invariant: the file's own date moves only when something in it actually changed, so a refused refresh stays
+  // visibly stale rather than looking fresh.
+  const refreshedAt = accepted > 0 ? now.toISOString() : existing._meta?.refreshedAt;
+  return {
+    catalogue: { _meta: { ...(refreshedAt ? { refreshedAt } : {}), planes: planeMeta }, planes },
+    outcomes,
+  };
+}
+
+/**
+ * hazard: this file used to run its fetches at module scope, so importing it to test the parsers would have hit the
+ * network. `parseCursorDocs` and the key function were therefore untested — and both carried a defect that reached
+ * the catalogue ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+async function main(): Promise<void> {
+  const mode = (process.argv[2] ?? "all").toLowerCase();
+  const ifStale = process.argv.includes("--if-stale");
+  const quiet = process.argv.includes("--quiet");
+
+  const path = cataloguePath();
+
+  /**
+   * why: `--if-stale` is what makes an automatic refresh safe to wire into `install` and `update`. Without it both
+   * would reach the network on every run; with it the common case is one file read.
+   *
+   * invariant: the freshness decision is the core's and takes the clock as a parameter, and it is per plane —
+   * the provider's page changes far more often than the vendor list.
+   */
+  function wanted(plane: string, label: string): boolean {
+    if (!ifStale) {
+      return true;
+    }
+    const meta = existing._meta?.planes?.[plane];
+    const state = coreFacade.pricing.freshness(
+      existing.planes?.[plane] === undefined ? null : (meta ?? {}),
+      new Date(),
+    );
+    if (coreFacade.pricing.shouldRefetch(state)) {
+      return true;
+    }
+    if (!quiet) {
+      console.log(`${coreFacade.pricing.freshnessMessage(state, label)} — not refetching`);
+    }
+    return false;
+  }
+
+  // why: the directory may not exist yet on a first install, and writing into a missing one is the failure this
+  // avoids rather than reports.
+  mkdirSync(HARNESS_HOME, { recursive: true });
+  // invariant: the legacy overrides move out before the catalogue is read, so nothing of the old file's shape —
+  // its entries or its date — is carried into the new one.
+  adoptLegacyOverrides(quiet);
+  const existing = loadCatalogue();
+
+  const updates: PlaneUpdate[] = [];
+
+  if ((mode === "all" || mode === PROVIDER_PLANE) && wanted(PROVIDER_PLANE, `${PROVIDER_PLANE} prices`)) {
+    const res = await fetch(PROVIDER_DOCS_URL);
+    if (!res.ok) {
+      console.error(`refresh: provider docs answered ${res.status} — keeping the catalogue as it is`);
+      process.exit(1);
+    }
+    updates.push({
+      plane: PROVIDER_PLANE,
+      source: PROVIDER_DOCS_URL,
+      table: parseCursorDocs(await res.text()),
+    });
+  }
+
+  if ((mode === "all" || mode === FALLBACK_PLANE) && wanted(FALLBACK_PLANE, `${FALLBACK_PLANE} prices`)) {
+    const res = await fetch(LITELLM_URL);
+    if (!res.ok) {
+      console.error(`refresh: ${FALLBACK_PLANE} answered ${res.status} — keeping the catalogue as it is`);
+      process.exit(1);
+    }
+    updates.push({
+      plane: FALLBACK_PLANE,
+      source: LITELLM_URL,
+      table: parseLiteLlm((await res.json()) as Record<string, LiteLlmEntry>),
+    });
+  }
+
+  if (updates.length === 0) {
+    return;
+  }
+
+  const { catalogue, outcomes } = applyPlanes(existing, updates, new Date());
+  const refused = outcomes.filter((outcome) => !outcome.accepted);
+  if (outcomes.some((outcome) => outcome.accepted)) {
+    writeFileSync(path, `${JSON.stringify(catalogue)}\n`);
+    for (const outcome of outcomes.filter((o) => o.accepted)) {
+      console.log(`${outcome.plane}: ${outcome.count} models (${outcome.reason}) → ${path}`);
+    }
+    retireSupersededFiles(quiet);
+  }
+  for (const outcome of refused) {
+    console.error(`${outcome.plane}: ${outcome.reason}`);
+  }
+  if (refused.length > 0) {
+    process.exitCode = 1;
+  }
 }
 
-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}`);
+if (import.meta.main) {
+  await main();
 }

package/tools/uninstall-runtime.ts

@@ -37,36 +37,38 @@ export type UninstallPlan = {
 
 export type UninstallTargets = {
   home: string;
-  binLink: string;
+  binLinks: string[];
   claudeSettings: string;
   cursorHooks: string;
   skillLinks: string[];
 };
 
 /**
- * hazard: `install.ps1` does not write the same artefacts as `install.sh`. It resolves the home from
- * `USERPROFILE`, **copies** `tlc.cmd` into the bin directory instead of linking it, and puts one skill junction
- * at `~/.tlc/skills/harness-init` rather than one inside each provider's directory. Reading the POSIX layout on
- * Windows finds none of them and reports a clean machine ([/decisions/ad-066.md](/decisions/ad-066.md)).
+ * Everything an install may have left outside the runtime directory, on any machine.
+ *
+ * hazard: this used to read one layout per platform, chosen by `process.platform` — and the two installers wrote
+ * different layouts, so reading the POSIX one on Windows found none of them and reported a clean machine
+ * ([/decisions/ad-066.md](/decisions/ad-066.md)).
+ *
+ * why every name and not a branch: an uninstall has to clean up what is *there*, which includes what an older
+ * version put there. `tlc.cmd` does not exist on Linux and the legacy `~/.tlc/skills` junction does not exist on
+ * a machine installed after it was retired — an absent path is reported as nothing, so listing them all is both
+ * simpler and more complete than deciding ([/decisions/ad-097.md](/decisions/ad-097.md)).
  */
-export function uninstallTargets(
-  env: NodeJS.ProcessEnv = process.env,
-  platform: NodeJS.Platform = process.platform,
-): UninstallTargets {
-  const windows = platform === "win32";
-  const userHome = (windows ? env.USERPROFILE : env.HOME)?.trim() || homedir();
+export function uninstallTargets(env: NodeJS.ProcessEnv = process.env): UninstallTargets {
+  const userHome = homedir();
   const binDir = env.TLC_BIN_DIR?.trim() || join(userHome, ".local", "bin");
   return {
     home: runtimeHome(env),
-    binLink: join(binDir, windows ? "tlc.cmd" : "tlc"),
+    binLinks: [join(binDir, "tlc"), join(binDir, "tlc.cmd")],
     claudeSettings: join(claudeConfigDir(), "settings.json"),
     cursorHooks: join(cursorConfigDir(), "hooks.json"),
-    skillLinks: windows
-      ? [join(userHome, ".tlc", "skills", "harness-init")]
-      : [
-          join(claudeConfigDir(), "skills", "harness-init"),
-          join(cursorConfigDir(), "skills", "harness-init"),
-        ],
+    skillLinks: [
+      join(claudeConfigDir(), "skills", "harness-init"),
+      join(cursorConfigDir(), "skills", "harness-init"),
+      // the layout the PowerShell installer wrote: one junction no provider ever read
+      join(userHome, ".tlc", "skills", "harness-init"),
+    ],
   };
 }
 
@@ -312,7 +314,9 @@ export function planUninstall(targets: UninstallTargets, options: { purge?: bool
   for (const link of targets.skillLinks) {
     planLink(items, link, targets.home, "skill link", "location");
   }
-  planLink(items, targets.binLink, targets.home, "the tlc launcher on PATH", "target");
+  for (const link of targets.binLinks) {
+    planLink(items, link, targets.home, "the tlc launcher on PATH", "target");
+  }
   const homeIsLink = planRuntime(items, targets.home, purge);
   planManual(items, targets.home);
 

package/bin/tlc-build

@@ -1,80 +0,0 @@
-#!/usr/bin/env bash
-# Build Node-runnable ESM bundles under dist/. Requires Bun OR esbuild on PATH for compile.
-set -euo pipefail
-
-TLC_HOME="$(cd "$(dirname "$0")/.." && pwd)"
-DIST="$TLC_HOME/dist"
-mkdir -p "$DIST"
-
-# Derived from disk, never hardcoded: a fixed list silently stops building a new
-# entrypoint, and the missing bundle only surfaces when a hook fires in production.
-collect() {
-  local dir="$1"
-  local name
-  for path in "$dir"/*.ts; do
-    [ -e "$path" ] || continue
-    name="$(basename "$path" .ts)"
-    case "$name" in *.test) continue ;; esac
-    printf '%s\n' "$name"
-  done
-}
-
-# tools/dev/ holds the checks that validate THIS repository's own architecture, docs and conventions. They must
-# not ship — a user's clone has no src/core to validate and no docs/decisions of ours to render — and the
-# directory is the whole declaration: `collect` reads one level, so nothing under tools/dev is ever a bundle.
-# The list this replaced named four while ten qualified, and the six that were added later shipped for weeks.
-
-# macOS ships bash 3.2, which has no mapfile — read into arrays the portable way instead.
-ENTRYPOINTS=()
-while IFS= read -r name; do
-  [ -n "$name" ] && ENTRYPOINTS+=("$name")
-done < <(collect "$TLC_HOME/src/entrypoints")
-
-TOOLS=()
-while IFS= read -r name; do
-  [ -n "$name" ] && TOOLS+=("$name")
-done < <(collect "$TLC_HOME/tools")
-
-build_one() {
-  local src="$1"
-  local out="$2"
-  if command -v bun >/dev/null 2>&1; then
-    bun build --target=node --format=esm --outfile="$out" "$src"
-    return
-  fi
-  if command -v esbuild >/dev/null 2>&1; then
-    esbuild --bundle --platform=node --format=esm --outfile="$out" "$src"
-    return
-  fi
-  echo "tlc-build: need Bun or esbuild to compile TypeScript → dist/" >&2
-  echo "  Install Node.js 24+ (Active LTS) or 26 Current, then either Bun or: npm i -g esbuild" >&2
-  exit 1
-}
-
-echo "tlc-build → $DIST"
-for name in "${ENTRYPOINTS[@]}"; do
-  build_one "$TLC_HOME/src/entrypoints/${name}.ts" "$DIST/${name}.mjs"
-done
-for name in "${TOOLS[@]}"; do
-  build_one "$TLC_HOME/tools/${name}.ts" "$DIST/${name}.mjs"
-done
-
-build_one "$TLC_HOME/bin/tlc-cli.ts" "$DIST/tlc-cli.mjs"
-
-chmod +x "$TLC_HOME/bin/tlc" "$TLC_HOME/bin/tlc-exec" "$TLC_HOME/bin/tlc-build"
-
-# A bundle whose source moved or was deleted is not rebuilt, so it is also never diffed — it simply stays in
-# dist/ and ships. Deriving what to remove from the same disk that decides what to build closes that.
-for bundle in "$DIST"/*.mjs; do
-  [ -e "$bundle" ] || continue
-  name="$(basename "$bundle" .mjs)"
-  if [ "$name" = "tlc-cli" ] ||
-     [ -f "$TLC_HOME/src/entrypoints/${name}.ts" ] ||
-     [ -f "$TLC_HOME/tools/${name}.ts" ]; then
-    continue
-  fi
-  echo "tlc-build: pruning $name.mjs — no source"
-  rm -f "$bundle"
-done
-
-echo "tlc-build: ok ($(ls -1 "$DIST"/*.mjs | wc -l) bundles)"

package/bin/tlc-exec

@@ -1,10 +0,0 @@
-#!/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

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