threadlens 1.0.1 → 1.1.1

package/README.md

@@ -4,32 +4,76 @@ Local cross-harness search for coding-agent sessions.
 
 ```bash
 npm install -g threadlens
-threadlens start
 threadlens search "plunk otp"
+threadlens skill
 ```
 
-Or run it once without installing:
+Or run once without installing:
 
 ```bash
 npx threadlens search "plunk otp"
 ```
 
+## How it works
+
+This package ships a tiny JS shim (`bin/threadlens.js`) with no vendored Python.
+Installing it pulls in the matching pre-built native binary via npm's
+`optionalDependencies` mechanism — exactly the way esbuild distributes its binary.
+
+| Platform | Package pulled |
+|---|---|
+| macOS arm64 | `@moinulmoin/threadlens-darwin-arm64` |
+| macOS x64   | `@moinulmoin/threadlens-darwin-x64`   |
+| Linux x64 (glibc) | `@moinulmoin/threadlens-linux-x64-gnu` |
+
+The binary is a self-contained [PyInstaller](https://pyinstaller.org/) onedir
+bundle — no Python required on the host machine.
+
 ## Requirements
 
-threadlens is a pure-Python CLI (stdlib only). This npm package is a thin
-launcher that runs the bundled source with **your** Python, so it needs:
+- **Node.js 16+** (for the shim)
+- One of the supported platforms above
+- No Python required
 
-- **Python 3.10+** on your `PATH`
+## Override / escape hatches
 
-macOS and most Linux distros already ship `python3`. If yours doesn't, install
-Python, or use the Python-native distribution which can fetch Python for you:
+**Point at a custom binary:**
+```bash
+THREADLENS_BINARY=/path/to/threadlens threadlens search "..."
+```
+
+**Installed with `--omit=optional`?** The shim will print a clear error. Fix it:
+```bash
+npm install -g threadlens   # re-install without --omit=optional
+```
 
+**Unsupported platform or prefer Python?**
 ```bash
-uv tool install threadlens     # then run `threadlens`
-uvx threadlens search "..."    # run without installing
+uv tool install threadlens       # installs from PyPI, brings its own Python
+uvx threadlens search "..."      # run without installing
 ```
 
-Use a specific interpreter with `THREADLENS_PYTHON=/path/to/python`.
+Or download a release archive directly from
+<https://github.com/moinulmoin/threadlens/releases>.
+
+## Binary resolution order
+
+1. `THREADLENS_BINARY` environment variable (if set, used verbatim)
+2. Platform lookup: `${process.platform}-${process.arch}` → scoped package name
+3. `require.resolve('<pkg>/package.json')` to locate the package directory
+4. Execute `<pkgDir>/bin/threadlens/threadlens` with all args forwarded
+
+If step 2 or 3 fails, the shim exits 127 with a diagnostic message.
+
+## Development
+
+```bash
+# Regenerate platform package scaffolds and sync version from threadlens/__init__.py
+node scripts/sync.mjs
+
+# Run the shim unit tests (no binaries needed)
+node --test npm/test/shim.test.mjs
+```
 
 See the [project README](https://github.com/moinulmoin/threadlens#readme) for
-full usage.
+full usage and source.

package/bin/resolve.js

@@ -0,0 +1,85 @@
+"use strict";
+
+// Pure platform-to-binary resolution logic.
+// No side-effects; injectable for tests.
+
+const path = require("node:path");
+
+/** Maps ${platform}-${arch} -> optional-dependency package name. */
+const PLATFORM_MAP = {
+  "darwin-arm64": "@moinulmoin/threadlens-darwin-arm64",
+  "linux-x64":    "@moinulmoin/threadlens-linux-x64-gnu",
+};
+
+/**
+ * Resolve the absolute path to the threadlens native binary.
+ *
+ * All inputs are injectable so the function is unit-testable without real
+ * platform packages on disk.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.platform]  — defaults to process.platform
+ * @param {string}   [opts.arch]      — defaults to process.arch
+ * @param {object}   [opts.env]       — defaults to process.env
+ * @param {Function} [opts.resolver]  — defaults to require.resolve
+ * @returns {string} Absolute path to the executable.
+ * @throws {Error} err.code === "UNSUPPORTED_PLATFORM" | "MISSING_PACKAGE"
+ */
+function resolveBinary({ platform, arch, env, resolver } = {}) {
+  platform = platform !== undefined ? platform : process.platform;
+  arch     = arch     !== undefined ? arch     : process.arch;
+  env      = env      !== undefined ? env      : process.env;
+  resolver = resolver !== undefined ? resolver : require.resolve;
+
+  // Explicit override wins unconditionally.
+  if (env.THREADLENS_BINARY) {
+    return env.THREADLENS_BINARY;
+  }
+
+  const key = `${platform}-${arch}`;
+  const pkg = PLATFORM_MAP[key];
+
+  if (!pkg) {
+    throw Object.assign(
+      new Error(
+        [
+          `threadlens: unsupported platform "${key}".`,
+          "",
+          "Pre-built binaries are available for: darwin-arm64, darwin-x64, linux-x64.",
+          "Alternatives:",
+          "  uv tool install threadlens       # installs from PyPI (brings its own Python)",
+          '  uvx threadlens search "..."      # one-shot, no install',
+          "  https://github.com/moinulmoin/threadlens/releases  (release archives)",
+        ].join("\n")
+      ),
+      { code: "UNSUPPORTED_PLATFORM" }
+    );
+  }
+
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = resolver(`${pkg}/package.json`);
+  } catch (_) {
+    throw Object.assign(
+      new Error(
+        [
+          `threadlens: platform package "${pkg}" is not installed.`,
+          "",
+          "This usually means npm was invoked with --omit=optional (or --no-optional).",
+          "Fix it with one of:",
+          "  npm install -g threadlens         (re-install without --omit=optional)",
+          "  uv tool install threadlens         (install from PyPI instead)",
+          '  uvx threadlens search "..."        (run once without installing)',
+          "  https://github.com/moinulmoin/threadlens/releases  (download a release archive)",
+        ].join("\n")
+      ),
+      { code: "MISSING_PACKAGE" }
+    );
+  }
+
+  const pkgDir = path.dirname(pkgJsonPath);
+  // The onedir bundle is laid out as:  <pkgDir>/bin/threadlens/threadlens
+  return path.join(pkgDir, "bin", "threadlens", "threadlens");
+}
+
+module.exports = { PLATFORM_MAP, resolveBinary };

package/bin/threadlens.js

@@ -1,75 +1,29 @@
 #!/usr/bin/env node
 "use strict";
 
-// Thin launcher for the threadlens Python CLI.
+// Thin launcher — resolves the pre-built native binary for this platform
+// and exec's it, passing all arguments through verbatim.
 //
-// The real tool is pure-Python (stdlib only). This npm package vendors that
-// source under ./vendor and runs it with the user's own Python interpreter, so
-// `threadlens skill` keeps returning a real, copyable on-disk path (a zipapp
-// would hide those files inside an archive).
+// Set THREADLENS_BINARY=/path/to/binary to override the auto-resolved path.
 
 const { spawnSync } = require("node:child_process");
-const path = require("node:path");
+const { resolveBinary } = require("./resolve.js");
 
-// vendor/ contains the importable `threadlens` package directory.
-const vendorDir = path.join(__dirname, "..", "vendor");
-
-function isPython310(cmd) {
-  const probe =
-    "import sys; raise SystemExit(0 if sys.version_info[:2] >= (3, 10) else 1)";
-  const res = spawnSync(cmd, ["-c", probe], { stdio: "ignore" });
-  return res.status === 0;
-}
-
-function pickPython() {
-  const override = process.env.THREADLENS_PYTHON;
-  const candidates = override ? [override] : ["python3", "python"];
-  for (const cmd of candidates) {
-    try {
-      if (isPython310(cmd)) return cmd;
-    } catch (_) {
-      // not found / not executable; try the next candidate
-    }
-  }
-  return null;
+let bin;
+try {
+  bin = resolveBinary();
+} catch (err) {
+  process.stderr.write(err.message + "\n");
+  process.exit(127);
 }
 
-const python = pickPython();
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
 
-if (!python) {
+if (result.error) {
   process.stderr.write(
-    [
-      "threadlens: could not find Python 3.10+ on your PATH.",
-      "",
-      "threadlens is a Python CLI; this npm package is a thin launcher.",
-      "Fix it with either:",
-      "",
-      "  • Install Python 3.10+  (https://www.python.org/downloads or `brew install python`)",
-      "  • Or install the native build with uv (it can fetch Python for you):",
-      "      uv tool install threadlens     # then run `threadlens`",
-      '      uvx threadlens search "..."    # run without installing',
-      "",
-      "Already have a specific interpreter? Point at it:",
-      "      THREADLENS_PYTHON=/path/to/python threadlens ...",
-      "",
-    ].join("\n")
+    `threadlens: failed to launch binary (${bin}): ${result.error.message}\n`
   );
-  process.exit(127);
-}
-
-const env = { ...process.env, PYTHONDONTWRITEBYTECODE: "1" };
-env.PYTHONPATH = env.PYTHONPATH
-  ? vendorDir + path.delimiter + env.PYTHONPATH
-  : vendorDir;
-
-const res = spawnSync(python, ["-m", "threadlens", ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env,
-});
-
-if (res.error) {
-  process.stderr.write(`threadlens: failed to launch Python: ${res.error.message}\n`);
   process.exit(1);
 }
 
-process.exit(res.status === null ? 1 : res.status);
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "threadlens",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Local cross-harness search for agent threads",
   "bin": {
     "threadlens": "bin/threadlens.js"
   },
   "files": [
-    "bin/",
-    "vendor/"
+    "bin"
   ],
   "engines": {
     "node": ">=16"
   },
   "scripts": {
-    "prepack": "node scripts/sync.mjs"
+    "sync": "node scripts/sync.mjs",
+    "prepare": "node scripts/sync.mjs"
   },
   "keywords": [
     "agents",
@@ -26,11 +26,6 @@
     "cursor"
   ],
   "license": "MIT",
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/moinulmoin/threadlens.git"
@@ -38,5 +33,9 @@
   "homepage": "https://github.com/moinulmoin/threadlens#readme",
   "bugs": {
     "url": "https://github.com/moinulmoin/threadlens/issues"
+  },
+  "optionalDependencies": {
+    "@moinulmoin/threadlens-darwin-arm64": "1.1.1",
+    "@moinulmoin/threadlens-linux-x64-gnu": "1.1.1"
   }
 }

package/vendor/threadlens/__init__.py

@@ -1,4 +0,0 @@
-"""Local cross-harness search for agent threads."""
-
-__version__ = "1.0.1"
-

package/vendor/threadlens/__main__.py

@@ -1,6 +0,0 @@
-from .cli import main
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
-