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

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,61 @@ 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: both ends are named explicitly — `TLC_ORIGIN` is where the code comes from and `TLC_INSTALL_DEST` is
+ * where it goes — because each of them defaults to the same conventional home when left unsaid, which is exactly
+ * how this became a no-op.
+ */
+export function npmSyncPlan(
+  packageRoot: string,
+  dest: 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, TLC_INSTALL_DEST: dest },
+  };
+}
+
+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.
@@ -1293,9 +1348,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, home);
+    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);