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

package/dist/tool-after.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5266,6 +5273,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";
@@ -5569,6 +5632,69 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  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) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6822,21 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  pricing: {
+    freshness,
+    freshnessMessage,
+    mayReplace,
+    shouldRefetch
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,
@@ -6880,6 +7021,11 @@ var coreFacade = {
 // src/platform/pricing.ts
 import { existsSync as existsSync25, readFileSync as readFileSync27 } from "node:fs";
 import { join as join26 } from "node:path";
+var FALLBACK_PLANE = "litellm";
+var MODEL_ALIASES = {
+  "cursor-grok-4.5": "grok-4.5",
+  auto: "auto-cost"
+};
 var VENDOR_TO_NEUTRAL_POOL = {
   cursor_models: "provider_native",
   anthropic_models: "provider_native",
@@ -6890,16 +7036,6 @@ var VENDOR_TO_NEUTRAL_POOL = {
 function mapPoolToNeutral(pool) {
   return VENDOR_TO_NEUTRAL_POOL[pool];
 }
-function readJsonFile2(path) {
-  if (!existsSync25(path)) {
-    return null;
-  }
-  try {
-    return JSON.parse(readFileSync27(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
 function stripMeta(table) {
   if (!table) {
     return {};
@@ -6908,7 +7044,7 @@ function stripMeta(table) {
   return rest;
 }
 function slugifyModelName(name) {
-  return name.trim().toLowerCase().replace(/[[\]]/g, "").replace(/\(.*?\)/g, "").replace(/[^a-z0-9.+]+/g, "-").replace(/^-+|-+$/g, "");
+  return name.trim().toLowerCase().replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/[[\]]/g, "").replace(/[^a-z0-9.+]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function candidatesFor(model, aliases) {
   const trimmed = model.trim();
@@ -6945,28 +7081,55 @@ function fuzzyFind(table, needle) {
   }
   return;
 }
-function overridesPath() {
+function cataloguePath() {
   return join26(runtimeHome(), "model-prices.json");
 }
-function providerNativePath(provider) {
-  return join26(runtimeHome(), `model-prices.${provider}.json`);
+function overridesPath() {
+  return join26(runtimeHome(), "model-prices.local.json");
+}
+var cache = new Map;
+function readCatalogue(path) {
+  if (!existsSync25(path)) {
+    cache.delete(path);
+    return null;
+  }
+  let text;
+  try {
+    text = readFileSync27(path, "utf8");
+  } catch {
+    cache.delete(path);
+    return null;
+  }
+  const hit = cache.get(path);
+  if (hit && hit.text === text) {
+    return hit.value;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    cache.delete(path);
+    return null;
+  }
+  cache.set(path, { text, value: parsed });
+  return parsed;
 }
-function litellmPath() {
-  return join26(runtimeHome(), "model-prices.litellm.json");
+function loadCatalogue() {
+  return readCatalogue(cataloguePath()) ?? {};
 }
-function aliasesPath() {
-  return join26(runtimeHome(), "model-aliases.json");
+function planeFor(catalogue, plane) {
+  return stripMeta(catalogue.planes?.[plane] ?? null);
 }
 function resolveModelPrice(provider, model) {
   const trimmed = model.trim();
   if (!trimmed) {
     return;
   }
-  const overrides = stripMeta(readJsonFile2(overridesPath()));
-  const native = stripMeta(readJsonFile2(providerNativePath(provider)));
-  const litellm = stripMeta(readJsonFile2(litellmPath()));
-  const aliases = readJsonFile2(aliasesPath()) ?? {};
-  const candidates = candidatesFor(trimmed, aliases);
+  const catalogue = loadCatalogue();
+  const overrides = stripMeta(readCatalogue(overridesPath()));
+  const native = provider ? planeFor(catalogue, provider) : {};
+  const litellm = planeFor(catalogue, FALLBACK_PLANE);
+  const candidates = candidatesFor(trimmed, MODEL_ALIASES);
   for (const id of candidates) {
     const entry = overrides[id];
     if (entry) {
@@ -7831,14 +7994,9 @@ var ENTRY_SPECS2 = [
   { hookEvent: "stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
   { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" }
 ];
-function commandFor(runtime) {
-  if (process.platform === "win32") {
-    return { command: "cmd", argsPrefix: ["/c", "node", runtime.launcherPath] };
-  }
-  return { command: "node", argsPrefix: [runtime.launcherPath] };
-}
 function cursorWiring(runtime) {
-  const { command, argsPrefix } = commandFor(runtime);
+  const command = "node";
+  const argsPrefix = [runtime.launcherPath];
   const entries = ENTRY_SPECS2.map((spec) => ({
     hookEvent: spec.hookEvent,
     handler: spec.handler,

package/dist/tool-before.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5266,6 +5273,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";
@@ -5569,6 +5632,69 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  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) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6822,21 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  pricing: {
+    freshness,
+    freshnessMessage,
+    mayReplace,
+    shouldRefetch
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,
@@ -7641,14 +7782,9 @@ var ENTRY_SPECS2 = [
   { hookEvent: "stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
   { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" }
 ];
-function commandFor(runtime) {
-  if (process.platform === "win32") {
-    return { command: "cmd", argsPrefix: ["/c", "node", runtime.launcherPath] };
-  }
-  return { command: "node", argsPrefix: [runtime.launcherPath] };
-}
 function cursorWiring(runtime) {
-  const { command, argsPrefix } = commandFor(runtime);
+  const command = "node";
+  const argsPrefix = [runtime.launcherPath];
   const entries = ENTRY_SPECS2.map((spec) => ({
     hookEvent: spec.hookEvent,
     handler: spec.handler,