iterate-harness 1.12.8 → 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.
 
@@ -44,6 +46,21 @@ If the install during `npm install` can't complete (no Python, no network, or
 the npm install, and `ih` still installs on its first run — a lazy fallback
 keeps the package usable either way.
 
+## Interactive experience
+
+`ih` greets you with a cyan **ITERATE** ASCII banner on every run (claude-code
+style), and the first install runs an **interactive wizard** like
+iterate-skill-installer:
+
+- It prints an "Installing" box with the pinned version and runtime location.
+- It asks `Install iterate-harness vX.Y.Z ...? [Y/n]` before downloading —
+  decline and it exits cleanly (code 0) instead of failing.
+- When done, it prints a "Done" box with getting-started tips (`ih --help`,
+  `ih status`, `ih iterate --help`).
+
+All UI output goes to **stderr**, so `ih --version | jq '...'` still gives you
+clean machine-readable stdout.
+
 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

@@ -27,16 +27,31 @@ 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、无网络，或
 `ITERATE_HARNESS_SKIP_INSTALL=1`），钩子只会打印提示而不让 npm 安装失败，
 `ih` 会在首次运行时补装——惰性兑底保证两种情况下包都可用。
 
+## 交互式体验
+
+每次运行 `ih`，都会出现青色 **ITERATE** ASCII 横幅（claude-code 风格）；首次安装
+会像 iterate-skill-installer 一样进入**交互式向导**：
+
+- 先打印 "Installing" 信息框，包含锁定的版本号与运行时目录。
+- 下载前询问 `Install iterate-harness vX.Y.Z ...? [Y/n]`——选否会以 0 退出码
+  干净退出而不是报错。
+- 装完打印 "Done" 信息框，附上快速上手提示（`ih --help`、`ih status`、
+  `ih iterate --help`）。
+
+所有交互输出都写到 **stderr**，所以 `ih --version | jq '...'` 得到的 stdout
+依旧干净、可机器解析。
+
 React TUI 的前端依赖（`node_modules`）会在首次启动 TUI 时由 harness 自动安装——
 npm 用户必然有 Node，所以 TUI 始终可用。
 

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
@@ -36,6 +37,8 @@ const https = require("https");
 const os = require("os");
 const path = require("path");
 
+const ui = require("./ui");
+
 // ---------------------------------------------------------------------------
 // Constants (no magic strings below — everything is named here)
 // ---------------------------------------------------------------------------
@@ -58,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).
@@ -72,6 +80,10 @@ const IS_WINDOWS = process.platform === "win32";
 
 class BootstrapError extends Error {}
 
+// Thrown when the user declines the interactive install wizard. Treated as a
+// graceful "nothing to do" exit (code 0), never as a failure.
+class CancelledError extends Error {}
+
 // ---------------------------------------------------------------------------
 // Pure helpers (unit-tested in test/bootstrap.test.js)
 // ---------------------------------------------------------------------------
