tokenjam 0.6.9 → 0.6.11

package/bin/tj.js

@@ -31,9 +31,19 @@
  * tokenjam==<version>` / `--spec tokenjam==<version>` to this wrapper's OWN
  * version (kept in sync with the release tag by publish-npm.yml's `npm
  * version ${GITHUB_REF_NAME#v}` step) forces the resolver past that shortcut,
- * so `npx tokenjam` always runs the release it shipped with. If the pinned
- * spec can't be resolved yet (this wrapper published slightly ahead of PyPI
- * propagation), we fall back to the unpinned form rather than fail outright.
+ * so `npx tokenjam` always runs the release it shipped with.
+ *
+ * Fail-closed on an unresolved pin: publish-npm.yml's wrapper job now blocks
+ * on the matching PyPI release actually being visible before it publishes
+ * this wrapper, so "pinned spec doesn't resolve" should no longer happen in
+ * the ordinary run. Silently falling back to the unpinned form here traded a
+ * loud, correct, RETRYABLE failure for a silent PERMANENT one: uv/pipx cache
+ * whatever the unpinned spec resolves to and never re-resolve on their own,
+ * so one unlucky run during any remaining propagation gap left a stale
+ * version cached forever — surfacing as "0.6.2 shipped a palette rework but
+ * npx still shows the old colors" with no obvious cause. A resolution
+ * failure is now reported and the next runner (or an already-installed PATH
+ * `tj`) is tried instead — never a silent unpinned run.
  *
  * Staleness note: pinning only fixes what THIS wrapper runs. A bare `tj`
  * invoked directly (no `npx`) still runs whatever was separately installed
@@ -44,6 +54,7 @@
 "use strict";
 
 const { spawnSync } = require("child_process");
+const fs = require("fs");
 const path = require("path");
 
 // PyPI package name vs. command name differ (`tokenjam` ships the `tj` script),
@@ -102,6 +113,43 @@ function resolves(bin, args) {
   return probe.status === 0;
 }
 
+// Resolve `bin` to an absolute path the way the OS would launch it, without
+// spawning it — a plain PATH walk, no shell involved.
+function resolveOnPath(bin) {
+  const dirs = (process.env.PATH || "").split(path.delimiter);
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";")
+      : [""];
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        // not here, keep looking
+      }
+    }
+  }
+  return null;
+}
+
+// True when `candidatePath` resolves (through symlinks) to this very file.
+// `npx` symlinks this package's own `tj`/`tokenjam` bin into a temp bin dir
+// and puts that dir on PATH, so a naive "is tj on PATH" probe finds
+// ourselves — re-spawning that would recurse into this same wrapper forever
+// instead of ever reaching a real, separately-installed CLI.
+function isOwnShim(candidatePath) {
+  if (!candidatePath) return false;
+  try {
+    return fs.realpathSync(candidatePath) === fs.realpathSync(__filename);
+  } catch {
+    return false; // couldn't stat either side — don't claim a match
+  }
+}
+
 // --- stale shadowing install detection ------------------------------------
 //
 // Detect-and-tell only, per design: this never mutates anything and never
@@ -247,11 +295,36 @@ function main() {
     : { ...process.env, TJ_NPX_ZERO_INSTALL_REPORT: "1" };
 
   const version = ownVersion();
+  let sawUnresolvedPin = false;
 
   for (const { bin, pinnedPrefix, prefix } of runners(version)) {
-    if (!has(bin)) continue;
-    const args =
-      pinnedPrefix && resolves(bin, pinnedPrefix) ? pinnedPrefix : prefix;
+    if (bin === COMMAND) {
+      // The installed-CLI fallback: only real if it resolves to something
+      // OTHER than this wrapper (see isOwnShim above). Under npx, `has(bin)`
+      // alone would find our own re-exec'd shim and spawn it recursively.
+      const resolved = resolveOnPath(bin);
+      if (!resolved || isOwnShim(resolved)) continue;
+    } else if (!has(bin)) {
+      continue;
+    }
+
+    let args;
+    if (pinnedPrefix) {
+      if (!resolves(bin, pinnedPrefix)) {
+        // Fail closed: never silently drop to the unpinned spec (see the
+        // version-pinning comment at the top of this file for why). Report
+        // and move on to the next runner instead.
+        sawUnresolvedPin = true;
+        process.stderr.write(
+          `Note: ${bin} can't resolve tokenjam==${version} yet — skipping it rather than running an unpinned (potentially stale-cached) version.\n`
+        );
+        continue;
+      }
+      args = pinnedPrefix;
+    } else {
+      args = prefix;
+    }
+
     const result = spawnSync(bin, [...args, ...passthrough], {
       stdio: "inherit",
       env: childEnv,
@@ -261,6 +334,17 @@ function main() {
     process.exit(result.status === null ? 1 : result.status);
   }
 
+  if (sawUnresolvedPin) {
+    process.stderr.write(
+      "\n" +
+        `tj (TokenJam): couldn't resolve tokenjam==${version} on PyPI through uv/pipx, and no already-installed 'tj' was found on PATH.\n` +
+        "This should be transient — PyPI's CDN can lag briefly right after a release. Wait a minute and re-run `npx tokenjam`.\n" +
+        "If it persists, check https://pypi.org/project/tokenjam/#history for the release, or install an unpinned copy yourself:\n" +
+        "  uvx --from tokenjam tj   /   pipx run --spec tokenjam tj\n\n"
+    );
+    process.exit(1);
+  }
+
   process.stderr.write(
     "\n" +
       "tj (TokenJam) needs a Python runner to launch its CLI.\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenjam",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "Zero-install launcher for TokenJam (tj): npx tokenjam runs the Python CLI via uvx/pipx and reports the recurring mistakes your AI agent keeps repeating, no setup required.",
   "keywords": [
     "claude-code",