iterate-harness 1.12.7 → 1.12.8

package/README.md

@@ -20,7 +20,9 @@ The harness itself is a **Python package**. This npm package is a thin
 distribution wrapper: it does not re-implement anything, it just makes `ih`
 installable with npm and keeps it up to date.
 
-On first run the wrapper:
+Right after `npm install` finishes, a `postinstall` hook creates the managed
+venv and installs the harness — so `ih` is ready to use immediately. The
+delegation logic used at install time and at runtime is the same:
 
 1. Finds a Python interpreter >= 3.10 (`py -3` / `python` / `python3`,
    overridable via `ITERATE_HARNESS_PYTHON`).
@@ -28,15 +30,20 @@ On first run the wrapper:
    (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 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
+   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.
 4. Delegates to the venv's real `ih` executable with argv, stdio, signals and
    exit codes forwarded.
 
+If the install during `npm install` can't complete (no Python, no network, or
+`ITERATE_HARNESS_SKIP_INSTALL=1`), the hook prints a notice without failing
+the npm install, and `ih` still installs on its first run — a lazy fallback
+keeps the package usable either way.
+
 The React TUI's frontend dependencies (`node_modules`) are installed
 automatically by the harness itself on first TUI launch — npm users always
 have Node, so the TUI always works.

package/README.zh-CN.md

@@ -19,19 +19,24 @@ ih --version        # 首次运行引导安装 Python 端，随后打印版本
 harness 本身是**一个 Python 包**。这个 npm 包是一个薄分发包装器：它不重新实现任何
 逻辑，只是让 `ih` 可以通过 npm 安装并保持更新。
 
-首次运行时，包装器会：
+`npm install` 一结束，`postinstall` 钩子就会创建托管虚拟环境并安装 harness——
+所以 `ih` 装完即用。安装时与运行时共用同一套代理逻辑：
 
 1. 找到一个 >= 3.10 的 Python 解释器（`py -3` / `python` / `python3`，
    可通过 `ITERATE_HARNESS_PYTHON` 覆盖）。
 2. 在 `~/.iterate-harness-npm/venv` 创建托管虚拟环境
    （可通过 `ITERATE_HARNESS_NPM_HOME` 覆盖）。
 3. `pip install` **与本 npm 包版本锁定的** harness 发布版本 —— npm 的 `1.6.0`
-   总会安装 harness `v1.6.0`。升级 npm 包会在下次运行时自动重装对应的 harness 版本。
+   总会安装 harness `v1.6.0`。升级 npm 包会自动重装对应的 harness 版本。
    优先下载 GitHub 发布里的**预构建 wheel**（`iterate_harness-<version>-py3-none-any.whl`，
    已内置编译好的前端资源——和 iterate-skill-installer 分发预打包资源一致）。
    若 wheel 缺失，再兑底使用锁定的**源码归档**。
 4. 代理调用 venv 里真正的 `ih` 可执行文件，转发 argv、stdio、信号与退出码。
 
+若 `npm install` 期间无法完成安装（无 Python、无网络，或
+`ITERATE_HARNESS_SKIP_INSTALL=1`），钩子只会打印提示而不让 npm 安装失败，
+`ih` 会在首次运行时补装——惰性兑底保证两种情况下包都可用。
+
 React TUI 的前端依赖（`node_modules`）会在首次启动 TUI 时由 harness 自动安装——
 npm 用户必然有 Node，所以 TUI 始终可用。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "iterate-harness",
-  "version": "1.12.7",
-  "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",
+  "version": "1.12.8",
+  "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",
   "repository": {
@@ -22,6 +22,7 @@
   "files": [
     "bin",
     "lib",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -33,6 +34,7 @@
     "installer"
   ],
   "scripts": {
-    "test": "node --test test/bootstrap.test.js"
+    "test": "node --test test/bootstrap.test.js test/postinstall.test.js",
+    "postinstall": "node scripts/postinstall.js"
   }
 }

package/scripts/postinstall.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/*
+ * npm `postinstall` hook for the iterate-harness wrapper.
+ *
+ * Runs right after `npm install`/`npm install -g` finishes, so the Python
+ * harness is ready the moment npm finishes — no wait on the first `ih` run.
+ *
+ * It deliberately NEVER fails the npm install: if the managed venv cannot be
+ * created here (e.g. no Python interpreter, no network, user opted out with
+ * ITERATE_HARNESS_SKIP_INSTALL=1), we print a notice and exit 0. The regular
+ * `ih` entry point keeps its own lazy-bootstrap fallback, so the first run
+ * still installs the harness on demand.
+ */
+
+"use strict";
+
+const { ensureRuntime, reportBootstrapFailure, SKIP_INSTALL_ENV_VAR } = require("../lib/bootstrap");
+
+async function main() {
+  if (process.env[SKIP_INSTALL_ENV_VAR] === "1") {
+    process.stderr.write(
+      `[iterate-harness] skipped install during npm install (${SKIP_INSTALL_ENV_VAR}=1); ` +
+        "the harness will be installed on the first `ih` run.\n"
+    );
+    return;
+  }
+  try {
+    await ensureRuntime();
+    process.stderr.write("[iterate-harness] harness installed during npm install.\n");
+  } catch (error) {
+    reportBootstrapFailure(error);
+    process.stderr.write(
+      "[iterate-harness] could not install the harness during npm install " +
+        "(see above). It will be retried automatically on the first `ih` run.\n"
+    );
+  }
+}
+
+main().catch((error) => {
+  reportBootstrapFailure(error);
+  process.exit(0);
+});