iterate-harness 1.12.9 → 1.12.10

package/README.md

@@ -30,12 +30,14 @@ delegation logic used at install time and at runtime is the same:
    (overridable via `ITERATE_HARNESS_NPM_HOME`).
 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. 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.
+   automatically re-installs the matching harness version on the next run.
+   The preferred source is the official **PyPI** index: pip resolves
+   `iterate-harness==X.Y.Z` against your configured mirror (e.g.
+   `pypi.tuna.tsinghua.edu.cn`), so installs work even when GitHub is
+   unreachable or its TLS cert fails to verify. If PyPI is unavailable, the
+   wrapper falls back to the pre-built **wheel** on the GitHub release
+   (frontend assets baked in, like iterate-skill-installer ships pre-wrapped
+   assets), then the pinned **source archive** as a final resort.
 4. Delegates to the venv's real `ih` executable with argv, stdio, signals and
    exit codes forwarded.
 

package/README.zh-CN.md

@@ -27,10 +27,11 @@ harness 本身是**一个 Python 包**。这个 npm 包是一个薄分发包装
 2. 在 `~/.iterate-harness-npm/venv` 创建托管虚拟环境
    （可通过 `ITERATE_HARNESS_NPM_HOME` 覆盖）。
 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 缺失，再兑底使用锁定的**源码归档**。
+   总会安装 harness `v1.6.0`。升级 npm 包会在下次运行时自动重装对应的 harness 版本。
+   **首选官方 PyPI 索引**：pip 会按你配置的镜像源（如 `pypi.tuna.tsinghua.edu.cn`）
+   解析 `iterate-harness==X.Y.Z`，即使 GitHub 不可达或 TLS 证书校验失败也能安装。
+   若 PyPI 不可用，再兑底 GitHub release 上的**预构建 wheel**（已内置编译好的前端
+   资源——与 iterate-skill-installer 分发预打包资源一致），最后才用锁定的**源码归档**。
 4. 代理调用 venv 里真正的 `ih` 可执行文件，转发 argv、stdio、信号与退出码。
 
 若 `npm install` 期间无法完成安装（无 Python、无网络，或

package/lib/bootstrap.js

@@ -8,17 +8,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 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.
+ *    (lockstep: npm 1.12.9 installs harness v1.12.9). The preferred source is
+ *    the official **PyPI** index — pip resolves `iterate-harness==X.Y.Z` against
+ *    the user's configured mirror (e.g. `pypi.tuna.tsinghua.edu.cn`), so it
+ *    works even when GitHub is unreachable or its TLS cert fails to verify.
+ *    If PyPI is unavailable, the wrapper falls back to the pre-built GitHub
+ *    **wheel** release asset (frontend dist baked in, like iterate-skill-
+ *    installer ships pre-wrapped assets), pip-installing it directly and, if
+ *    pip's trust store is broken (common on macOS python.org builds), retrying
+ *    by downloading the wheel with Node's own https stack — and, failing that,
+ *    with curl (system trust store) — then pip-installing the local file. If
+ *    the wheel is missing too, the worker falls back to the pinned source
+ *    archive as a final 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
@@ -60,6 +61,11 @@ 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 install channel: the official PyPI index. pip reads the user's
+// mirror config (e.g. `pypi.tuna.tsinghua.edu.cn`), so it stays fast and
+// stable even when GitHub is unreachable — unlike the GitHub wheel fallback.
+const PYPI_PACKAGE_NAME = "iterate-harness";
+
 // 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).
@@ -91,6 +97,12 @@ function wheelAssetUrl(version) {
   return `${HARNESS_RELEASE_DOWNLOAD_URL}/v${version}/${wheelAssetName(version)}`;
 }
 
