@tech-leads-club/harness-toolkit 0.3.2 → 0.3.4

package/bin/tlc-build.mjs

@@ -38,32 +38,21 @@ function sourcesIn(dir) {
 }
 
 /**
- * why one invocation with every entry: `--splitting` can only share a chunk between entries it sees together.
- * Built one at a time, each bundle inlined the whole core — measured, 24 bundles of ~257 KB each where more than
- * half of every one was byte-identical to its neighbour: 5.0 MB of `dist/` to carry 548 KB of distinct code
+ * hazard: this built every entry in ONE invocation with `--splitting`, which cut `dist/` from 5.0 MB to 548 KB —
+ * and shipped a broken CLI. A shared chunk carries the module body of anything two entries both import, including
+ * `bin/tlc-cli.ts`, and its `if (import.meta.main)` guard evaluates **true** inside that chunk. So running
+ * `install-runtime`, which imports the CLI for `NPM_MARKER` and `wireRuntime`, ran the CLI's `main` instead:
+ * `tlc harness install` printed `unknown:` and installed nothing. Published as 0.3.2 and caught by installing it
  * ([/decisions/ad-098.md](/decisions/ad-098.md)).
  *
- * invariant: the entry names stay flat and keep `.mjs`, because the launcher resolves `dist/<entry>.mjs` and the
- * hooks on every installed machine name the launcher. Chunks go in a subdirectory, so pruning an orphan entry
- * never has to tell the two apart.
+ * invariant: one bundle per entry, so a module that self-executes behind `import.meta.main` is inlined into the
+ * one program that is allowed to run it. Splitting can come back when no library module carries that guard, and
+ * not before — the size win is real and it is not worth a CLI that cannot install.
  */
