iterate-harness 1.12.4 → 1.12.6

package/README.md

@@ -26,10 +26,14 @@ On first run the wrapper:
    overridable via `ITERATE_HARNESS_PYTHON`).
 2. Creates a managed virtualenv at `~/.iterate-harness-npm/venv`
    (overridable via `ITERATE_HARNESS_NPM_HOME`).
-3. `pip install`s the harness **release tarball pinned to this npm package's
-   version** — npm `1.6.0` always installs harness `v1.6.0`. Upgrading the npm
-   package automatically re-installs the matching harness version on the next
-   run.
+3. `pip install`s the harness **pinned to this npm package's version** — npm
+   `1.6.0` always installs harness `v1.6.0`. Upgrading the npm package
+   automatically re-installs the matching harness version on the next run.
+   The preferred artifact is the **pre-built wheel** uploaded to the GitHub
+   release (`iterate_harness-<version>-py3-none-any.whl`, which already bundles
+   the compiled frontend assets — exactly like iterate-skill-installer ships
+   pre-wrapped assets). If the wheel is missing, the wrapper falls back to the
+   pinned **source archive** as a last resort.
 4. Delegates to the venv's real `ih` executable with argv, stdio, signals and
    exit codes forwarded.
 
@@ -50,7 +54,7 @@ have Node, so the TUI always works.
 | --- | --- |
 | `ITERATE_HARNESS_PYTHON` | Use this interpreter instead of auto-detection |
 | `ITERATE_HARNESS_NPM_HOME` | Runtime dir (default `~/.iterate-harness-npm`) |
-| `ITERATE_HARNESS_INSTALL_URL` | Install from this pip URL instead of the pinned release tarball (e.g. a git branch for testing) |
+| `ITERATE_HARNESS_INSTALL_URL` | Install from this pip URL instead of the pinned release wheel (e.g. a git branch for testing) |
 | `ITERATE_HARNESS_SKIP_INSTALL=1` | Skip bootstrap entirely; just run the already-installed `ih` |
 
 ## npx (no global install)

package/README.zh-CN.md

@@ -25,8 +25,11 @@ harness 本身是**一个 Python 包**。这个 npm 包是一个薄分发包装
    可通过 `ITERATE_HARNESS_PYTHON` 覆盖）。
 2. 在 `~/.iterate-harness-npm/venv` 创建托管虚拟环境
    （可通过 `ITERATE_HARNESS_NPM_HOME` 覆盖）。
-3. `pip install` **与本 npm 包版本锁定的** harness 发布 tarball —— npm 的 `1.6.0`
+3. `pip install` **与本 npm 包版本锁定的** harness 发布版本 —— npm 的 `1.6.0`
    总会安装 harness `v1.6.0`。升级 npm 包会在下次运行时自动重装对应的 harness 版本。
+   优先下载 GitHub 发布里的**预构建 wheel**（`iterate_harness-<version>-py3-none-any.whl`，
+   已内置编译好的前端资源——和 iterate-skill-installer 分发预打包资源一致）。
+   若 wheel 缺失，再兑底使用锁定的**源码归档**。
 4. 代理调用 venv 里真正的 `ih` 可执行文件，转发 argv、stdio、信号与退出码。
 
 React TUI 的前端依赖（`node_modules`）会在首次启动 TUI 时由 harness 自动安装——
@@ -44,7 +47,7 @@ npm 用户必然有 Node，所以 TUI 始终可用。
 | --- | --- |
 | `ITERATE_HARNESS_PYTHON` | 使用该解释器，而非自动检测 |
 | `ITERATE_HARNESS_NPM_HOME` | 运行时目录（默认 `~/.iterate-harness-npm`） |
-| `ITERATE_HARNESS_INSTALL_URL` | 从这个 pip URL 安装，而非锁定的发布 tarball（例如测试用的 git 分支） |
+| `ITERATE_HARNESS_INSTALL_URL` | 从这个 pip URL 安装，而非锁定的发布 wheel（例如测试用的 git 分支） |
 | `ITERATE_HARNESS_SKIP_INSTALL=1` | 完全跳过引导安装，直接运行已装好的 `ih` |
 
 ## npx（免全局安装）

package/lib/bootstrap.js

@@ -7,12 +7,18 @@
  *
  * 1. Resolve a Python interpreter >= 3.10 (env override first).
  * 2. Create/reuse the venv at ~/.iterate-harness-npm/venv.