+// PyPI package spec pinned to the version (e.g. `iterate-harness==1.12.9`).
+// pip resolves this against the user's configured index/mirror, not GitHub.
+function pypiInstallSpec(version) {
+  return `${PYPI_PACKAGE_NAME}==${version}`;
+}
+
 // Last-resort installable source: the pinned source archive (builds on pip).
 function releaseTarballUrl(version) {
   return `${HARNESS_REPO_ARCHIVE_URL}/v${version}.tar.gz`;
@@ -274,25 +286,17 @@ 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) {
+// Ordered install candidates, best-effort first:
+//   1. PyPI spec — pip installs via the user's mirror (stable, no GitHub).
+//   2. Pre-built wheel on the GitHub release (needs GitHub, but no source build).
+//   3. Pinned source archive on GitHub (last resort; pip builds from source).
+// An explicit env override short-circuits the chain (the user owns the source).
+function installCandidates(version, env) {
   const override = env ? env[INSTALL_URL_ENV_VAR] : undefined;
   if (override) {
-    return null;
+    return [override];
   }
-  return releaseTarballUrl(version);
+  return [pypiInstallSpec(version), wheelAssetUrl(version), releaseTarballUrl(version)];
 }
 
 // ---------------------------------------------------------------------------
@@ -421,41 +425,55 @@ async function downloadTarballTo(url, dest, deps) {
 
 async function installHarness(options) {
   const python = options.python;
-  const url = options.url;
   const homeDir = options.homeDir;
   const version = options.version;
+  const candidates = options.candidates;
   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;
 
+  if (!candidates || candidates.length === 0) {
+    throw new BootstrapError("no install candidate URLs were provided");
+  }
+
+  const failures = [];
+  for (const candidate of candidates) {
+    try {
+      if (isRemoteHttpUrl(candidate)) {
+        // HTTP(S) candidate: `pip` first, then node/curl download + local pip
+        // (survives broken Python TLS trust stores on macOS python.org builds).
+        await installRemoteArtifact(python, candidate, homeDir, version, runStepFn, downloader);
+      } else {
+        // Non-URL candidate (e.g. `iterate-harness==1.12.9` resolved by pip
+        // against the user's mirror): no artifact to download, just pip it.
+        runStepFn(python, pipInstallArgs(candidate));
+      }
+      return;
+    } catch (error) {
+      failures.push(`${candidate}: ${error.message}`);
+      process.stderr.write(
+        `[iterate-harness] install from "${candidate}" failed (${error.message}); ` +
+          "trying the next candidate ...\n"
+      );
+    }
+  }
+
+  throw new BootstrapError(`all install candidates failed:\n  ${failures.join("\n  ")}`);
+}
+
+// pip-install a downloadable HTTP artifact, retrying with a node/curl download
+// of the raw file + local pip install when pip's TLS trust store is broken.
+async function installRemoteArtifact(python, url, homeDir, version, runStepFn, downloader) {
   try {
     runStepFn(python, pipInstallArgs(url));
     return;
   } catch (primaryError) {
-    if (!isRemoteHttpUrl(url)) {
-      throw primaryError;
-    }
     process.stderr.write(
       `[iterate-harness] pip install from ${url} failed; retrying via direct download ...\n`
     );
-    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})`
-      );
-    }
-    runStepFn(python, pipInstallArgs(cachePath));
   }
+  const cachePath = downloadCachePath(homeDir, version, artifactExtensionFor(url));
+  await downloader(url, cachePath);
+  runStepFn(python, pipInstallArgs(cachePath));
 }
 
 async function bootstrap(homeDir, version, env) {
@@ -477,18 +495,13 @@ async function bootstrap(homeDir, version, env) {
     runStep(interpreter.command, [...interpreter.preArgs, "-m", "venv", venvDir]);
   }
 
-  const url = installUrl(version, env);
-  const fallbackUrl = installFallbackUrl(version, env);
+  const candidates = installCandidates(version, env);
   ui.step(`Installing iterate-harness ${version}`);
   await installHarness({
     python: executable.python,
-    url,
+    candidates,
     homeDir,
     version,
-    fallback:
-      fallbackUrl != null
-        ? { python: executable.python, url: fallbackUrl, homeDir, version }
-        : undefined,
   });
 
   const stampPath = path.join(homeDir, STAMP_FILE_NAME);
@@ -624,15 +637,16 @@ module.exports = {
   downloadFile,
   downloadTarballTo,
   ensureRuntime,
-  installFallbackUrl,
+  installCandidates,
   installHarness,
-  installUrl,
+  installRemoteArtifact,
   isRemoteHttpUrl,
   isSupportedPython,
   needsBootstrap,
   packageVersion,
   parsePythonVersion,
   pipInstallArgs,
+  pypiInstallSpec,
   pythonCandidates,
   releaseTarballUrl,
   reportBootstrapFailure,

package/package.json

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