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

package/dist/tlc-cli.mjs

@@ -4,17 +4,16 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // bin/tlc-cli.ts
 import { spawnSync } from "node:child_process";
 import {
-  existsSync as existsSync25,
-  lstatSync,
-  mkdirSync as mkdirSync16,
+  existsSync as existsSync26,
+  lstatSync as lstatSync2,
+  mkdirSync as mkdirSync17,
   readdirSync as readdirSync6,
   readFileSync as readFileSync27,
   realpathSync,
-  rmSync as rmSync4,
+  rmSync as rmSync5,
   writeFileSync as writeFileSync15
 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { delimiter, join as join26 } from "node:path";
+import { delimiter, join as join27 } from "node:path";
 
 // src/core/attest/attest.service.ts
 import { createHash } from "node:crypto";
@@ -5284,6 +5283,62 @@ function release(root, provider, session) {
   deletePresenceRecord(root, provider, session);
 }
 
+// src/core/pricing/pricing.freshness.ts
+var DEFAULT_TTL_DAYS = 7;
+var MS_PER_DAY = 86400000;
+function freshness(meta, now, ttlDays = DEFAULT_TTL_DAYS) {
+  if (meta === null) {
+    return { state: "absent" };
+  }
+  const stamp = meta.refreshedAt;
+  if (stamp === undefined || Number.isNaN(Date.parse(stamp))) {
+    return { state: "undated" };
+  }
+  const ageMs = now.getTime() - Date.parse(stamp);
+  const ageDays = Math.max(0, ageMs / MS_PER_DAY);
+  return ageDays > ttlDays ? { state: "stale", ageDays, refreshedAt: stamp } : { state: "fresh", ageDays, refreshedAt: stamp };
+}
+function shouldRefetch(state) {
+  return state.state === "absent" || state.state === "undated" || state.state === "stale";
+}
+function freshnessMessage(state, catalogue) {
+  switch (state.state) {
+    case "absent":
+      return `${catalogue}: not on this machine — run \`tlc harness prices refresh\``;
+    case "undated":
+      return `${catalogue}: present but carries no date — it will be refetched`;
+    case "fresh":
+      return `${catalogue}: ${describeAge(state.ageDays)} old`;
+    default:
+      return `${catalogue}: ${describeAge(state.ageDays)} old — run \`tlc harness prices refresh\``;
+  }
+}
+var MIN_RETAINED_RATIO = 0.5;
+function mayReplace(existingCount, incomingCount, minRatio = MIN_RETAINED_RATIO) {
+  if (incomingCount === 0) {
+    return { replace: false, reason: "parsed no entries at all — the upstream format has changed" };
+  }
+  if (existingCount === 0) {
+    return { replace: true, reason: `first catalogue, ${incomingCount} entries` };
+  }
+  if (incomingCount >= existingCount) {
+    return { replace: true, reason: `${existingCount} → ${incomingCount} entries` };
+  }
+  const retained = incomingCount / existingCount;
+  return retained >= minRatio ? { replace: true, reason: `${existingCount} → ${incomingCount} entries` } : {
+    replace: false,
+    reason: `would drop from ${existingCount} to ${incomingCount} entries, keeping the existing catalogue — the upstream format has probably changed`
+  };
+}
+function describeAge(ageDays) {
+  if (ageDays < 1) {
+    const hours = Math.max(1, Math.round(ageDays * 24));
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  const days = Math.round(ageDays);
+  return `${days} day${days === 1 ? "" : "s"}`;
+}
+
 // src/core/release/release.decisions.ts
 import { existsSync as existsSync17, readdirSync as readdirSync5, readFileSync as readFileSync19 } from "node:fs";
 import { join as join18 } from "node:path";
@@ -5633,7 +5688,8 @@ function linkHealth(target, runtimeHome2, probe) {
   if (!probe.exists(resolved)) {
     return { state: "dangling", target, resolved };
   }
-  const home = runtimeHome2.replace(/\/+$/, "");
+  const resolveHome = probe.realpath ?? ((path) => path);
+  const home = resolveHome(runtimeHome2).replace(/\/+$/, "");
   return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
 }
 function linkHealthMessage(health) {
@@ -6780,6 +6836,12 @@ var coreFacade = {
     coversHandler,
     decideShim
   },
+  pricing: {
+    freshness,
+    freshnessMessage,
+    mayReplace,
+    shouldRefetch
+  },
   skill: {
     linkHealth,
     linkHealthMessage,
@@ -6991,6 +7053,43 @@ function unknownFlags(args) {
   return args.filter((arg) => arg.startsWith("--"));
 }
 
+// src/platform/links.ts
+import { copyFileSync, existsSync as existsSync25, lstatSync, mkdirSync as mkdirSync16, rmSync as rmSync4, symlinkSync } from "node:fs";
+import { dirname as dirname7, join as join26 } from "node:path";
+var LINK_TYPE = "junction";
+function linkDir(source, target) {
+  let replaced = false;
+  if (isLink(target)) {
+    rmSync4(target, { recursive: true, force: true });
+    replaced = true;
+  } else if (existsSync25(target)) {
+    return {
+      kind: "refused",
+      target,
+      reason: `${target} exists and is not a link — move it aside and re-run`
+    };
+  }
+  mkdirSync16(dirname7(target), { recursive: true });
+  symlinkSync(source, target, LINK_TYPE);
+  return { kind: replaced ? "relinked" : "linked", target, source };
+}
+function isLink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+function seedConfig(dest) {
+  const path = join26(dest, "config.json");
+  const example = join26(dest, "config.example.json");
+  if (existsSync25(path) || !existsSync25(example)) {
+    return { seeded: false, path };
+  }
+  copyFileSync(example, path);
+  return { seeded: true, path };
+}
+
 // bin/tlc-cli.ts
 class UsageError extends Error {
 }
@@ -6998,22 +7097,22 @@ function resolveProjectRoot() {
   return process.env.TLC_PROJECT_DIR ?? process.cwd();
 }
 function modeFilePath(root) {
-  return join26(projectStateDir(root), "harness-mode");
+  return join27(projectStateDir(root), "harness-mode");
 }
 function grindFlagPath(root) {
-  return join26(flagsDir(root), "grind-on");
+  return join27(flagsDir(root), "grind-on");
 }
 function skipFlagPath(root) {
-  return join26(flagsDir(root), "skip-verify");
+  return join27(flagsDir(root), "skip-verify");
 }
 function focusFlagPath(root) {
-  return join26(flagsDir(root), "focus");
+  return join27(flagsDir(root), "focus");
 }
 function pairedFlagPath(root) {
-  return join26(flagsDir(root), "paired");
+  return join27(flagsDir(root), "paired");
 }
 function ensureFlagsDir(root) {
-  mkdirSync16(flagsDir(root), { recursive: true });
+  mkdirSync17(flagsDir(root), { recursive: true });
 }
 function readMode(root) {
   return coreFacade.policy.loadPolicy(root).mode;
@@ -7022,7 +7121,7 @@ function grindOn(root) {
   return coreFacade.policy.loadPolicy(root).grind.enabled;
 }
 function gatesPaused(root) {
-  return existsSync25(skipFlagPath(root));
+  return existsSync26(skipFlagPath(root));
 }
 function acceptedModes() {
   return coreFacade.policy.OPERATOR_MODES.join(" | ");
@@ -7084,8 +7183,8 @@ function setGrind(root, on) {
     coreFacade.policy.refreshPolicyBaselines(root);
     return "grind ON — stop hook will lint/test and auto-retry on failure";
   }
-  if (existsSync25(path)) {
-    rmSync4(path);
+  if (existsSync26(path)) {
+    rmSync5(path);
   }
   coreFacade.policy.refreshPolicyBaselines(root);
   return "grind OFF — no auto fix loops";
@@ -7098,8 +7197,8 @@ function setPaused(root, on) {
     coreFacade.policy.refreshPolicyBaselines(root);
     return "gates PAUSED — stop checks disabled until `tlc harness resume`";
   }
-  if (existsSync25(path)) {
-    rmSync4(path);
+  if (existsSync26(path)) {
+    rmSync5(path);
   }
   coreFacade.policy.refreshPolicyBaselines(root);
   return "gates ACTIVE again";
@@ -7321,30 +7420,30 @@ function classifyRuntimePath(dest, probe) {
   if (!probe.exists(dest)) {
     return "absent";
   }
-  if (probe.exists(join26(dest, ".git"))) {
+  if (probe.exists(join27(dest, ".git"))) {
     return "managed";
   }
-  return probe.exists(join26(dest, NPM_MARKER)) ? "npm" : "unmanaged";
+  return probe.exists(join27(dest, NPM_MARKER)) ? "npm" : "unmanaged";
 }
 function runtimePathKind(dest) {
   return classifyRuntimePath(dest, {
     isSymlink: (path) => {
       try {
-        return lstatSync(path).isSymbolicLink();
+        return lstatSync2(path).isSymbolicLink();
       } catch {
         return false;
       }
     },
-    exists: existsSync25
+    exists: existsSync26
   });
 }
 function missingBundles(dest) {
-  const entrypoints = join26(dest, "src", "entrypoints");
-  if (!existsSync25(entrypoints)) {
+  const entrypoints = join27(dest, "src", "entrypoints");
+  if (!existsSync26(entrypoints)) {
     return [];
   }
   const expected = readdirSync6(entrypoints).filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts")).map((name) => `${name.slice(0, -3)}.mjs`);
-  return expected.filter((bundle) => !existsSync25(join26(dest, "dist", bundle)));
+  return expected.filter((bundle) => !existsSync26(join27(dest, "dist", bundle)));
 }
 function linkedRuntimeMessage(dest, target) {
   return [
@@ -7392,7 +7491,7 @@ function resetFailureMessage(dest, mergeRef, gitOutput) {
 `);
 }
 function runtimeRevision(dest) {
-  if (!existsSync25(join26(dest, ".git"))) {
+  if (!existsSync26(join27(dest, ".git"))) {
     return { revision: null, date: null };
   }
   const read = (args) => {
@@ -7435,7 +7534,7 @@ function versionText(root, style = PLAIN) {
   return render(versionScreen(root), style);
 }
 function pendingUpdate(dest, mergeRef) {
-  if (!existsSync25(join26(dest, ".git"))) {
+  if (!existsSync26(join27(dest, ".git"))) {
     return { ok: false, reason: "the runtime path is not a git checkout", commits: 0, decisions: [] };
   }
   const fetch = spawnSync("git", ["-C", dest, "fetch", "origin"], { stdio: "inherit", env: process.env });
@@ -7486,17 +7585,17 @@ var GATE_FIELDS = {
   "test-command": "test",
   "lint-command": "lint"
 };
-function resolveExecutable(name, env = process.env, platform = process.platform) {
-  const extensions = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-  const candidates = (base) => [base, ...extensions.map((ext) => `${base}${ext}`)];
+var EXECUTABLE_EXTENSIONS = ["", ".exe", ".cmd", ".bat", ".ps1"];
+function resolveExecutable(name, env = process.env) {
+  const candidates = (base) => EXECUTABLE_EXTENSIONS.map((ext) => `${base}${ext}`);
   if (name.includes("/") || name.includes("\\")) {
-    return candidates(name).find((candidate) => existsSync25(candidate)) ?? null;
+    return candidates(name).find((candidate) => existsSync26(candidate)) ?? null;
   }
   for (const dir of (env.PATH ?? "").split(delimiter)) {
     if (!dir) {
       continue;
     }
-    const found = candidates(join26(dir, name)).find((candidate) => existsSync25(candidate));
+    const found = candidates(join27(dir, name)).find((candidate) => existsSync26(candidate));
     if (found) {
       return found;
     }
@@ -7515,11 +7614,11 @@ function setGateCommand(root, field, argv, interactive) {
     throw new UsageError(`\`${binary}\` was not found on PATH, and a gate command that cannot run is a config fault ([/decisions/ad-021.md](/decisions/ad-021.md)).`);
   }
   const path = projectConfigPath(root);
-  const parsed = existsSync25(path) ? JSON.parse(readFileSync27(path, "utf8")) : {};
+  const parsed = existsSync26(path) ? JSON.parse(readFileSync27(path, "utf8")) : {};
   const grind = { ...parsed.grind ?? {} };
   grind[field === "test" ? "testCommand" : "lintCommand"] = argv;
   parsed.grind = grind;
-  mkdirSync16(join26(root, ".tlc", "harness"), { recursive: true });
+  mkdirSync17(join27(root, ".tlc", "harness"), { recursive: true });
   writeFileSync15(path, `${JSON.stringify(parsed, null, 2)}
 `, "utf8");
   coreFacade.policy.refreshPolicyBaselines(root);
@@ -7575,23 +7674,25 @@ function helpText(style = PLAIN) {
 }
 function pricesHelpScreen() {
   return {
-    title: "price catalogs",
+    title: "prices",
     sections: [
       {
-        lines: `  tlc harness prices refresh [all|cursor|litellm]
+        lines: `  tlc harness prices refresh [all|cursor|litellm] [--if-stale]
   tlc harness prices lookup <model-id>
 
-  refresh / refresh all   Cursor catalog + LiteLLM fallback
-  refresh cursor          model-prices.cursor.json (tracked)
-  refresh litellm         model-prices.litellm.json (local)
+  refresh / refresh all   both planes of model-prices.json
+  refresh cursor          the provider's own rates
+  refresh litellm         the vendors' list prices
+  --if-stale              fetch only past the 7-day TTL
   lookup <model-id>       catalog key, pool, USD for 1M in + 1M out
 
-  Resolution: overrides → Cursor → LiteLLM → null
+  Catalogue: <runtime home>/model-prices.json — fetched per machine, never versioned
+  Overrides: <runtime home>/model-prices.local.json — yours, hand-written
   Documentation: tlc harness help prices`.split(`
 `)
       }
     ],
-    footer: "resolution: local overrides → the provider's own catalog → LiteLLM → null"
+    footer: "resolution: your overrides → the asking provider's plane → the vendor plane → null"
   };
 }
 function pricesHelpText(style = PLAIN) {
@@ -7605,11 +7706,37 @@ function resolveHarnessRoot() {
     return home;
   }
 }
+function wireRuntime(dest, home) {
+  const lines = [];
+  const seeded = seedConfig(dest);
+  if (seeded.seeded) {
+    lines.push(`config seeded → ${seeded.path}`);
+  }
+  if (!existsSync26(join27(dest, "skills", "harness-init"))) {
+    return { lines, missingSkill: true };
+  }
+  const links = coreFacade.skill.skillLinks(dest, providerConfigDirs(), existsSync26);
+  if (links.length === 0) {
+    lines.push("no provider config dir found — skill not linked");
+  }
+  for (const link of links) {
+    const outcome = linkDir(link.source, link.target);
+    lines.push(outcome.kind === "refused" ? `skill not linked — ${outcome.reason}` : `skill → ${outcome.target}`);
+  }
+  const hooks = spawnSync(process.execPath, [join27(dest, "bin", "write-user-hooks.mjs")], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_HOME: home }
+  });
+  if ((hooks.status ?? 1) !== 0) {
+    lines.push("hooks unchanged (merge manually or: node bin/write-user-hooks.mjs --force)");
+  }
+  return { lines, missingSkill: false };
+}
 function execBinPath() {
-  return join26(resolveHarnessRoot(), "bin", "tlc-exec");
+  return join27(resolveHarnessRoot(), "bin", "tlc-exec.mjs");
 }
 function buildBinPath() {
-  return join26(resolveHarnessRoot(), "bin", "tlc-build");
+  return join27(resolveHarnessRoot(), "bin", "tlc-build.mjs");
 }
 function route(args) {
   const cmd = (args[0] ?? "status").toLowerCase();
@@ -7815,7 +7942,7 @@ function runUpdate(root) {
   const revisionBefore = runtimeRevision(dest).revision;
   const home = runtimeHome();
   console.log(`update: runtime → ${dest}`);
-  if (!existsSync25(join26(dest, "bin", "tlc-exec.mjs"))) {
+  if (!existsSync26(join27(dest, "bin", "tlc-exec.mjs"))) {
     console.error(`update: missing install at ${home}`);
     console.error(`update: install once with \`npm i -g ${NPM_PACKAGE}\`, then \`tlc harness install\`, then retry.`);
     process.exit(1);
@@ -7827,13 +7954,16 @@ function runUpdate(root) {
     const bump = spawnSync("npm", ["install", "-g", `${NPM_PACKAGE}@latest`], {
       stdio: "inherit",
       env: process.env,
-      shell: process.platform === "win32"
+      shell: true
     });
     if ((bump.status ?? 1) !== 0) {
       console.error(npmUpdateFailureMessage());
       process.exit(bump.status ?? 1);
     }
-    const sync = spawnSync(execBinPath(), ["install-runtime"], { stdio: "inherit", env: process.env });
+    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+      stdio: "inherit",
+      env: process.env
+    });
     if ((sync.status ?? 1) !== 0) {
       process.exit(sync.status ?? 1);
     }
@@ -7860,57 +7990,32 @@ function runUpdate(root) {
     const after = runtimeRevision(dest).revision;
     console.log(revisionBefore === after ? `update: runtime already at ${after ?? "unknown"} — nothing to move` : `update: runtime ${revisionBefore ?? "unknown"} → ${after ?? "unknown"}`);
   }
-  const binDir = process.env.TLC_BIN_DIR || join26(homedir3(), ".local", "bin");
-  mkdirSync16(binDir, { recursive: true });
-  if (process.platform === "win32") {
-    const installPs1 = join26(dest, "install.ps1");
-    const r = spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", installPs1], {
-      stdio: "inherit",
-      env: { ...process.env, TLC_HOME: home },
-      cwd: dest
-    });
-    if ((r.status ?? 1) !== 0) {
-      process.exit(r.status ?? 1);
-    }
-  } else {
-    const tlcBin = join26(dest, "bin", "tlc");
-    const skillSrc = join26(dest, "skills", "harness-init");
-    spawnSync("ln", ["-sfn", tlcBin, join26(binDir, "tlc")], { stdio: "inherit" });
-    if (!existsSync25(skillSrc)) {
-      console.error(`update: missing skill at ${skillSrc}`);
-      process.exit(1);
-    }
-    const links = coreFacade.skill.skillLinks(dest, providerConfigDirs(), existsSync25);
-    if (links.length === 0) {
-      console.log("update: no provider config dir found — skill not linked");
-    }
-    for (const link of links) {
-      mkdirSync16(join26(link.providerDir, "skills"), { recursive: true });
-      spawnSync("ln", ["-sfn", link.source, link.target], { stdio: "inherit" });
-      console.log(`update: skill → ${link.target}`);
-    }
-    const hooks = spawnSync(process.execPath, [join26(dest, "bin", "write-user-hooks.mjs")], {
-      stdio: "inherit",
-      env: { ...process.env, TLC_HOME: home }
-    });
-    if ((hooks.status ?? 1) !== 0) {
-      console.log("update: hooks unchanged (merge manually or: node bin/write-user-hooks.mjs --force)");
-    }
+  const wired = wireRuntime(dest, home);
+  for (const line of wired.lines) {
+    console.log(`update: ${line}`);
+  }
+  if (wired.missingSkill) {
+    console.error(`update: missing skill at ${join27(dest, "skills", "harness-init")}`);
+    process.exit(1);
   }
   const missing = missingBundles(dest);
   if (missing.length === 0) {
     console.log("update: dist/ complete — no rebuild, so the runtime path stays clean");
-  } else if (existsSync25(buildBinPath())) {
+  } else if (existsSync26(buildBinPath())) {
     console.log(`update: ${missing.length} bundle(s) missing — building`);
-    const build = spawnSync(buildBinPath(), [], { stdio: "inherit", env: process.env });
+    const build = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
     if ((build.status ?? 1) !== 0) {
       console.log(`update: build failed — ${missing.length} bundle(s) still missing from dist/`);
     }
   }
   announceNewCapabilities(root, dest);
   announceLandedDecisions(root, dest, revisionBefore);
+  spawnSync(process.execPath, [execBinPath(), "refresh-model-prices", "all", "--if-stale"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_PROJECT_DIR: root }
+  });
   console.log("update: running doctor…");
-  const doctor = spawnSync(execBinPath(), ["doctor"], {
+  const doctor = spawnSync(process.execPath, [execBinPath(), "doctor"], {
     stdio: "inherit",
     env: { ...process.env, TLC_PROJECT_DIR: root }
   });
@@ -7918,7 +8023,7 @@ function runUpdate(root) {
   process.exit(doctor.status ?? 0);
 }
 function runEntry(entry, toolArgs, root) {
-  const r = spawnSync(execBinPath(), [entry, ...toolArgs], {
+  const r = spawnSync(process.execPath, [execBinPath(), entry, ...toolArgs], {
     stdio: "inherit",
     env: { ...process.env, TLC_PROJECT_DIR: root }
   });
@@ -8013,7 +8118,7 @@ function main(argv) {
       console.log(helpText(createStyle()));
       break;
     case "build": {
-      const r = spawnSync(buildBinPath(), [], { stdio: "inherit", env: process.env });
+      const r = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
       process.exit(r.status ?? 1);
       break;
     }
@@ -8095,6 +8200,7 @@ if (__require.main == __require.module) {
   main(process.argv.slice(2));
 }
 export {
+  wireRuntime,
   versionText,
   versionScreen,
   versionJson,