@@ -85,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`;
@@ -268,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) {
+// 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 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);
+  return [pypiInstallSpec(version), wheelAssetUrl(version), releaseTarballUrl(version)];
 }
 
 // ---------------------------------------------------------------------------
@@ -415,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) {
@@ -467,30 +491,27 @@ async function bootstrap(homeDir, version, env) {
     fs.rmSync(venvDir, { recursive: true, force: true });
   }
   if (!fs.existsSync(activateMarker)) {
-    process.stderr.write(`[iterate-harness] creating virtualenv at ${venvDir} ...\n`);
+    ui.step(`Creating virtualenv at ${venvDir}`);
     runStep(interpreter.command, [...interpreter.preArgs, "-m", "venv", venvDir]);
   }
 
-  const url = installUrl(version, env);
-  const fallbackUrl = installFallbackUrl(version, env);
-  process.stderr.write(`[iterate-harness] installing iterate-harness ${version} ...\n`);
+  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);
   fs.writeFileSync(stampPath, `${version}\n`, "utf8");
+  ui.success(`iterate-harness ${version} installed`);
 }
 
-async function ensureRuntime(env) {
+async function ensureRuntime(env, options) {
   const environment = env || process.env;
+  const opts = options || {};
   const version = packageVersion();
   const homeDir = runtimeHomeDir(environment);
   const venvDir = path.join(homeDir, VENV_DIR_NAME);
@@ -503,7 +524,30 @@ async function ensureRuntime(env) {
     : "";
 
   if (!skipInstall && needsBootstrap(stampContent, version)) {
+    if (opts.interactive) {
+      // Interactive install wizard: ask the user before downloading.
+      const confirmed = await ui.askYesNo(
+        `Install iterate-harness v${version} into ${homeDir}?`,
+        true
+      );
+      if (!confirmed) {
+        throw new CancelledError(
+          "Skipped installing iterate-harness. Re-run `ih` whenever you are ready."
+        );
+      }
+      ui.frameSection("Installing", [
+        `\x1b[36m◆\x1b[0m Version: v${version}`,
+        `\x1b[36m◆\x1b[0m Runtime:  ${homeDir}`,
+      ]);
+    }
     await bootstrap(homeDir, version, environment);
+    if (opts.interactive) {
+      ui.frameSection("Done", [
+        `\x1b[32m✓\x1b[0m iterate-harness v${version} installed`,
+        `  Run \x1b[36mih --help\x1b[0m to see all commands.`,
+        `  Try \x1b[36mih status\x1b[0m or \x1b[36mih iterate --help\x1b[0m to get started.`,
+      ]);
+    }
   }
 
   if (!fs.existsSync(executable.ih)) {
@@ -530,10 +574,19 @@ function reportBootstrapFailure(error) {
 }
 
 async function runHarness(args, env) {
+  // Print the banner on every run (claude-code style). Skipped automatically
+  // when stderr is not a TTY (e.g. piped output), so `ih --version | jq` stays clean.
+  ui.printBanner();
+
   let target;
   try {
-    target = await ensureRuntime(env);
+    target = await ensureRuntime(env, { interactive: true });
   } catch (error) {
+    if (error instanceof CancelledError) {
+      ui.info(error.message);
+      process.exit(0);
+      return;
+    }
     reportBootstrapFailure(error);
     process.exit(1);
     return;
@@ -567,6 +620,7 @@ async function runHarness(args, env) {
 
 module.exports = {
   BootstrapError,
+  CancelledError,
   DEFAULT_ARTIFACT_EXT,
   MAX_DOWNLOAD_REDIRECTS,
   MIN_PYTHON_MAJOR,
@@ -583,15 +637,16 @@ module.exports = {
   downloadFile,
   downloadTarballTo,
   ensureRuntime,
-  installFallbackUrl,
+  installCandidates,
   installHarness,
-  installUrl,
+  installRemoteArtifact,
   isRemoteHttpUrl,
   isSupportedPython,
   needsBootstrap,
   packageVersion,
   parsePythonVersion,
   pipInstallArgs,
+  pypiInstallSpec,
   pythonCandidates,
   releaseTarballUrl,
   reportBootstrapFailure,

package/lib/ui.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/*
+ * Terminal UI helpers for the iterate-harness npm wrapper.
+ *
+ * Mirrors the style of iterate-skill-installer's interactive installer:
+ *   - ASCII banner (ITERATE brand)
+ *   - Colored step/success/warning/error/info prefixes
+ *   - Framed section box for summary
+ *   - Yes/no prompt for interactive choices
+ *
+ * Every function writes to stderr so piped stdout (e.g. `ih --version | jq`)
+ * is never polluted with UI noise. Non-TTY stderr silently skips the banner.
+ */
+
+const readline = require("node:readline");
+
+const ITERATE_BANNER = [
+  "██╗████████╗███████╗██████╗  █████╗ ████████╗███████╗",
+  "██║╚══██╔══╝██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝",
+  "██║   ██║   █████╗  ██████╔╝███████║   ██║   █████╗  ",
+  "██║   ██║   ██╔══╝  ██╔══██╗██╔══██║   ██║   ██╔══╝  ",
+  "██║   ██║   ███████╗██║  ██║██║  ██║   ██║   ███████╗",
+  "╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝",
+];
+
+function printBanner() {
+  if (!process.stderr.isTTY) return;
+  console.error();
+  for (const line of ITERATE_BANNER) {
+    console.error(`\x1b[36m${line}\x1b[0m`);
+  }
+  console.error(`\x1b[36m  iterate-harness\x1b[0m\x1b[2m · jingzhao-l/iterate-harness\x1b[0m`);
+  console.error();
+}
+
+function info(message) {
+  console.error(`\x1b[34mℹ\x1b[0m  ${message}`);
+}
+
+function success(message) {
+  console.error(`\x1b[32m✓\x1b[0m  ${message}`);
+}
+
+function warning(message) {
+  console.error(`\x1b[33m⚠\x1b[0m  ${message}`);
+}
+
+function error(message) {
+  console.error(`\x1b[31m✗\x1b[0m  ${message}`);
+}
+
+function step(message) {
+  console.error(`\x1b[36m◆\x1b[0m  ${message}`);
+}
+
+function hint(message) {
+  console.error(`\x1b[2m   ${message}\x1b[0m`);
+}
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function frameSection(title, lines) {
+  const maxLen = Math.max(
+    title.length,
+    ...lines.map((l) => stripAnsi(l).length),
+  );
+  const innerWidth = maxLen + 2;
+  const top = `┌─ ${title} ${"─".repeat(Math.max(0, innerWidth - title.length - 2))}┐`;
+  const bottom = `└${"─".repeat(innerWidth + 1)}┘`;
+  console.error(top);
+  for (const line of lines) {
+    const visibleLen = stripAnsi(line).length;
+    const padding = " ".repeat(Math.max(0, innerWidth - visibleLen));
+    console.error(`│ ${line}${padding}│`);
+  }
+  console.error(bottom);
+}
+
+function askYesNo(question, defaultNo = false) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const hint = defaultNo ? "[y/N]" : "[Y/n]";
+    rl.question(`\x1b[36m◆\x1b[0m  ${question} ${hint} `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === "y" || a === "yes") resolve(true);
+      else if (a === "n" || a === "no") resolve(false);
+      else resolve(defaultNo);
+    });
+  });
+}
+
+module.exports = {
+  ITERATE_BANNER,
+  printBanner,
+  info,
+  success,
+  warning,
+  error,
+  step,
+  hint,
+  stripAnsi,
+  frameSection,
+  askYesNo,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-harness",
-  "version": "1.12.8",
+  "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",

package/scripts/postinstall.js

@@ -15,23 +15,21 @@
 "use strict";
 
 const { ensureRuntime, reportBootstrapFailure, SKIP_INSTALL_ENV_VAR } = require("../lib/bootstrap");
+const ui = require("../lib/ui");
 
 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"
-    );
+    ui.warning(`Skipped install during npm install (${SKIP_INSTALL_ENV_VAR}=1); harness installs on the first \`ih\` run.`);
     return;
   }
   try {
     await ensureRuntime();
-    process.stderr.write("[iterate-harness] harness installed during npm install.\n");
+    ui.success("iterate-harness installed during npm install — `ih` is ready to use.");
   } 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"
+    ui.warning(
+      "Could not install the harness during npm install (see above). " +
+        "It will be retried automatically on the first `ih` run."
     );
   }
 }