- * 3. pip-install the harness release tarball pinned to THIS npm package's
- *    version (lockstep: npm 1.6.0 installs harness v1.6.0). When pip cannot
- *    fetch the tarball (typically a broken Python TLS trust store on macOS
- *    python.org builds), the wrapper retries by downloading the tarball with
- *    Node's own https stack — and, failing that, with curl (system trust
- *    store) — then pip-installs the local file.
+ * 3. pip-install the harness release pinned to THIS npm package's version
+ *    (lockstep: npm 1.12.6 installs harness v1.12.6). The preferred artifact is
+ *    the pre-built wheel uploaded to the GitHub release (it already contains
+ *    the compiled frontend assets, exactly like iterate-skill-installer ships
+ *    pre-wrapped assets). pip-installing the wheel avoids building from source,
+ *    which previously failed because the source archive has no frontend/web/
+ *    dist for pyproject.toml's force-include. When pip cannot fetch the wheel
+ *    (typically a broken Python TLS trust store on macOS python.org builds),
+ *    the wrapper retries by downloading the wheel with Node's own https stack
+ *    — and, failing that, with curl (system trust store) — then pip-installs
+ *    the local file. If the wheel is missing from the release entirely, the
+ *    wrapper falls back to the pinned source archive as a last resort.
  * 4. Stamp the installed version; a mismatch (npm upgrade) triggers a
  *    re-install on the next run.
  * 5. Spawn the venv's `ih` with argv/stdio/signals forwarded and the exit
@@ -48,7 +54,15 @@ const HOME_ENV_VAR = "ITERATE_HARNESS_NPM_HOME";
 const INSTALL_URL_ENV_VAR = "ITERATE_HARNESS_INSTALL_URL";
 const SKIP_INSTALL_ENV_VAR = "ITERATE_HARNESS_SKIP_INSTALL";
 
-const HARNESS_REPO_ARCHIVE_URL = "https://github.com/jingzhao-l/iterate-harness/archive/refs/tags";
+const HARNESS_GITHUB_REPO = "jingzhao-l/iterate-harness";
+const HARNESS_RELEASE_DOWNLOAD_URL = `https://github.com/${HARNESS_GITHUB_REPO}/releases/download`;
+const HARNESS_REPO_ARCHIVE_URL = `https://github.com/${HARNESS_GITHUB_REPO}/archive/refs/tags`;
+
+// Preferred installable artifact: the pre-built wheel (frontend dist baked in).
+const WHEEL_ASSET_SUFFIX = "-py3-none-any.whl";
+// Last-resort artifact: the pinned source archive (pip builds from source).
+const DEFAULT_ARTIFACT_EXT = ".tar.gz";
+const WHEEL_ARTIFACT_EXT = ".whl";
 
 const MIN_PYTHON_MAJOR = 3;
 const MIN_PYTHON_MINOR = 10;
@@ -62,6 +76,16 @@ class BootstrapError extends Error {}
 // Pure helpers (unit-tested in test/bootstrap.test.js)
 // ---------------------------------------------------------------------------
 
+function wheelAssetName(version) {
+  return `iterate_harness-${version}${WHEEL_ASSET_SUFFIX}`;
+}
+
+// Preferred installable source: the pre-built wheel (frontend dist baked in).
+function wheelAssetUrl(version) {
+  return `${HARNESS_RELEASE_DOWNLOAD_URL}/v${version}/${wheelAssetName(version)}`;
+}
+
+// Last-resort installable source: the pinned source archive (builds on pip).
 function releaseTarballUrl(version) {
   return `${HARNESS_REPO_ARCHIVE_URL}/v${version}.tar.gz`;
 }
@@ -125,8 +149,19 @@ function isRemoteHttpUrl(target) {
   return /^https?:\/\//i.test(String(target || ""));
 }
 
