@tech-leads-club/harness-toolkit 0.3.6 → 0.4.0

package/tools/help-topic.ts

@@ -5,22 +5,34 @@ import { runtimeHome } from "../src/platform/paths.ts";
 const docsDir = join(runtimeHome(), "docs");
 const topic = (process.argv[2] ?? "").toLowerCase();
 
-const TOPICS: Record<string, string> = {
-  architecture: "architecture.md",
-  concepts: "concepts.md",
-  measure: "measure.md",
-  metrics: "measure.md",
-  prices: "measure.md",
-  price: "measure.md",
-  cost: "measure.md",
-  costs: "measure.md",
-  diagnose: "diagnose.md",
-  doctor: "diagnose.md",
-  debug: "diagnose.md",
-  init: "init.md",
-  setup: "init.md",
-  lessons: "lessons.md",
-  lesson: "lessons.md",
+/**
+ * A topic is a document, or one heading inside one. `section` exists because two topics live inside a larger
+ * document and printing the whole of it would bury the answer.
+ */
+type Topic = { file: string; section?: string };
+
+const TOPICS: Record<string, Topic> = {
+  architecture: { file: "architecture.md" },
+  concepts: { file: "concepts.md" },
+  measure: { file: "measure.md" },
+  metrics: { file: "measure.md" },
+  prices: { file: "measure.md", section: "## Prices" },
+  price: { file: "measure.md", section: "## Prices" },
+  cost: { file: "measure.md", section: "## Prices" },
+  costs: { file: "measure.md", section: "## Prices" },
+  diagnose: { file: "diagnose.md" },
+  doctor: { file: "diagnose.md" },
+  debug: { file: "diagnose.md" },
+  init: { file: "init.md" },
+  setup: { file: "init.md" },
+  lessons: { file: "lessons.md" },
+  lesson: { file: "lessons.md" },
+  rules: { file: "concepts.md", section: "## operator rules" },
+  rule: { file: "concepts.md", section: "## operator rules" },
+  runtime: { file: "concepts.md", section: "## which runtime answers a hook" },
+  dev: { file: "concepts.md", section: "## which runtime answers a hook" },
+  settings: { file: "concepts.md", section: "## where a setting lives" },
+  config: { file: "concepts.md", section: "## where a setting lives" },
 };
 
 function printIndex(): void {
@@ -30,6 +42,9 @@ TOPICS
   tlc harness help architecture
   tlc harness help concepts
   tlc harness help lessons
+  tlc harness help rules
+  tlc harness help settings
+  tlc harness help runtime
   tlc harness help measure
   tlc harness help prices
   tlc harness help diagnose
@@ -49,25 +64,26 @@ if (!topic || topic === "help" || topic === "-h" || topic === "--help") {
   process.exit(0);
 }
 
-const file = TOPICS[topic];
-if (!file) {
+const entry = TOPICS[topic];
+if (!entry) {
   console.error(`unknown topic: ${topic}`);
   printIndex();
   process.exit(1);
 }
 
-const path = join(docsDir, file);
+const path = join(docsDir, entry.file);
 if (!existsSync(path)) {
   console.error(`missing doc: ${path}`);
   process.exit(1);
 }
 
 let body = readFileSync(path, "utf8");
-if (topic === "prices" || topic === "price" || topic === "cost" || topic === "costs") {
-  const marker = "## Prices";
-  const idx = body.indexOf(marker);
+if (entry.section) {
+  const idx = body.indexOf(entry.section);
+  // why the whole document when the heading is absent: an answer from the wrong version of a doc beats no answer,
+  // and the section check already runs in the gate.
   if (idx >= 0) {
-    body = `# Prices\n\n${body.slice(idx)}`;
+    body = body.slice(idx);
   }
 }
 

package/tools/init-project.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
 import { applyCursorWiring, renderCursorHooksDocument } from "../bin/write-user-hooks.mjs";
 import type { WiringEntry } from "../src/contracts/index.ts";
+import { coreFacade } from "../src/core/index.ts";
 import { DEFAULTS } from "../src/core/policy/policy.defaults.ts";
 import { claudeConfigDir, cursorConfigDir, projectConfigPath, runtimeHome } from "../src/platform/paths.ts";
 import { render, type Screen } from "../src/platform/screen.ts";
@@ -150,17 +151,37 @@ export function mergeGitignore(root: string): { text: string; changed: boolean }
   return { text: `${withoutTrailingBlank.join("\n").replace(/\n+$/, "")}\n`, changed: true };
 }
 
+/**
+ * hazard: this returned `DEFAULTS` whole, and the wizard's `--stdin-json` carried every knob it had collected. Both
+ * wrote values nobody chose, and each one shadows the machine tier for ever — raise a number there afterwards and
+ * no such project sees it. Measured on one repository: 29 keys restating the tiers below
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: pruning cannot change the effective policy, because a leaf is dropped only when the tiers below
+ * already resolve to it. An existing config is still returned untouched — rewriting an operator's file is not
+ * this command's business.
+ */
 export function resolvePolicy(root: string, flags: InitFlags, stdinText: string | null): unknown {
   if (flags.stdinJson && !flags.minimal) {
     if (!stdinText || stdinText.trim() === "") {
       throw new Error("stdin-json: empty stdin");
     }
-    return JSON.parse(stdinText);
+    return prune(JSON.parse(stdinText) as Record<string, unknown>);
   }
   if (!flags.minimal && !flags.stdinJson && existsSync(projectConfigPath(root))) {
     return JSON.parse(readFileSync(projectConfigPath(root), "utf8"));
   }
-  return DEFAULTS;
+  /**
+   * hazard: this returned `DEFAULTS`, and pruning it was not enough. Against a machine tier that enabled things,
+   * the shipped defaults *differ* — so a fresh project wrote `comments.enabled: false` and turned off, in that
+   * repository, a capability the operator had switched on for the machine. A project that has decided nothing must
+   * say nothing ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   */
+  return { version: DEFAULTS.version };
+}
+
+function prune(policy: Record<string, unknown>): Record<string, unknown> {
+  return coreFacade.policy.pruneShadowed(policy, coreFacade.policy.resolvedWithoutProjectTier());
 }
 
 export type ProviderPresence = { cursor: boolean; claude: boolean };
@@ -197,10 +218,22 @@ export function buildPlan(
 
 export type ApplyOutcome = {
   configPath: string;
+  /** why reported: silence after keeping a file reads as having written it. */
+  configKept: boolean;
   cursor: { skipped: true } | { skipped: false; status: string; target: string };
   claude: { skipped: true } | { skipped: false; status: string; target: string };
 };
 
+/**
+ * why exported: the repository's convention is that text is built by a named function and printed by the caller,
+ * so what an operator reads can be asserted. Silence after keeping a file reads as having written it.
+ */
+export function configLine(outcome: ApplyOutcome): string {
+  return outcome.configKept
+    ? `kept ${outcome.configPath} — already configured; delete it to start over, or run the wizard to replace it`
+    : `wrote ${outcome.configPath}`;
+}
+
 export function applyPlan(
   root: string,
   flags: InitFlags,
@@ -209,8 +242,20 @@ export function applyPlan(
 ): ApplyOutcome {
   const policy = resolvePolicy(root, flags, stdinText);
   const configPath = projectConfigPath(root);
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+  /**
+   * hazard: this wrote unconditionally. `init --minimal` on a configured project replaced the operator's file —
+   * with the whole default policy before, with a bare version marker after that changed. Both destroy choices
+   * nobody asked to undo, and neither said so ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   *
+   * invariant: an existing config is replaced only when the operator supplied one to replace it with. That is what
+   * `--stdin-json` is — the wizard's collected answers — and it is the one route that carries consent. Everything
+   * else keeps the file. This is the rule `linkDir` already follows: a real file at the target is somebody's work.
+   */
+  const kept = existsSync(configPath) && !flags.stdinJson;
+  if (!kept) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+  }
 
   const launcher = launcherPath();
 
@@ -242,7 +287,7 @@ export function applyPlan(
   const gitignore = mergeGitignore(root);
   writeFileSync(join(root, ".gitignore"), gitignore.text);
 
-  return { configPath, cursor, claude };
+  return { configPath, configKept: kept, cursor, claude };
 }
 
 async function readStdin(): Promise<string> {
@@ -270,7 +315,7 @@ export async function main(argv: string[]): Promise<void> {
   }
 
   const outcome = applyPlan(root, flags, presence, stdinText);
-  console.log(`wrote ${outcome.configPath}`);
+  console.log(configLine(outcome));
   if (outcome.cursor.skipped) {
     console.log("init: cursor not installed — skipped project hooks.json");
   } else {

package/tools/install-runtime.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE, wireRuntime } from "../bin/tlc-cli.ts";
 import { linkDir } from "../src/platform/links.ts";
@@ -71,8 +71,29 @@ export function originRoot(env: NodeJS.ProcessEnv = process.env): string {
   return home && home.length > 0 ? resolve(home) : conventionalRuntimeHome();
 }
 
+/**
+ * hazard: this compared `resolve(source)` with `resolve(dest)`, and `resolve` does not follow a symlink. An
+ * operator who installed with `--link` has a runtime home that *is* a link to their checkout, so the two paths
+ * differed lexically while naming the same directory — the in-place guard missed, `rmSync` followed the link, and
+ * the first entry of the payload deleted the checkout's own `bin/` before `cpSync` failed on the source it had
+ * just removed. Measured on this repository: the gate ate its own `bin/` ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why the fallback: a destination that does not exist yet has no real path, and a first install is exactly that
+ * case. Then the lexical answer is the only one there is, and it is correct — nothing is there to alias.
+ */
+function samePlace(a: string, b: string): boolean {
+  const real = (path: string): string => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return resolve(path);
+    }
+  };
+  return real(a) === real(b);
+}
+
 export function installRuntime(source: string, dest: string): InstallReport {
-  if (resolve(source) === resolve(dest)) {
+  if (samePlace(source, dest)) {
     // why: the git route already has the code at the destination. Copying a directory onto itself is the one
     // input that turns a sync into data loss.
     return { kind: "in-place", source, dest, entries: [], missing: [] };

package/tools/lessons-cli.ts

@@ -159,7 +159,10 @@ export function listScreen(report: LessonsListReport): Screen {
         },
         { label: "notes", value: notes.join("  ") },
       ],
-      lines: ["", row.instruction.slice(0, 160)],
+      // why the whole instruction: it is the operator's own text, and a slice with no marker is how 103
+      // characters of a 263-character lesson vanished mid-word ([/decisions/ad-101.md](/decisions/ad-101.md)).
+      lines: ["", row.instruction],
+      wrap: true,
     });
   }
 

package/tools/refresh-model-prices.ts

@@ -2,7 +2,7 @@
 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 { machineHome } from "../src/platform/paths.ts";
 import {
   cataloguePath,
   FALLBACK_PLANE,
@@ -23,7 +23,7 @@ import {
  *
  * invariant: written where it is read. One resolution, `runtimeHome()`, used by both sides.
  */
-const HARNESS_HOME = runtimeHome();
+const HARNESS_HOME = machineHome();
 
 /**
  * The plane a provider's own rates land in. It is the provider's id, because the catalogue is keyed by who bills

package/tools/uninstall-runtime.ts

@@ -12,7 +12,13 @@ import {
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE } from "../bin/tlc-cli.ts";
-import { claudeConfigDir, cursorConfigDir, runtimeHome } from "../src/platform/paths.ts";
+import {
+  claudeConfigDir,
+  cursorConfigDir,
+  launcherBinDir,
+  launcherNames,
+  runtimeHome,
+} 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";
 import { removeClaudeWiring, unmergeClaudeSettings } from "../src/providers/claude/claude.wiring.ts";
@@ -57,10 +63,12 @@ export type UninstallTargets = {
  */
 export function uninstallTargets(env: NodeJS.ProcessEnv = process.env): UninstallTargets {
   const userHome = homedir();
-  const binDir = env.TLC_BIN_DIR?.trim() || join(userHome, ".local", "bin");
+  // invariant: the same definition install links into, so what one creates the other removes
+  // ([/decisions/ad-101.md](/decisions/ad-101.md)).
+  const binDir = launcherBinDir(env);
   return {
     home: runtimeHome(env),
-    binLinks: [join(binDir, "tlc"), join(binDir, "tlc.cmd")],
+    binLinks: launcherNames().map((name) => join(binDir, name)),
     claudeSettings: join(claudeConfigDir(), "settings.json"),
     cursorHooks: join(cursorConfigDir(), "hooks.json"),
     skillLinks: [