iterate-harness 1.12.7 → 1.12.9

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,35 @@ 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.
+
+## 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

@@ -19,19 +19,38 @@ 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` 会在首次运行时补装——惰性兑底保证两种情况下包都可用。
+
+## 交互式体验
+
+每次运行 `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

@@ -36,6 +36,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)
 // ---------------------------------------------------------------------------
@@ -72,6 +74,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)
 // ---------------------------------------------------------------------------
@@ -467,13 +473,13 @@ 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`);
+  ui.step(`Installing iterate-harness ${version}`);
   await installHarness({
     python: executable.python,
     url,
@@ -487,10 +493,12 @@ async function bootstrap(homeDir, version, env) {
 
   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 +511,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 +561,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 +607,7 @@ async function runHarness(args, env) {
 
 module.exports = {
   BootstrapError,
+  CancelledError,
   DEFAULT_ARTIFACT_EXT,
   MAX_DOWNLOAD_REDIRECTS,
   MIN_PYTHON_MAJOR,

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,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.9",
+  "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,40 @@
+#!/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");
+const ui = require("../lib/ui");
+
+async function main() {
+  if (process.env[SKIP_INSTALL_ENV_VAR] === "1") {
+    ui.warning(`Skipped install during npm install (${SKIP_INSTALL_ENV_VAR}=1); harness installs on the first \`ih\` run.`);
+    return;
+  }
+  try {
+    await ensureRuntime();
+    ui.success("iterate-harness installed during npm install — `ih` is ready to use.");
+  } catch (error) {
+    reportBootstrapFailure(error);
+    ui.warning(
+      "Could not install the harness during npm install (see above). " +
+        "It will be retried automatically on the first `ih` run."
+    );
+  }
+}
+
+main().catch((error) => {
+  reportBootstrapFailure(error);
+  process.exit(0);
+});