-function downloadCachePath(homeDir, version) {
-  return path.join(homeDir, TARBALL_CACHE_DIR_NAME, `iterate-harness-${version}.tar.gz`);
+// Infer the on-disk extension (for the cache file) from a download URL so
+// pip-installing the local copy keeps a correct .whl / .tar.gz suffix.
+function artifactExtensionFor(url) {
+  const match = /\.(tar\.gz|whl)$/i.exec(String(url || ""));
+  if (!match) {
+    return DEFAULT_ARTIFACT_EXT;
+  }
+  return match[1].toLowerCase() === "whl" ? WHEEL_ARTIFACT_EXT : DEFAULT_ARTIFACT_EXT;
+}
+
+function downloadCachePath(homeDir, version, extension) {
+  const ext = extension || DEFAULT_ARTIFACT_EXT;
+  return path.join(homeDir, TARBALL_CACHE_DIR_NAME, `iterate-harness-${version}${ext}`);
 }
 
 function pipInstallArgs(target) {
@@ -225,16 +260,29 @@ function runStep(command, args, options) {
   }
 }
 
+// Preferred install URL: the pre-built wheel pinned to this npm version.
+// An explicit env override always wins (e.g. a local dev wheel or git ref).
 function installUrl(version, env) {
   const override = env ? env[INSTALL_URL_ENV_VAR] : undefined;
   if (override) {
     return override;
   }
+  return wheelAssetUrl(version);
+}
+
+// Last-resort fallback URL: the pinned source archive. Only relevant when the
+// user did not override the install URL (an explicit override means they own
+// the source and no archive fallback should kick in).
+function installFallbackUrl(version, env) {
+  const override = env ? env[INSTALL_URL_ENV_VAR] : undefined;
+  if (override) {
+    return null;
+  }
   return releaseTarballUrl(version);
 }
 
 // ---------------------------------------------------------------------------
-// Tarball download fallback (Node-side TLS — survives broken pip trust stores)
+// Artifact download fallback (Node-side TLS — survives broken pip trust stores)
 // ---------------------------------------------------------------------------
 
 function downloadFile(url, dest, redirectBudget) {
@@ -353,14 +401,19 @@ async function downloadTarballTo(url, dest, deps) {
 }
 
 // ---------------------------------------------------------------------------
-// Install chain: pip from URL first, Node-download + local pip as fallback
+// Install chain: pip from URL (pre-built wheel) first, Node-download + local
+// pip as TLS fallback; missing wheel falls back to the source archive.
 // ---------------------------------------------------------------------------
 
 async function installHarness(options) {
   const python = options.python;
   const url = options.url;
+  const homeDir = options.homeDir;
+  const version = options.version;
   const runStepFn = options.runStepFn || runStep;
   const downloader = options.downloader || downloadTarballTo;
+  // Optional terminal fallback (e.g. the source archive if the wheel is missing).
+  const fallback = options.fallback;
 
   try {
     runStepFn(python, pipInstallArgs(url));
@@ -372,10 +425,17 @@ async function installHarness(options) {
     process.stderr.write(
       `[iterate-harness] pip install from ${url} failed; retrying via direct download ...\n`
     );
-    const cachePath = downloadCachePath(options.homeDir, options.version);
+    const cachePath = downloadCachePath(homeDir, version, artifactExtensionFor(url));
     try {
       await downloader(url, cachePath);
     } catch (downloadError) {
+      if (fallback) {
+        process.stderr.write(
+          `[iterate-harness] primary artifact unavailable (${downloadError.message}); ` +
+            `falling back to source archive ${fallback.url} ...\n`
+        );
+        return installHarness(fallback);
+      }
       throw new BootstrapError(
         `${primaryError.message}\n\n(direct-download fallback also failed: ${downloadError.message})`
       );
@@ -404,8 +464,18 @@ async function bootstrap(homeDir, version, env) {
   }
 
   const url = installUrl(version, env);
-  process.stderr.write(`[iterate-harness] pip installing iterate-harness ${version} ...\n`);
-  await installHarness({ python: executable.python, url, homeDir, version });
+  const fallbackUrl = installFallbackUrl(version, env);
+  process.stderr.write(`[iterate-harness] installing iterate-harness ${version} ...\n`);
+  await installHarness({
+    python: executable.python,
+    url,
+    homeDir,
+    version,
+    fallback:
+      fallbackUrl != null
+        ? { python: executable.python, url: fallbackUrl, homeDir, version }
+        : undefined,
+  });
 
   const stampPath = path.join(homeDir, STAMP_FILE_NAME);
   fs.writeFileSync(stampPath, `${version}\n`, "utf8");
@@ -489,6 +559,7 @@ async function runHarness(args, env) {
 
 module.exports = {
   BootstrapError,
+  DEFAULT_ARTIFACT_EXT,
   MAX_DOWNLOAD_REDIRECTS,
   MIN_PYTHON_MAJOR,
   MIN_PYTHON_MINOR,
@@ -496,12 +567,15 @@ module.exports = {
   HOME_ENV_VAR,
   INSTALL_URL_ENV_VAR,
   SKIP_INSTALL_ENV_VAR,
+  WHEEL_ASSET_SUFFIX,
+  artifactExtensionFor,
   detectPython,
   curlDownload,
   downloadCachePath,
   downloadFile,
   downloadTarballTo,
   ensureRuntime,
+  installFallbackUrl,
   installHarness,
   installUrl,
   isRemoteHttpUrl,
@@ -515,4 +589,6 @@ module.exports = {
   reportBootstrapFailure,
   runHarness,
   venvExecutablePaths,
+  wheelAssetName,
+  wheelAssetUrl,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-harness",
-  "version": "1.12.4",
+  "version": "1.12.6",
   "description": "npm distribution wrapper for iterate-harness — installs the Python harness (ih CLI) into a managed venv on first run and exposes it as a global command",
   "license": "MIT",
   "type": "commonjs",