@tech-leads-club/harness-toolkit 0.2.1

package/tools/help-topic.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+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",
+};
+
+function printIndex(): void {
+  console.log(`tlc harness help
+
+TOPICS
+  tlc harness help architecture
+  tlc harness help concepts
+  tlc harness help lessons
+  tlc harness help measure
+  tlc harness help prices
+  tlc harness help diagnose
+  tlc harness help init
+
+PRICES
+  tlc harness prices refresh [all|cursor|litellm]
+  tlc harness prices lookup <model-id>
+
+ALSO
+  tlc harness status | doctor | grind | mode | obs | lessons
+`);
+}
+
+if (!topic || topic === "help" || topic === "-h" || topic === "--help") {
+  printIndex();
+  process.exit(0);
+}
+
+const file = TOPICS[topic];
+if (!file) {
+  console.error(`unknown topic: ${topic}`);
+  printIndex();
+  process.exit(1);
+}
+
+const path = join(docsDir, 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 (idx >= 0) {
+    body = `# Prices\n\n${body.slice(idx)}`;
+  }
+}
+
+process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);

package/tools/init-project.ts

@@ -0,0 +1,277 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { applyCursorWiring, renderCursorHooksDocument } from "../bin/write-user-hooks.mjs";
+import type { WiringEntry } from "../src/contracts/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";
+import { PLAIN, type Style } from "../src/platform/style.ts";
+import { applyClaudeWiring } from "../src/providers/claude/claude.wiring.ts";
+
+export class UsageError extends Error {}
+
+export type InitFlags = {
+  dryRun: boolean;
+  write: boolean;
+  minimal: boolean;
+  stdinJson: boolean;
+  force: boolean;
+};
+
+export function parseFlags(args: readonly string[]): InitFlags {
+  return {
+    dryRun: args.includes("--dry-run"),
+    write: args.includes("--write") || args.includes("--minimal"),
+    minimal: args.includes("--minimal"),
+    stdinJson: args.includes("--stdin-json"),
+    force: args.includes("--force"),
+  };
+}
+
+export function usageScreen(): Screen {
+  return {
+    title: "harness init",
+    sections: [
+      {
+        lines: `  tlc harness init --dry-run
+  tlc harness init --write [--stdin-json] [--force]
+  tlc harness init --minimal
+
+--minimal writes a safe agnostic stub (grind/ship off). Prefer the harness-init skill for full discovery.`.split(
+          "\n",
+        ),
+      },
+    ],
+  };
+}
+
+// why: plain by default and never given a style here — the only caller throws it as a UsageError, and an error
+// message is printed on a path that may be redirected.
+export function usageText(style: Style = PLAIN): string {
+  return render(usageScreen(), style);
+}
+
+export function launcherPath(home = runtimeHome()): string {
+  return join(home, "bin", "tlc-exec.mjs");
+}
+
+function shimCommand(platform = process.platform): { command: string; argsPrefix: string[] } {
+  if (platform === "win32") {
+    return { command: "cmd", argsPrefix: ["/c", "node"] };
+  }
+  return { command: "node", argsPrefix: [] };
+}
+
+type ShimSpec = {
+  hookEvent: string;
+  handler: string;
+  timeoutSeconds: number;
+  loopLimit?: number;
+  matcher?: string;
+};
+
+const CURSOR_SHIM_SPECS: readonly ShimSpec[] = [
+  { hookEvent: "sessionStart", handler: "session-start", timeoutSeconds: 10 },
+  { hookEvent: "sessionEnd", handler: "session-end", timeoutSeconds: 10 },
+  { hookEvent: "preToolUse", handler: "tool-before", timeoutSeconds: 10 },
+  { hookEvent: "beforeShellExecution", handler: "tool-before", timeoutSeconds: 10 },
+  { hookEvent: "beforeMCPExecution", handler: "tool-before", timeoutSeconds: 10 },
+  { hookEvent: "beforeReadFile", handler: "tool-before", timeoutSeconds: 5 },
+  { hookEvent: "subagentStart", handler: "subagent-start", timeoutSeconds: 5 },
+  { hookEvent: "stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
+  { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" },
+];
+
+const CLAUDE_SHIM_SPECS: readonly ShimSpec[] = [
+  { hookEvent: "SessionStart", handler: "session-start", timeoutSeconds: 10 },
+  { hookEvent: "SessionEnd", handler: "session-end", timeoutSeconds: 10 },
+  { hookEvent: "PreToolUse", handler: "tool-before", timeoutSeconds: 10 },
+  { hookEvent: "SubagentStart", handler: "subagent-start", timeoutSeconds: 5 },
+  { hookEvent: "Stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
+  { hookEvent: "MessageDisplay", handler: "response-after", timeoutSeconds: 5 },
+];
+
+export function cursorShimEntries(launcher: string): WiringEntry[] {
+  const { command, argsPrefix } = shimCommand();
+  return CURSOR_SHIM_SPECS.map((spec) => ({
+    hookEvent: spec.hookEvent,
+    handler: spec.handler,
+    command,
+    args: [...argsPrefix, launcher, "shim", spec.handler],
+    timeoutSeconds: spec.timeoutSeconds,
+    ...(spec.loopLimit !== undefined ? { loopLimit: spec.loopLimit } : {}),
+    ...(spec.matcher !== undefined ? { matcher: spec.matcher } : {}),
+  }));
+}
+
+export function claudeShimEntries(launcher: string): WiringEntry[] {
+  return CLAUDE_SHIM_SPECS.map((spec) => ({
+    hookEvent: spec.hookEvent,
+    handler: spec.handler,
+    command: "node",
+    args: [launcher, "shim", spec.handler],
+    timeoutSeconds: spec.timeoutSeconds,
+    ...(spec.loopLimit !== undefined ? { loopLimit: spec.loopLimit } : {}),
+  }));
+}
+
+export const GITIGNORE_LINE = ".tlc/harness/state/";
+
+export function mergeGitignore(root: string): { text: string; changed: boolean } {
+  const path = join(root, ".gitignore");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const lines = existing.split("\n");
+  const alreadyPresent = lines.includes(GITIGNORE_LINE);
+  if (alreadyPresent) {
+    return { text: existing.endsWith("\n") || existing === "" ? existing : `${existing}\n`, changed: false };
+  }
+  lines.push(GITIGNORE_LINE);
+  const withoutTrailingBlank = lines.filter((line, index, all) => line.length > 0 || index < all.length - 1);
+  return { text: `${withoutTrailingBlank.join("\n").replace(/\n+$/, "")}\n`, changed: true };
+}
+
+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);
+  }
+  if (!flags.minimal && !flags.stdinJson && existsSync(projectConfigPath(root))) {
+    return JSON.parse(readFileSync(projectConfigPath(root), "utf8"));
+  }
+  return DEFAULTS;
+}
+
+export type ProviderPresence = { cursor: boolean; claude: boolean };
+
+export function detectProviders(dirs: { cursor?: string; claude?: string } = {}): ProviderPresence {
+  return {
+    cursor: existsSync(dirs.cursor ?? cursorConfigDir()),
+    claude: existsSync(dirs.claude ?? claudeConfigDir()),
+  };
+}
+
+export type InitPlan = {
+  policy: unknown;
+  cursorHooksDocument: unknown | null;
+  claudeHooksPreview: WiringEntry[] | null;
+  gitignoreLine: string;
+};
+
+export function buildPlan(
+  root: string,
+  flags: InitFlags,
+  stdinText: string | null,
+  presence: ProviderPresence,
+): InitPlan {
+  const policy = resolvePolicy(root, flags, stdinText);
+  const launcher = launcherPath();
+  return {
+    policy,
+    cursorHooksDocument: presence.cursor ? renderCursorHooksDocument(cursorShimEntries(launcher)) : null,
+    claudeHooksPreview: presence.claude ? claudeShimEntries(launcher) : null,
+    gitignoreLine: GITIGNORE_LINE,
+  };
+}
+
+export type ApplyOutcome = {
+  configPath: string;
+  cursor: { skipped: true } | { skipped: false; status: string; target: string };
+  claude: { skipped: true } | { skipped: false; status: string; target: string };
+};
+
+export function applyPlan(
+  root: string,
+  flags: InitFlags,
+  presence: ProviderPresence,
+  stdinText: string | null,
+): ApplyOutcome {
+  const policy = resolvePolicy(root, flags, stdinText);
+  const configPath = projectConfigPath(root);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+
+  const launcher = launcherPath();
+
+  const cursor = presence.cursor
+    ? (() => {
+        const result = applyCursorWiring(
+          {
+            target: join(root, ".cursor", "hooks.json"),
+            strategy: "replace",
+            entries: cursorShimEntries(launcher),
+          },
+          { force: flags.force },
+        );
+        return { skipped: false as const, status: result.status, target: result.target };
+      })()
+    : { skipped: true as const };
+
+  const claude = presence.claude
+    ? (() => {
+        const result = applyClaudeWiring(join(root, ".claude", "settings.json"), claudeShimEntries(launcher));
+        return {
+          skipped: false as const,
+          status: result.ok ? (result.changed ? "written" : "unchanged") : "failed",
+          target: join(root, ".claude", "settings.json"),
+        };
+      })()
+    : { skipped: true as const };
+
+  const gitignore = mergeGitignore(root);
+  writeFileSync(join(root, ".gitignore"), gitignore.text);
+
+  return { configPath, cursor, claude };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+export async function main(argv: string[]): Promise<void> {
+  const root = process.env.TLC_PROJECT_DIR ?? process.cwd();
+  const flags = parseFlags(argv);
+
+  if (!flags.dryRun && !flags.write) {
+    throw new UsageError(usageText());
+  }
+
+  const stdinText = flags.stdinJson ? await readStdin() : null;
+  const presence = detectProviders();
+
+  if (flags.dryRun) {
+    console.log(JSON.stringify(buildPlan(root, flags, stdinText, presence), null, 2));
+    return;
+  }
+
+  const outcome = applyPlan(root, flags, presence, stdinText);
+  console.log(`wrote ${outcome.configPath}`);
+  if (outcome.cursor.skipped) {
+    console.log("init: cursor not installed — skipped project hooks.json");
+  } else {
+    console.log(`hooks: ${outcome.cursor.status} ${outcome.cursor.target}`);
+  }
+  if (outcome.claude.skipped) {
+    console.log("init: claude not installed — skipped project settings.json");
+  } else {
+    console.log(`hooks: ${outcome.claude.status} ${outcome.claude.target}`);
+  }
+  console.log("updated .gitignore harness entries");
+}
+
+if (import.meta.main) {
+  try {
+    await main(process.argv.slice(2));
+  } catch (error) {
+    if (error instanceof UsageError) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+}

package/tools/install-runtime.ts

@@ -0,0 +1,164 @@
+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 { 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";
+
+/**
+ * why: an npm-installed copy lives under a directory npm replaces wholesale, so the runtime cannot keep its state
+ * there — measured on the packed tarball, which wrote `runtime-cache.json` inside the package on its first run.
+ * The package is the delivery vehicle; the runtime that hooks name stays at the conventional home, and this is
+ * what puts the code there ([/decisions/ad-056.md](/decisions/ad-056.md)).
+ *
+ * invariant: an entry here is replaced wholesale, so a file deleted upstream does not survive the update. Nothing
+ * outside this list is touched, which is what keeps `config.json`, `state/` and `flags/` the operator's.
+ */
+export const RUNTIME_PAYLOAD = [
+  "bin",
+  "capabilities",
+  "dist",
+  "docs",
+  "skills",
+  "src",
+  "tools",
+  "config.example.json",
+  "model-aliases.json",
+  "model-prices.cursor.json",
+  "model-prices.json",
+  "package.json",
+] as const;
+
+/** Never copied and never removed. The reason the split exists. */
+export const OPERATOR_OWNED = ["config.json", "state", "flags"] as const;
+
+/**
+ * Inside a payload entry and still not shipped.
+ *
+ * why: `tools/dev` holds the checks that validate *this* repository — its module boundaries, its screen contract,
+ * its decision records. A user's install has none of that to validate, and with Bun present the launcher resolves
+ * an entry straight from source, so copying them would put runnable repo-only commands on their machine. The
+ * clone route is different on purpose: a checkout is the repository, and a contributor needs them
+ * ([/decisions/ad-068.md](/decisions/ad-068.md)).
+ */
+export const NOT_SHIPPED = [join("tools", "dev"), join("tools", "__test__")] as const;
+
+export function isShipped(relativePath: string): boolean {
+  const normalised = relativePath.split(sep).join("/");
+  return !NOT_SHIPPED.some((excluded) => {
+    const prefix = excluded.split(sep).join("/");
+    return normalised === prefix || normalised.startsWith(`${prefix}/`);
+  });
+}
+
+export type InstallReport = {
+  kind: "copied" | "in-place";
+  source: string;
+  dest: string;
+  entries: string[];
+  missing: string[];
+};
+
+/** The physical location of the copy that launched us, which is not the home once an npm shim is driving one. */
+export function originRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const declared = env.TLC_ORIGIN?.trim();
+  if (declared && declared.length > 0) {
+    return resolve(declared);
+  }
+  // hazard: `runtimeHome()` reads `process.env` and would ignore the env passed in, which made this untestable
+  // and would have read the wrong home for any caller that supplies one.
+  const home = env.TLC_HOME?.trim();
+  return home && home.length > 0 ? resolve(home) : conventionalRuntimeHome();
+}
+
+export function installRuntime(source: string, dest: string): InstallReport {
+  if (resolve(source) === resolve(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: [] };
+  }
+  mkdirSync(dest, { recursive: true });
+  const entries: string[] = [];
+  const missing: string[] = [];
+  for (const entry of RUNTIME_PAYLOAD) {
+    const from = join(source, entry);
+    if (!existsSync(from)) {
+      missing.push(entry);
+      continue;
+    }
+    const to = join(dest, entry);
+    rmSync(to, { recursive: true, force: true });
+    cpSync(from, to, {
+      recursive: true,
+      filter: (src) => isShipped(relative(source, src)),
+    });
+    entries.push(entry);
+  }
+  // why: a directory with no `.git` used to classify as `unmanaged`, which doctor reports as a failure and update
+  // answers with "re-install with the one-liner". The marker is how the thing that created this directory says
+  // what it is, rather than leaving every later reader to guess from the contents.
+  writeFileSync(
+    join(dest, NPM_MARKER),
+    `Installed by \`tlc harness install\` from ${source}.\nUpdate with: npm i -g ${NPM_PACKAGE}@latest && tlc harness install\n`,
+    "utf8",
+  );
+  const config = join(dest, "config.json");
+  const example = join(dest, "config.example.json");
+  if (!existsSync(config) && existsSync(example)) {
+    writeFileSync(config, readFileSync(example, "utf8"), "utf8");
+  }
+  return { kind: "copied", source, dest, entries, missing };
+}
+
+export function installScreen(report: InstallReport): Screen {
+  if (report.kind === "in-place") {
+    return {
+      title: "harness install",
+      sections: [
+        { rows: [{ label: "runtime", value: `already at ${report.dest} — nothing to copy`, level: "ok" }] },
+      ],
+    };
+  }
+  const rows: Row[] = [
+    { label: "installed", value: `${report.entries.length} path(s) → ${report.dest}`, level: "ok" },
+    { label: "from", value: report.source },
+  ];
+  if (report.missing.length > 0) {
+    // why: a payload entry absent from the source is a packaging fault, not a passing install. `tools/` was
+    // missing from the published `files` list the first time this ran.
+    rows.push({
+      label: "packaging",
+      value: `MISSING from the source: ${report.missing.join(", ")}`,
+      level: "fail",
+    });
+  }
+  return { title: "harness install", sections: [{ rows }] };
+}
+
+export function installReportText(report: InstallReport, style: Style = PLAIN): string {
+  return render(installScreen(report), style);
+}
+
+/**
+ * hazard: not the resolved home. On the very first npm run nothing is installed yet, so the resolved home *is*
+ * the package — and asking it where to install would answer "here", which is the one place that cannot hold
+ * state. The conventional path is the answer unless the operator named one themselves.
+ */
+export function installDest(env: NodeJS.ProcessEnv = process.env): string {
+  // hazard: the destination cannot be carried on `TLC_HOME`. Setting that makes the launcher resolve the runtime
+  // to a directory that does not exist yet on a first install, and it then refuses for want of the bundles it was
+  // being asked to put there. A separate variable keeps resolution and destination independent.
+  const explicit = env.TLC_INSTALL_DEST?.trim();
+  if (explicit && explicit.length > 0) {
+    return resolve(explicit);
+  }
+  return runtimeHomeWasChosen(env) ? runtimeHome(env) : conventionalRuntimeHome();
+}
+
+if (import.meta.main) {
+  const source = originRoot();
+  const dest = installDest();
+  const report = installRuntime(source, dest);
+  console.log(installReportText(report, createStyle()));
+  process.exit(report.missing.length > 0 ? 1 : 0);
+}