-const CHUNK_DIR = "chunks";
-
-function build(targets) {
+function buildOne(source, out) {
   const result = spawnSync(
     "bun",
-    [
-      "build",
-      "--target=node",
-      "--format=esm",
-      "--splitting",
-      `--outdir=${dist}`,
-      "--entry-naming",
-      "[name].mjs",
-      "--chunk-naming",
-      `${CHUNK_DIR}/[name]-[hash].mjs`,
-      ...targets.map((target) => target.source),
-    ],
+    ["build", "--target=node", "--format=esm", `--outfile=${out}`, source],
     { stdio: "inherit" },
   );
   if (result.error?.code === "ENOENT") {
@@ -85,14 +74,11 @@ const targets = [
 mkdirSync(dist, { recursive: true });
 console.log(`tlc-build → ${dist}`);
 
-/**
- * hazard: chunk names carry a content hash, so a rebuild after a source change writes new ones and leaves the old
- * ones behind. Nothing references them and they ship anyway, growing the package with every build.
- *
- * invariant: the chunk directory is derived, so it is replaced rather than merged.
- */
-rmSync(join(dist, CHUNK_DIR), { recursive: true, force: true });
-build(targets);
+// invariant: a leftover chunk directory from the split build would ship for ever, referenced by nothing.
+rmSync(join(dist, "chunks"), { recursive: true, force: true });
+for (const target of targets) {
+  buildOne(target.source, join(dist, `${target.name}.mjs`));
+}
 
 // invariant: the launcher stays executable on a filesystem that tracks the bit. A no-op where it does not.
 try {

package/bin/tlc-cli.ts

@@ -904,6 +904,67 @@ export function resolveHarnessRoot(): string {
   }
 }
 
+/**
+ * Where npm put the package this command was installed from.
+ *
+ * hazard: `update` spawned `install-runtime` through the **runtime home's** launcher, so the tool resolved its
+ * source and its destination to the same directory and reported "already at … — nothing to copy". Measured on a
+ * scratch machine: `npm i -g` moved the package from 0.3.0 to 0.3.2 and the runtime the hooks execute stayed on
+ * 0.3.0. Every npm install that ever ran `update` bumped a package and kept its old code, while `doctor` said
+ * update "re-materialises this directory" ([/decisions/ad-098.md](/decisions/ad-098.md)).
+ *
+ * invariant: asked of npm rather than derived from this process. The CLI can be running from the runtime home,
+ * from the package, or from a linked clone, and only npm knows where it installs globally.
+ */
+export function globalPackageRoot(
+  probe = {
+    npmRoot: () => spawnSync("npm", ["root", "-g"], { encoding: "utf8", shell: true }).stdout ?? "",
+    exists: existsSync,
+  },
+): string | null {
+  // invariant: trimmed here rather than in the probe. `npm root -g` ends in a newline, and a path with a newline
+  // in it fails as a directory while reading as a plausible string in an error message.
+  const root = probe.npmRoot().trim();
+  if (root.length === 0) {
+    return null;
+  }
+  const candidate = join(root, ...NPM_PACKAGE.split("/"));
+  return probe.exists(candidate) ? candidate : null;
+}
+
+/**
+ * invariant: the *package's* launcher runs the materialisation, not the runtime home's. A release that fixes
+ * `install` has to be able to deliver that fix, and the old code cannot do it.
+ *
+ * invariant: only the **source** is named. `TLC_ORIGIN` is the one end this can know; the destination belongs to
+ * `installDest`, which exists because on a first npm run the *resolved* home is the package itself
+ * ([/decisions/ad-056.md](/decisions/ad-056.md)).
+ *
+ * hazard: the first version of this named the destination too, as `runtimeHome()`, and walked straight into that.
+ * On a clean machine it wrote `config.json` and the price catalogue into
+ * `node_modules/@tech-leads-club/harness-toolkit`, copied nothing, and then crashed writing hooks — Node refuses
+ * to strip types under `node_modules` ([/decisions/ad-098.md](/decisions/ad-098.md)).
+ */
+export function npmSyncPlan(packageRoot: string): {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+} {
+  return {
+    command: process.execPath,
+    args: [join(packageRoot, "bin", "tlc-exec.mjs"), "install-runtime"],
+    env: { TLC_ORIGIN: packageRoot },
+  };
+}
+
+export function npmRootFailureMessage(home: string): string {
+  return [
+    `update: npm reported no global root, so the package it just installed cannot be found.`,
+    `  The runtime at ${home} is unchanged — nothing was half-written.`,
+    `  Run \`npm root -g\` yourself; then \`npm i -g ${NPM_PACKAGE}@latest\` and \`tlc harness install\`.`,
+  ].join("\n");
+}
+
 /**
  * Everything an install has to put in place outside the runtime directory itself: the init skill where each
  * provider reads it, the user-level hooks, and a seeded config.
@@ -989,6 +1050,7 @@ export type Action =
   | { kind: "prices-refresh"; scope: string }
   | { kind: "prices-lookup"; modelId: string }
   | { kind: "entry"; entry: string; args: string[] }
+  | { kind: "install"; args: string[] }
   | { kind: "unknown"; cmd: string };
 
 export function route(args: string[]): Action {
@@ -1107,7 +1169,7 @@ export function route(args: string[]): Action {
     case "init":
       return { kind: "entry", entry: "init-project", args: args.slice(1) };
     case "install":
-      return { kind: "entry", entry: "install-runtime", args: args.slice(1) };
+      return { kind: "install", args: args.slice(1) };
     // why: the exit has to be as easy to find as the entrance. An operator who cannot get the harness off their
     // machine without hand-editing settings.json will not try it on a second one
     // ([/decisions/ad-066.md](/decisions/ad-066.md)).
@@ -1293,9 +1355,15 @@ function runUpdate(root: string): never {
       console.error(npmUpdateFailureMessage());
       process.exit(bump.status ?? 1);
     }
-    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+    const packageRoot = globalPackageRoot();
+    if (packageRoot === null) {
+      console.error(npmRootFailureMessage(home));
+      process.exit(1);
+    }
+    const plan = npmSyncPlan(packageRoot);
+    const sync = spawnSync(plan.command, plan.args, {
       stdio: "inherit",
-      env: process.env,
+      env: { ...process.env, ...plan.env },
     });
     if ((sync.status ?? 1) !== 0) {
       process.exit(sync.status ?? 1);
@@ -1390,6 +1458,31 @@ function runEntry(entry: string, toolArgs: string[], root: string): never {
   process.exit(r.status ?? 1);
 }
 
+/**
+ * `install`, which is the only entry that must run from the *package* rather than from the runtime it is about to
+ * replace.
+ *
+ * hazard: it went through `runEntry`, so the runtime home's own launcher ran the runtime home's own
+ * `install-runtime`, whose source and destination then resolved to the same directory. Measured: package at 0.3.3,
+ * runtime left on 0.3.1, with the command reporting success — and this is the recovery route the README and every
+ * failure message name ([/decisions/ad-098.md](/decisions/ad-098.md)).
+ *
+ * invariant: `--link` stays local. It points the runtime at the checkout the operator is standing in, so its
+ * source is the working directory and never the package.
+ */
+function runInstall(toolArgs: string[], root: string): never {
+  const packageRoot = toolArgs.includes("--link") ? null : globalPackageRoot();
+  if (packageRoot === null) {
+    runEntry("install-runtime", toolArgs, root);
+  }
+  const plan = npmSyncPlan(packageRoot);
+  const r = spawnSync(plan.command, [...plan.args, ...toolArgs], {
+    stdio: "inherit",
+    env: { ...process.env, ...plan.env, TLC_PROJECT_DIR: root },
+  });
+  process.exit(r.status ?? 1);
+}
+
 function main(argv: string[]): void {
   const root = resolveProjectRoot();
   const group = (argv[0] ?? "").toLowerCase();
@@ -1553,6 +1646,9 @@ function main(argv: string[]): void {
     case "prices-lookup":
       runEntry("price-lookup", json ? [action.modelId, JSON_FLAG] : [action.modelId], root);
       break;
+    case "install":
+      runInstall(action.args, root);
+      break;
     case "entry":
       runEntry(action.entry, json ? [...action.args, JSON_FLAG] : action.args, root);
       break;